implement-phase
/implement-phase
Execute a single phase from an implementation plan with all quality gates. This skill is the unit of work for implement-plan, handling implementation, verification, code review, ADR compliance, and plan synchronization for ONE phase. Triggers when implement-plan delegates a phase, or manually with "/implement-phase" and a phase reference.
- Author
- mhylle ↗
- Repository
- claude-skills-collection ↗
- Licence
- MIT
- Last repository change
- 13.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 0
- HTML comments
- 2
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Execute a single phase from an implementation plan with all quality gates. This skill is the unit of work for implement-plan, handling implementation, verification, code review, ADR compliance, and plan synchronization for ONE phase. Triggers when implement-plan delegates a phase, or manually with "/implement-phase" and a phase reference.
Arguments
/implement-phase [plan-path] [phase-number]
Original author description
Execute a single phase from an implementation plan with all quality gates. This skill is the unit of work for implement-plan, handling implementation, verification, code review, ADR compliance, and plan synchronization for ONE phase. Triggers when implement-plan delegates a phase, or manually with "/implement-phase" and a phase reference.
How it works
- Contents
- Orchestrator pattern (non-negotiable)
- Execution contract (read before starting)
- Blocker protocol
- Mandatory exit conditions
- Input context
- Architecture
- The 8 steps (overview)
- Optional steps
- TDD mode
SKILL.md preview
---
name: implement-phase
description: Execute a single phase from an implementation plan with all quality gates. This skill is the unit of work for implement-plan, handling implementation, verification, code review, ADR compliance, and plan synchronization for ONE phase. Triggers when implement-plan delegates a phase, or manually with "/implement-phase" and a phase reference.
user-invocable: false
argument-hint: "[plan-path] [phase-number]"
---
# Implement Phase
<!-- contents: generated by tests/skill_structure.py --write; edit headings, not this block -->
## Contents
- [Orchestrator pattern (non-negotiable)](#orchestrator-pattern-non-negotiable)
- [Execution contract (read before starting)](#execution-contract-read-before-starting)
- [Blocker protocol](#blocker-protocol)
- [Mandatory exit conditions](#mandatory-exit-conditions)
- [Input context](#input-context)
- [Architecture](#architecture)
- [The 8 steps (overview)](#the-8-steps-overview)
- [Step 1 — Implementation](#step-1--implementation)
- [Step 2 — Exit Condition Verification (verification-loop)](#step-2--exit-condition-verification-verification-loop)
- [Step 3 — Automated Integration Testing](#step-3--automated-integration-testing)
- [Step 4 — Code Review](#step-4--code-review)
- [Step 5 — ADR Compliance Check](#step-5--adr-compliance-check)
- [Step 6 — Plan Synchronization](#step-6--plan-synchronization)
- [Step 7 — Prompt Archival](#step-7--prompt-archival)
- [Step 8 — Phase Completion Report](#step-8--phase-completion-report)
- [Optional steps](#optional-steps)
- [TDD mode](#tdd-mode)
- [Phase-steps extensibility](#phase-steps-extensibility)
- [Error handling](#error-handling)
- [Configuration](#configuration)
- [Invocation](#invocation)
- [Return value](#return-value)
- [Integration with other skills](#integration-with-other-skills)
- [Best practices](#best-practices)
- [References (loaded on demand)](#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.**
| DO (orchestrator) | DON'T (direct implementation) |
|---|---|
| Spawn subagents to write code | Write code yourself |
| Spawn subagents to create files | Use Write/Edit tools directly |
| Spawn subagents to run tests | Run tests yourself |
| Spawn subagents to fix issues | Fix code yourself |
| Read files to understand context | Read files to copy/paste code |
| Track progress with Task tools | Implement while tracking |
| Coordinate and delegate | Do the work yourself |
**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:**
| Blocker | Example |
|---|---|
| Permission denied | Subagent cannot write to a protected directory |
| Infrastructure unavailable | Cannot reach required inference server |
| Missing credentials | API key not configured, auth token expired |
| External service down | Third-party API returning 503 |
| Ambiguous requirements | Plan says "integrate with payment system" but doesn't specify which |
| Destructive operation | Phase requires dropping a production database |
**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.
| Condition | Requirement | Why |
|---|---|---|
| **verification-loop PASS** | All 6 checks pass (Build, Type, Lint, Test, Security, Diff) | Code must compile, type-check, pass linting, tests, and security |
| **Integration tests PASS** | All API/UI tests pass | Feature must work end-to-end |
| **Code review PASS** | STATUS: PASS (NOTEs may remain) | No blocking issues or recommendations outstanding |
| **All recommendations fixed** | Every recommendation addressed | Recommendations are blocking, not optional |
| **ADR compliance PASS** | Follows existing ADRs, new decisions documented | Architectural consistency |
| **Plan verified** | All work items confirmed complete | Specification fulfilled |
**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
```yaml
# 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
Files in this package (7)
- SKILL.md 21 KB
- references/optional-steps.md 2 KB
- references/phase-steps.md 9 KB
- references/return-value.md 3 KB
- references/step-details.md 12 KB
- references/subagent-protocol.md 4 KB
- references/tdd-mode.md 7 KB
Versions
The database has no other skills named implement-phase.
Database snapshot: 13.11.2026 · package version 04b48f8123db (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100implement-plan
Execute an approved implementation plan from the configured plans directory. Use when the user wants to implement a plan phase by phase with verification. - 90build-phase
Build a specific phase by number. Spawns Builder to implement the approved phase plan. Phase 1 quality gates (PostToolUse, Stop hooks) fire automatically on Builder. Use when you're ready to implement an approved phase plan. Triggers on: '/build-phase', 'build phase', 'implement… - 95implement-plan
Orchestrate the execution of complete implementation plans, delegating each phase to implement-phase skill. This skill manages the full plan lifecycle including phase sequencing, user confirmation between phases, and overall progress tracking. Triggers on "implement the plan",… - 90rpi-implement
Execute an approved plan from .rpi/plans phase by phase with TDD and per-phase verification. Use when user says 'implement the plan', 'start implementing', 'run the next phase', or just approved a plan. - 90rpi-implement
Execute an approved plan from .rpi/plans phase by phase with TDD and per-phase verification. Use when user says 'implement the plan', 'start implementing', 'run the next phase', or just approved a plan. - 100doc-driven-implementer-v1
Use only when the user explicitly asks to use doc-driven-implementer. Implements an existing IMPLEMENT.md plan phase by phase with completion gates, test evidence, and doc/handoff synchronization.