Implement Phase

Contents

• Orchestrator pattern (non-negotiable)
• Execution contract (read before starting)
• Blocker protocol
• Mandatory exit conditions
• Input context
• Architecture
• The 8 steps (overview)
  • Step 1 — Implementation
  • Step 2 — Exit Condition Verification (verification-loop)
  • Step 3 — Automated Integration Testing
  • Step 4 — Code Review
  • Step 5 — ADR Compliance Check
  • Step 6 — Plan Synchronization
  • Step 7 — Prompt Archival
  • Step 8 — Phase Completion Report
• Optional steps
• TDD mode
• Phase-steps extensibility
• Error handling
• Configuration
• Invocation
• Return value
• Integration with other skills
• Best practices
• References (loaded on demand)

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

• references/optional-steps.md: Optional steps
• references/phase-steps.md: Phase Steps Reference
• references/return-value.md: Return value
• references/step-details.md: Step details — subagent patterns and output specs
• references/subagent-protocol.md: Subagent Communication Protocol
• references/tdd-mode.md: TDD Mode (optional)

Execute a single phase from an implementation plan with comprehensive quality gates. Designed to be called by implement-plan, but can also be invoked directly. Either way it runs inline: the session that invoked it is the phase lead.

Orchestrator pattern (non-negotiable)

This session is the phase lead and an orchestrator. Never implement code directly.

Violations: using Write/Edit/NotebookEdit directly, creating files without spawning a subagent, fixing code without spawning a subagent, running implementation commands directly.

This holds whenever the Agent tool is available. "Foreground", "no background agents" or "don't poll" in the user's words is about how you wait for agents, not about who writes the code; only an explicit "write the code yourself in this session" overrides the rule, and when you're unsure, ask. If Agent isn't in your tool list at all, do the steps' work in this session.

Why orchestrate?

• Context preservation — main session retains full plan context.
• Parallelization — independent tasks run concurrently.
• Clean separation — orchestration logic stays separate from implementation.
• Better error handling — subagent failures don't pollute main context.

Subagent communication protocol → references/subagent-protocol.md. Every subagent prompt must include a response-format block demanding terse STATUS/FILES/ERRORS output and disk-based logs for large output. Verbose subagent responses are the single biggest context waster this skill faces.

Execution contract (read before starting)

Steps 1–8 execute as one continuous operation. The phase lead does not stop for the user between them.

current_step = 1
while current_step <= 8:
    result = execute_step(current_step)
    if result == PASS:
        current_step += 1          # AUTO-CONTINUE, no user pause
    elif result == FAIL:
        fix_and_retry(current_step)  # Stay on step, spawn fix subagent, retry
    elif result == BLOCKED:
        ask_user()                   # Blocker protocol, then resume this step
return COMPLETE                      # Only stop here (after Step 8)

Agents report asynchronously. An Agent call returns at once; the agent's report arrives later as a message in this session, and that message resumes you. After dispatching, do any independent work that's left (another independent dispatch, preparing the next step's context). When nothing is left, end the turn with one line saying what you're waiting for, e.g. Waiting for: test writer (1a), implementer (1b). Waiting on a report is not a pause: the report resumes the step. Never poll with sleep or wait loops, never say you'll wait and then stop, and never do the dispatched work yourself in the meantime, since it would collide with the agent's.

Keep track of what's in flight. Before ending a turn, note which agents are running and for which step or sub-task (the tracker's IN FLIGHT line), so a resumed or compacted session can tell what is still outstanding.

The only valid pause points are:

1. BLOCKED — something you cannot fix without the user (see Blocker protocol below). Ask them, then resume the blocked step.
2. After Step 8 — the Completion Report and PHASE_RESULT have been presented; the next phase waits for the user.

Everything else is a fix loop, not a pause. Verification failed → spawn fix subagent → re-run → PASS → continue. Code review returned NEEDS_CHANGES → spawn fix subagent → re-run → PASS → continue. None of these require user input; they require retries.

After each step, output a progress tracker and continue. Example after Step 4:

┌─────────────────────────────────────────┐
│ PROGRESS: Step 4 → Step 5               │
├─────────────────────────────────────────┤
│ ✅ Step 1: Implementation    [DONE]     │
│ ✅ Step 2: Exit Conditions   [DONE]     │
│ ✅ Step 3: Integration Test  [DONE]     │
│ ✅ Step 4: Code Review       [DONE]     │
│ ⏳ Step 5: ADR Compliance    [CURRENT]  │
│ ⬚ Step 6: Plan Sync         [PENDING]  │
│ ⬚ Step 7: Prompt Archival   [PENDING]  │
│ ⬚ Step 8: Completion Report [PENDING]  │
├─────────────────────────────────────────┤
│ IN FLIGHT: none                         │
│ NEXT ACTION: Check ADR compliance now   │
└─────────────────────────────────────────┘

NEXT ACTION must describe executing the next step (or, mid-step, the reports you're waiting for), not "waiting for user confirmation." Any tracker whose NEXT ACTION says otherwise (before Step 8) is a contract violation.

Self-check after a skill invocation (like code-review):

1. Did it return PASS? → continue to next step immediately.
2. NEEDS_CHANGES? → spawn fix subagents, re-run step, expect PASS.
3. Am I at Step 8? → if no, execute next step immediately.
4. Did I test the feature myself? → if no, go back to Step 3.

Blocker protocol

A blocker is something you cannot fix autonomously. Do not stop for fixable issues.

Valid blockers:

NOT blockers — fix these yourself: test fails, lint errors, build errors, type errors, code-review feedback, API returning an error, UI element not found.

When you hit a genuine blocker, ask the user directly — you're running in their session. Stop dispatching new work, note what's still in flight, and present the blocker (with AskUserQuestion for the options when it's available):

⛔ BLOCKED: [brief description]

Phase: [N] - [Name]
Step: [current step]
Blocker Type: [Permission | Infrastructure | Credentials | External | Ambiguous | Destructive]

Details:
[what failed and why]

What I need:
[specific action from user]

Options:
A) [resolve and continue]
B) [skip this verification and proceed with risk]
C) [abort phase]

After the user answers, resume from the blocked step (not Step 1). End the phase with status: BLOCKED in PHASE_RESULT only when the caller said the run is unattended and no one can be asked; fill in blocker with what would unblock it.

Mandatory exit conditions

Non-negotiable — a phase cannot complete until all are satisfied.

Why recommendations are mandatory, not "nice to have":

• Recommendations indicate pattern violations, missing tests, or technical debt.
• Unfixed, they accumulate and compound across phases.
• The Clean Baseline Principle requires each phase to end clean — the next phase inherits whatever you leave behind.
• If an issue is worth noting, it's worth fixing.

The only acceptable Step 4 outcome is clean PASS.

Input context

Plan Path: [path to plan file]
Phase: [number or name]
Task ID: [from implement-plan's TaskList]
Prompt Path: [optional - path to pre-generated prompt from prompt-generator]
Changed Files: [optional - auto-detected if not provided]
Skip Steps: [optional - list of steps to skip, for testing]
TDD Mode: [enabled/disabled - see references/tdd-mode.md]
Coverage Threshold: [percentage - default 80%, applies when TDD enabled]

If a Prompt Path is provided (from prompt-generator):

1. Read the prompt file — it contains detailed orchestration instructions.
2. Use the prompt as primary guidance.
3. Use the plan as the source of truth for exit conditions and success criteria.
4. Archive the prompt on completion (Step 7).

Architecture

implement-plan (orchestrates full plan)
    │
    └── implement-phase (this skill — one phase at a time, in the same session)
            │
            ├── 1. Implementation (spawn subagents)
            ├── 2. Exit Condition Verification (verification-loop skill)
            ├── 3. Automated Integration Testing (API or Playwright)
            ├── 4. Code Review (code-review skill)
            ├── 5. ADR Compliance Check
            ├── 6. Plan Synchronization
            ├── 7. Prompt Archival (if prompt provided)
            └── 8. Phase Completion Report

The 8 steps (overview)

Full subagent-spawning patterns and per-step output formats live in references/step-details.md. Read that file when you're about to execute a step. Summary here:

Step 1 — Implementation

Spawn test subagents first (verification-first pattern), then implementation subagents with a coding-standards pointer embedded. Monitor, collect changed files. If TDD mode is enabled, the order reverses and adds a RED → GREEN → REFACTOR cycle — see references/tdd-mode.md. Output: IMPLEMENTATION_STATUS, FILES_CREATED/MODIFIED, TEST_RESULTS. Gate: PASS. Next: Step 2.

Step 2 — Exit Condition Verification (verification-loop)

Invoke the verification-loop skill. It runs 6 checks (Build, Type, Lint, Test, Security, Diff). Output: VERIFICATION_LOOP_STATUS, per-check results. Gate: all 6 PASS. Next: Step 3.

Step 3 — Automated Integration Testing

You are the tester. Not the user. API → curl/httpie/fetch subagent. Web UI → browser-verification-agent (one test scenario per spawn; or general-purpose with claude-in-chrome if it isn't in your agent list). CLI → execute and verify output. Database → query and verify. Output: aggregated INTEGRATION_TEST_STATUS, pass/fail counts, evidence paths. Gate: PASS. Next: Step 4.

Step 4 — Code Review

Invoke devflow:code-review (this collection's skill, invoked as devflow:code-review; not Claude Code's built-in /code-review, which returns a different result) with phase context. PASS is required; NEEDS_CHANGES (any blocking issue or recommendation) requires fix subagents and re-review (max 3 retries). NOTEs are informational and never block. Output: CODE_REVIEW_STATUS, blocking issues, recommendations, notes. Gate: PASS. Next: Step 5.

Step 5 — ADR Compliance Check

Read docs/decisions/INDEX.md, check against applicable ADRs, invoke the adr skill if new decisions need documentation. Output: ADR_COMPLIANCE_STATUS, applicable ADRs, any new ADR numbers. Gate: PASS. Next: Step 6.

Step 6 — Plan Synchronization

Verify all work items completed, add ADR references, note deviations. Per ADR-0001, plans are specification documents — progress lives in Task tools (TaskUpdate), not checkbox edits. Output: PLAN_SYNC_STATUS, work-items count. Gate: PASS. Next: Step 7.

Step 7 — Prompt Archival

If a prompt file was used, move it to docs/prompts/completed/. If none, mark skipped. Output: PROMPT_ARCHIVAL_STATUS. Gate: non-blocking (a failed archive logs but doesn't stop completion). Next: Step 8.

Step 8 — Phase Completion Report

Final. Generate the summary (see references/step-details.md for the format), invoke continuous-learning (it confirms any learned skills with the user before writing them), present the report and the PHASE_RESULT block, stop. If implement-plan invoked you, it continues from that block in this same session.

Optional steps

Some pipelines insert additional steps at specific points. See references/optional-steps.md for the full list and enablement mechanism. Currently supported:

• Security Review (inserts at Step 4.5) — enable for auth/input/crypto/payment phases. Skill: devflow:security-review (not the built-in /security-review).

TDD mode

Optional. When enabled (via plan metadata, --tdd flag, or global settings), Step 1 follows the RED → GREEN → REFACTOR cycle and a coverage-verification check is added. See references/tdd-mode.md for full details.

Phase-steps extensibility

The pipeline is defined as an ordered list of steps:

PHASE_STEPS = [
  { name: "implementation",       required: true,  skill: null },
  { name: "exit_conditions",      required: true,  skill: null },
  { name: "integration_testing",  required: true,  skill: null },
  { name: "code_review",          required: true,  skill: "devflow:code-review" },
  { name: "adr_compliance",       required: true,  skill: "adr" },
  { name: "plan_sync",            required: true,  skill: null },
  { name: "prompt_archival",      required: false, skill: null },
  { name: "completion_report",    required: true,  skill: null },
]

Adding a new step: define gate criteria, insert at the right position, implement the logic or delegate to a skill. Steps can be conditional (e.g., phase-type-based, metadata-flag-gated). Full step-config schema, gate-criteria field definitions, retry/timeout semantics, and worked examples for security-scan / performance-check / docs-update → references/phase-steps.md.

Error handling

Step failures:

1. Log failure details with full context.
2. Attempt an automatic fix (spawn fix subagent).
3. Re-run the step.
4. Escalate to user if the fix fails or requires a decision.

Retry limit: default 3 per step. Exhausted retries escalate:

⛔ PHASE BLOCKED: [Step Name] failed after 3 attempts

Last Error: [details]

Options:
A) Retry with different approach
B) Skip this step (if non-blocking)
C) Abort phase and return to plan

How should I proceed?

Blocker protocol (above): stop dispatching new work, note what's in flight, ask the user with full context, resume the blocked step after their answer.

Configuration

# In the plan file
phase_config:
  strict_mode: true          # Fail on any warning
  skip_steps: []
  additional_steps: []
  retry_limit: 3
  tdd_mode: false
  coverage_threshold: 80

# Global defaults (~/.claude/settings.json)
implement_phase:
  default_retry_limit: 3
  always_run_security: false
  require_adr_for_decisions: true
  default_tdd_mode: false
  default_coverage_threshold: 80

Invocation

From implement-plan (primary use):

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

Context:
- Plan: docs/plans/auth-implementation.md
- Phase: 2 (Authentication Service)
- Previous Phase Status: Complete

Execute all quality gates and end with the PHASE_RESULT block.

The procedure loads into implement-plan's session, which becomes the phase lead; implement-plan picks up again from the PHASE_RESULT block.

Manual:

/implement-phase docs/plans/my-plan.md phase:3

Or interactively:

/implement-phase
> Which plan? docs/plans/auth-implementation.md
> Which phase? 2

Return value

Step 8 ends with a structured PHASE_RESULT block, the phase's closing summary in the same session, with per-step status, files changed, test results, ADR info, and a ready_for_next flag. When implement-plan invoked the phase, it reads this block and continues. Full schema in references/return-value.md.

Integration with other skills

• devflow:code-review — called in Step 4. Receives phase context, returns structured review.
• adr — called in Step 5 when new architectural decisions need documentation or compliance check finds undocumented decisions.
• verification-loop — called in Step 2. Default exit-condition check (6 checks).
• devflow:security-review — called in optional Step 4.5 when enabled.
• continuous-learning — called in Step 8 to capture phase patterns before /clear or /compact.

Future extensibility: the step design allows adding security-scan, performance-check, documentation-update, changelog-entry, and similar quality gates without modifying the core logic.

Best practices

For implement-plan authors:

1. Provide complete phase context when calling.
2. Trust the PHASE_RESULT block that ends the phase.
3. Expect status: BLOCKED only from unattended runs; otherwise the phase asks the user itself.
4. Present manual verification steps to the user only if they were actually needed (should be rare — Step 3 covers automated testing).

For direct users:

1. Ensure the plan file is up-to-date before running.
2. Have docs/decisions/INDEX.md available.
3. Review any manual verification steps the completion report surfaces.
4. If the completion report lists code-review NOTEs, skim them — they are informational and were not required to be fixed.

For step developers:

1. A new step must define: its gate criteria, its output format, whether it's required, whether it wraps a skill.
2. Insert at the correct position (after the step it depends on, before any step that depends on it).
3. Update references/step-details.md with the subagent pattern and references/phase-steps.md with the step's config entry.

References (loaded on demand)

• references/subagent-protocol.md — mandatory response-format block, concise-response examples, disk-based communication patterns, coding-standards pointer template
• references/step-details.md — detailed subagent-spawning patterns and per-step output formats for all 8 default steps
• references/tdd-mode.md — optional Step 1 inversion: RED → GREEN → REFACTOR cycle, TDD subagent prompts, coverage verification
• references/optional-steps.md — Step 4.5 Security Review insertion point, enablement via plan metadata, per-phase overrides
• references/phase-steps.md — default pipeline table, step config schema, adding custom steps, conditional execution rules, step insertion points
• references/return-value.md — full PHASE_RESULT schema returned to implement-plan, status values per step, ready_for_next semantics