nixos-config/profiles/opencode/skill/overseer-plan/references/implementation.md

Implementation Instructions

For the skill agent executing /overseer-plan. Follow this workflow exactly.

Step 1: Read Markdown File

Read the provided file using the Read tool.

Step 2: Extract Title

• Parse first # heading as title
• Strip "Plan: " prefix if present (case-insensitive)
• Fallback: use filename without extension

Step 3: Create Milestone via MCP

Basic creation:

const milestone = await tasks.create({
  description: "<extracted-title>",
  context: `<full-markdown-content>`,
  priority: <priority-if-provided-else-3>
});
return milestone;

With --parent option:

const task = await tasks.create({
  description: "<extracted-title>",
  context: `<full-markdown-content>`,
  parentId: "<parent-id>",
  priority: <priority-if-provided-else-3>
});
return task;

Capture returned task ID for subsequent steps.

Step 4: Analyze Plan Structure

Breakdown Indicators

1. Numbered/bulleted implementation lists (3-7 items)

   ## Implementation
   1. Create database schema
   2. Build API endpoints
   3. Add frontend components
   

2. Clear subsections under implementation/tasks/steps

   ### 1. Backend Changes
   - Modify server.ts
   
   ### 2. Frontend Updates
   - Update login form
   

3. File-specific sections

   ### `src/auth.ts` - Add JWT validation
   ### `src/middleware.ts` - Create auth middleware
   

4. Sequential phases

   **Phase 1: Database Layer**
   **Phase 2: API Layer**
   

Do NOT Break Down When

• Only 1-2 steps/items
• Plan is a single cohesive fix
• Content is exploratory ("investigate", "research")
• Work items inseparable
• Plan very short (<10 lines)

Step 5: Validate Atomicity & Acceptance Criteria

For each proposed task, verify:

• Atomic: Can be completed in single commit
• Validated: Has clear acceptance criteria

If task too large -> split further. If no validation -> add to context:

Done when: <specific observable criteria>

Examples of good acceptance criteria:

• "Done when: npm test passes, new migration applied"
• "Done when: API returns 200 with expected payload"
• "Done when: Component renders without console errors"
• "Done when: Type check passes (tsc --noEmit)"

Step 6: Oracle Review

Before creating tasks, invoke Oracle to review the proposed breakdown.

Prompt Oracle with:

Review this task breakdown for "<milestone>":

1. <task> - Done when: <criteria>
2. <task> - Done when: <criteria>
...

Check:
- Are tasks truly atomic (single commit)?
- Is validation criteria clear and observable?
- Does milestone deliver demoable increment?
- Missing dependencies/blockers?
- Any tasks that should be split or merged?

Incorporate Oracle's feedback, then proceed to create tasks.

Step 7: Create Subtasks (If Breaking Down)

Extract for Each Subtask

1. Description: Strip numbering, keep concise (1-10 words), imperative form
2. Context: Section content + "Part of [milestone description]" + acceptance criteria

Flat Breakdown

const subtasks = [
  { description: "Create database schema", context: "Schema for users/tokens. Part of 'Add Auth'.\n\nDone when: Migration runs, tables exist with FK constraints." },
  { description: "Build API endpoints", context: "POST /auth/register, /auth/login. Part of 'Add Auth'.\n\nDone when: Endpoints return expected responses, tests pass." }
];

const created = [];
for (const sub of subtasks) {
  const task = await tasks.create({
    description: sub.description,
    context: sub.context,
    parentId: milestone.id
  });
  created.push(task);
}
return { milestone: milestone.id, subtasks: created };

Epic-Level Breakdown (phases with sub-items)

// Create phase as task under milestone
const phase = await tasks.create({
  description: "Backend Infrastructure",
  context: "Phase 1 context...",
  parentId: milestoneId
});

// Create subtasks under phase
for (const item of phaseItems) {
  await tasks.create({
    description: item.description,
    context: item.context,
    parentId: phase.id
  });
}

Step 8: Report Results

Subtasks Created

Created milestone <id> from plan

Analyzed plan structure: Found <N> distinct implementation steps
Created <N> subtasks:
- <id>: <description>
- <id>: <description>
...

View structure: execute `await tasks.list({ parentId: "<id>" })`

No Breakdown

Created milestone <id> from plan

Plan describes a cohesive single task. No subtask breakdown needed.

View task: execute `await tasks.get("<id>")`

Epic-Level Breakdown

Created milestone <id> from plan

Analyzed plan structure: Found <N> major phases
Created as milestone with <N> tasks:
- <id>: <phase-name> (<M> subtasks)
- <id>: <phase-name> (<M> subtasks)
...

View structure: execute `await tasks.list({ parentId: "<id>" })`