mhylle/claude-skills-collection/implement-phase

Implement Phase

<!-- contents: generated by tests/skill_structure.py --write; edit headings, not this block -->

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)

<!-- /contents -->

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: