Implement Plan

Implement phases from: $ARGUMENTS/plan.md

Architecture

This skill is a thin dispatcher. It does NOT read references, extract patterns, or implement code. Builders handle implementation, validators handle review, and auditors handle cross-phase analysis.

All agents are ephemeral. Each gets a fresh 200K context and is shut down after its cycle. This prevents context contamination, ensures skill instructions are never compacted, and eliminates bottlenecks.

Processing Model

for each group (sequential):
  1. Gate check all phases in group
  2. Build phases (parallel where deps allow)
  3. Validate each phase (PASS/FAIL routing)
  4. When all group phases PASS → spawn auditor
  5. Orchestrator reads auditor report and triages:
     - Clean/Low → log deviations, continue to next group
     - Medium → auto-spawn builder + validator to fix
     - High/Critical → checkpoint with user, then fix
  6. Track deviation summary for next group's auditor

Step 1: Read and Review the Plan

1. Read the plan file at $ARGUMENTS/plan.md
2. Check if $ARGUMENTS/reviews/planning/plan.md exists
3. If no review exists, run /review-plan $ARGUMENTS first
4. Read the review file at $ARGUMENTS/reviews/planning/plan.md
5. Check the Verdict section:
   • If Yes → proceed to Step 2
   • If No → STOP and report the Critical Issues to the user

Step 2: Check Flow Audit

1. Count phases in the Phase Table.

2. Skip for small plans: If 1-2 phases, skip to Step 3.

3. Check if audit exists: Look for $ARGUMENTS/reviews/planning/flow-audit.md.

4. If missing: STOP and tell the user to run /audit-plan $ARGUMENTS first.

5. Gate logic:

Step 3: Parse Groups and Build Execution Plan

3a: Check for existing tasks (compact recovery):

Run TaskList first. If tasks already exist from a previous session or context compact:

1. Read existing tasks with TaskGet for each task ID
2. If any task is in_progress — resume from that point
3. Do NOT recreate the task list

3b: Parse the Phase Table and Group Summary:

Read plan.md’s Phase Table. For each phase, extract: number, title, group, focus, status, dependencies.

Read the Group Summary table to get group ordering and descriptions.

Build a group execution plan:

groups = [
  { name: "auth-system", phases: [P01, P02, P03], description: "..." },
  { name: "dashboard-ui", phases: [P04, P05, P06, P07], description: "..." },
  ...
]

Groups are processed sequentially in the order listed in the Group Summary. Phases within a group are processed in parallel where dependencies allow.

If all phases are done:

1. Remove the plan’s sidecar: rm -f ~/.cache/claude-statusline/plans/PLAN_NAME.json
2. Report completion to the user
3. Skip to Step 10 (cleanup)

3c: Create orchestrator tasks (first run only):

If no tasks exist yet, create tasks with rich, self-contained descriptions:

TaskCreate({
  subject: "Group: {group-name} — Phase {NN}: {title}",
  description: `Phase file: $ARGUMENTS/phase-{NN}-{slug}.md
Group: {group-name} ({N} phases in group: P{NN}, P{MM}, ...)
Skill: {skill-from-frontmatter}
Dependencies: {list or "none"}

Key deliverables from acceptance criteria:
- {criterion 1}
- {criterion 2}
- {criterion 3}

Gate check → build → validate → mark done.
After all phases in group "{group-name}" complete, spawn auditor for group review.`,
  activeForm: "Implementing Phase {NN} ({group-name})"
})

Then set up dependencies with TaskUpdate using addBlockedBy to mirror each phase’s dependencies frontmatter.

Also create one task per group for the audit step:

TaskCreate({
  subject: "Audit group: {group-name}",
  description: `Spawn auditor after all phases in group complete.
Group: {group-name}
Phases: P{NN}, P{MM}, ...
Plan folder: $ARGUMENTS

Auditor reviews: cross-phase regressions, deferred items, plan drift, acceptance criteria.
Triage: Clean/Low → continue. Medium → auto-fix. High/Critical → ask user.`,
  activeForm: "Auditing group {group-name}"
})

Set audit tasks to be blocked by all phase tasks in their group.

3d: Determine current group and unblocked phases:

Find the first group with pending phases. Within that group, identify unblocked phases (all dependencies satisfied).

Update the statusline sidecar:

mkdir -p ~/.cache/claude-statusline/plans && echo '{"plan":"PLAN_NAME","phase":PHASE_NUM,"group":"GROUP_NAME","updated":'$(date +%s)'}' > ~/.cache/claude-statusline/plans/PLAN_NAME.json

Step 4: Gate Check Phases

Before spawning builders, gate-check each unblocked phase. Mark each phase task as in_progress:

TaskUpdate({ taskId: "{phase-task-id}", status: "in_progress" })

4a: Check for skeleton/placeholder content:

echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_no_placeholders.py \
  --directory $ARGUMENTS --extension .md

If non-zero exit, the phase contains placeholder content. STOP — do not spawn a builder for a skeleton phase.

4b: Verify the phase review:

1. Check if $ARGUMENTS/reviews/planning/phase-{NN}.md exists
2. If no review exists, run /review-plan $ARGUMENTS phase {NN}
3. Read the review Verdict:
   • Ready: Yes → proceed to Step 5
   • Ready: No → FIX the phase first, re-run review, then proceed

Step 5: Create Team (First Run Only)

Create the team on the first run. Reuse it across all groups.

TeamCreate({
  team_name: "{plan-name}-impl",
  description: "Implementation team for {plan title}"
})

Concurrency Limits

Hard cap: 4 total active agents (builders + validators + auditor combined). The auditor runs alone — no builders or validators during audit.

Step 6: Spawn Builders

Spawn a fresh builder for each unblocked phase that passed gate-checking. Max 2 builders per batch.

Before spawning, extract the skill: field from each phase’s YAML frontmatter.

Task({
  description: "Implement phase {NN}",
  subagent_type: "builder",
  model: "opus",
  team_name: "{plan-name}-impl",
  name: "builder-1",
  mode: "bypassPermissions",
  prompt: `Implement the phase at: $ARGUMENTS/phase-{NN}-{slug}.md
Plan folder: $ARGUMENTS
Skill: {skill-from-frontmatter}

Follow your preloaded builder-workflow skill. It teaches you how to:
1. Read the phase and extract requirements
2. Invoke the Skill above (if not "none") and find reference files
3. Create internal tasks (TaskCreate) for each step — prefix with [Step]. This is REQUIRED for context compact recovery
4. Implement with TDD (Step 0 first), marking tasks in_progress/completed as you go
5. Run tests and typecheck
6. Report completion to team-lead (do NOT run /code-review — the validator handles that independently)

IMPORTANT: Before using the Write tool on any existing file, you MUST Read it first or the write will silently fail.`
})

Step 7: Wait and Route Builder/Validator Cycle

Wait for builder completion messages. When a builder reports done:

1. Spawn a fresh validator for this phase:

Task({
  description: "Validate phase {NN}",
  subagent_type: "validator",
  team_name: "{plan-name}-impl",
  name: "validator-{N}",
  mode: "bypassPermissions",
  prompt: `Validate phase {NN} on the {plan-name}-impl team. Follow the workflow defined in your agent instructions.

Phase file: $ARGUMENTS/phase-{NN}-{slug}.md
Plan folder: $ARGUMENTS

Run /code-review against the phase file, then verify with typecheck + tests. Report PASS/FAIL to team-lead via SendMessage.`
})

2. Wait for ALL validator verdicts in this batch before proceeding.

Handle Verdict

PASS:

1. Update phase YAML frontmatter: status: done
2. Update Phase Table in plan.md: status → “Done”
3. Mark the phase task as completed
4. Shutdown the builder and validator for this phase
5. When the entire batch is complete, check: are ALL phases in the current group done?
   • Yes → proceed to Step 8 (Group Audit)
   • No → loop back to find next unblocked phases in this group, spawn next batch

FAIL:

1. Shutdown current builder AND validator (both contexts may be stale)
2. Spawn a fresh builder with the validator’s fix instructions
3. Wait for fix builder → spawn fresh validator → re-validate → repeat until PASS

Step 8: Group Audit

When all phases in a group have passed validation, spawn an auditor for the group.

Mark the group audit task as in_progress:

TaskUpdate({ taskId: "{audit-task-id}", status: "in_progress" })

Shutdown all builders and validators from this group first — the auditor runs alone.

Spawn the auditor:

Task({
  description: "Audit group {group-name}",
  subagent_type: "auditor",
  model: "opus",
  team_name: "{plan-name}-impl",
  name: "auditor-{group-name}",
  mode: "bypassPermissions",
  prompt: `Audit the "{group-name}" phase group.

Plan folder: $ARGUMENTS
Group: {group-name}
Phases in this group:
- Phase {NN}: {title} — $ARGUMENTS/phase-{NN}-{slug}.md
- Phase {MM}: {title} — $ARGUMENTS/phase-{MM}-{slug}.md
[...list all phases in group...]

Previous group deviations:
{deviation-summary-from-previous-groups OR "None — this is the first group."}

Follow your preloaded auditor-workflow skill. It teaches you how to:
1. Read all group phases and build inventory
2. Collect and review code reviews for group phases
3. Check deferred items against current code
4. Cross-phase impact analysis (shared files, imports, overwrites)
5. Run verification (tests + typecheck)
6. Plan vs implementation comparison (acceptance criteria, ADRs)
7. Consider previous groups' deviations
8. Write audit report to $ARGUMENTS/reviews/implementation/group-{group-name}-audit.md
9. Report findings to team-lead with severity ratings

IMPORTANT: You are READ-ONLY. Do not modify source code. Write only the audit report file.`
})

Step 9: Triage Auditor Findings

When the auditor reports back, read the full audit report at $ARGUMENTS/reviews/implementation/group-{group-name}-audit.md.

9a: Create tasks from findings FIRST (compact safety):

Before spawning any fix builders, create tasks for each finding that needs action. This ensures findings survive context compaction:

TaskCreate({
  subject: "Fix: {finding summary} (group {group-name})",
  description: `From auditor report: $ARGUMENTS/reviews/implementation/group-{group-name}-audit.md

Severity: {Critical/High/Medium/Low}
Phase: P{NN}
File: {file:line from auditor report}
Issue: {description from auditor report}
Suggested fix: {fix from auditor report}`,
  activeForm: "Fixing {finding summary}"
})

9b: Triage by severity:

9c: For Medium findings — auto-fix cycle:

1. Spawn a builder with the specific fix instructions from the auditor report
2. Wait for builder completion
3. Spawn validator to verify the fix
4. If PASS → mark fix task complete
5. If FAIL → retry (max 3 attempts per finding, then escalate to user)

9d: For High/Critical findings — user checkpoint:

Present the auditor’s findings to the user:

## Group "{group-name}" Audit — Needs Your Input

**Assessment:** {from audit report}

### Critical/High Findings:
1. {finding 1 — severity, phase, file:line, issue}
2. {finding 2}
...

### Auditor's Recommendation:
{from audit report}

**Options:**
1. Fix all — I'll spawn builders for each finding
2. Fix specific items — tell me which ones
3. Skip and continue — accept the findings as-is
4. Stop implementation — address these manually

Use AskUserQuestion to get the user’s choice, then act accordingly.

9e: Track deviation summary:

After all findings are resolved (or accepted), build a deviation summary for the next group’s auditor:

deviation_summaries[group_name] = {
  assessment: "{from audit report}",
  key_deviations: ["{finding 1}", "{finding 2}"],
  unresolved: ["{any findings user chose to skip}"]
}

Pass this to the next auditor in its spawn prompt (see Step 8, “Previous group deviations”).

9f: Mark audit task complete and continue:

TaskUpdate({ taskId: "{audit-task-id}", status: "completed" })

Shutdown the auditor:

SendMessage({ type: "shutdown_request", recipient: "auditor-{group-name}" })

Loop back to Step 3 to start the next group.

Step 10: Cleanup

When all groups are done OR an error breakout condition is met:

1. Shutdown all active teammates:

// For each active agent:
SendMessage({ type: "shutdown_request", recipient: "{agent-name}" })

2. Delete team: TeamDelete()

3. Remove this plan’s statusline sidecar:

rm -f ~/.cache/claude-statusline/plans/PLAN_NAME.json

4. Report final summary to user:

## Implementation Complete

**Plan:** $ARGUMENTS
**Groups:** {count} completed
**Phases:** {count} Done

### Group Audit Results:
| Group | Assessment | Critical | High | Medium | Low |
|-------|-----------|----------|------|--------|-----|
| {name} | {verdict} | {N} | {N} | {N} | {N} |

### Unresolved Items:
{any findings the user chose to skip}

### Verification:
- Tests: {pass/fail}
- Typecheck: {pass/fail}

Error breakout conditions — STOP and shut down if:

• Validator FAIL repeats 3+ times on the same phase
• Auditor finding fix fails 3+ times
• Phase has Critical blocking issues from plan review
• User requests cancellation

Resuming After Context Compact

If you notice context was compacted:

1. Run TaskList to see all tasks and their status
2. Find the in_progress task — that’s where you were
3. Run TaskGet {id} on that task for full details
4. Read plan.md to get the Phase Table and Group Summary
5. Check existing audit reports in $ARGUMENTS/reviews/implementation/ to rebuild deviation summaries
6. Check if team exists: read ~/.claude/teams/{plan-name}-impl/config.json
   • If team exists, teammates may still be active — coordinate via messages
   • If no team, re-create it
7. Continue from the in_progress task

Pattern for every work cycle:

TaskList → find in_progress or first pending → TaskGet → continue work → TaskUpdate (completed) → next task

Tasks are the orchestrator’s source of truth for progress — not memory, not plan.md alone.

Reference Material

For anti-pattern prevention, context compact recovery, and troubleshooting, see references/team-operations.md.