Implement Plan

Contents

• Your Role: Orchestrator
• Getting Started
  • 1. Locate and Read the Plan
  • 2. Assess the Environment
  • 3. Check or Create Progress Tracking
  • 4. Confirm Before Starting
• Phase Execution
  • Announce
  • Run implement-phase
  • Handle Results
  • Confirm Between Phases
• Resuming Interrupted Work
• Final Completion
• Adapting to Plan Size
• Key Principles
• Skill Dependencies
• Reference

Reference files (open one when a step points to it):

• references/plan-format.md: Implementation Plan Format Reference

Orchestrate complete implementation plans by sequencing phases and running each one through the implement-phase skill, in this session. Read a plan, track progress, and coordinate phase-by-phase execution with user confirmation between phases.

Your Role: Orchestrator

This session coordinates — it does not implement. All code writing, testing, and file creation is done by the subagents that implement-phase spawns. When you invoke implement-phase, its procedure loads into this same session, which becomes the phase lead; the lead still hands the actual work to subagents.

Why this separation matters:

• Context preservation — This session retains the full plan context across all phases. Implementation work would fill the context with code details and lose sight of the overall plan.
• Clean error boundaries — Implementation failures are isolated within the subagents. The orchestrator stays clean and can reason about recovery without being entangled in failing code.
• Parallelization — implement-phase runs multiple tasks concurrently within a phase.

In practice: use Read/Glob to understand context, Skill to invoke implement-phase, and Task tools to track progress. Do not use Write/Edit/NotebookEdit; if you are about to, run implement-phase's procedure instead, which spawns subagents for the work.

This holds whenever the Agent tool is available. A user's "foreground", "no background agents" or "don't poll" is about how this session waits for agents, not about who writes the code; only an explicit "write the code yourself in this session" overrides the rule, so ask when unsure.

Getting Started

1. Locate and Read the Plan

Find the plan file (common locations: docs/plans/, thoughts/plans/, or the user-specified path). Read the entire plan — full context is essential for sequencing phases correctly.

2. Assess the Environment

Check what supporting infrastructure exists. Not all projects have all of these — adapt accordingly:

3. Check or Create Progress Tracking

TaskList → Look for tasks matching "Phase N:" pattern

If tasks exist with some completed:
  → Resume from first non-completed task
  → Show progress summary

If no tasks exist:
  → Create one task per phase with sequential dependencies
  → Start from Phase 1

4. Confirm Before Starting

Present a brief summary before executing:

• Plan name and total phases
• Current progress (if resuming)
• Which phase executes first
• Notable dependencies or prerequisites

Wait for user confirmation to begin.

Phase Execution

Announce

Briefly state what's about to happen:

======================================
STARTING PHASE [N]: [Phase Name]
======================================

Objectives: [1-2 sentences]
Dependencies: [Previous phase status]

Running implement-phase...

Run implement-phase

Mark the phase's task in_progress, then invoke the skill:

Skill(skill="implement-phase"): Execute Phase [N] of the implementation plan.

Context:
- Plan: [plan file path]
- Phase: [N] ([Phase Name])
- Task ID: [from TaskList, if available]
- Prompt: [prompt file path if discovered, otherwise "None"]
- Previous Phase Status: [Complete/N/A]

Execute all quality gates and end with the PHASE_RESULT block.

Optional parameters to pass through when specified in the plan:

• TDD Mode, Coverage Threshold — from plan metadata
• Skip Steps — if specific quality gates should be skipped

Its procedure loads into this session, which then acts as the phase lead through Steps 1–8; nothing comes back from elsewhere, so continue from the PHASE_RESULT block that ends Step 8.

Its agents report asynchronously, so this session ends turns while it waits for them. That is the phase still in progress, not the phase ending: each report resumes the phase, which runs on until Step 8.

Handle Results

The PHASE_RESULT block that ends each phase has one of three statuses:

COMPLETE — All quality gates passed.

1. Update task status to completed
2. Present results summary
3. Note any manual verification items (rare — implement-phase handles most verification)
4. Wait for user confirmation before next phase

FAILED — Quality gates could not be satisfied after internal retries.

1. Present failure details and what was attempted
2. Do not automatically retry the whole phase — implement-phase already retried internally
3. Offer options:
   • Fix and retry — User provides guidance, re-run the phase
   • Skip — Mark as skipped, note the risk, continue (user's call)
   • Abort — Stop plan execution
4. Wait for user decision

BLOCKED — During a phase, implement-phase asks the user about a blocker itself, since it runs in this session, and resumes the blocked step after the answer. A PHASE_RESULT with status: BLOCKED only ends a phase when no one could be asked (an unattended run). When you see one:

1. Present the blocker with full context
2. Include options from implement-phase plus your recommendation
3. Wait for user decision
4. On resolution, resume from the blocked step (not from Phase 1)

Confirm Between Phases

After each phase completes:

======================================
PHASE [N] COMPLETE: [Phase Name]
======================================

Results:
  Implementation: [files created/modified]
  Verification: [build/test/lint status]
  Code Review: [status]
  ADR Compliance: [status]

[Manual verification items, if any]

Progress: [N]/[total] phases complete
Next: Phase [N+1] — [Name]

Ready to proceed?
======================================

Resuming Interrupted Work

When tasks already exist for this plan:

1. Call TaskList to see current state
2. Find the first non-completed task
3. Spot-check that previous work exists (verify a few key files from completed phases)
4. Present resume summary and continue

Resuming: [Plan Name]

  Phase 1: [Name] — completed
  Phase 2: [Name] — completed
  Phase 3: [Name] — resuming here
  Phase 4: [Name] — pending

Continuing from Phase 3...

Final Completion

After all phases complete:

======================================
PLAN COMPLETE: [Plan Name]
======================================

Summary:
  Phases Completed: [N]/[N]
  Files Created: [count]
  Files Modified: [count]
  Tests Added: [count]

Quality Gates: All passed across all phases

Final Verification:
  [Remaining manual items, if any — often none]

======================================

Adapting to Plan Size

Not every plan needs full ceremony:

The implement-phase pipeline is the same regardless — this adaptation is about how much orchestration scaffolding this skill adds around it.

Key Principles

1. Delegate, don't implement — All code work flows through the subagents implement-phase spawns
2. Confirm between phases — Give the user a chance to review, adjust, or abort
3. Trust the PHASE_RESULT block — Act on the block that ends each phase
4. Surface problems clearly — Present failures and blockers with context and options
5. Degrade gracefully — Missing prompts or task history should not block execution
6. Resume cleanly — Task tools let work survive session restarts

Skill Dependencies

implement-plan
    └── implement-phase (required, runs in this session)
            ├── verification-loop (required)
            ├── devflow:code-review (required)
            └── adr (required for compliance)

Reference

See references/plan-format.md for:

• Standard plan structure and formatting
• Exit condition templates by project type (Node.js, Python, Go, Rust, Java)
• Phase organization and sizing guidelines