implement

name: implement description: "When the user asks to implement a feature, build a new capability, or runs /implement, drive the work through TDD with a parallel-or-sequential plan: gather context, propose a plan, gate user approval, run Red→Green→Refactor with conflict-free file ownership, verify, and report." when_to_use: Use ONLY for new feature work invoked via /implement or explicit 'build / implement / add this feature' phrasing. Do NOT use for bug fixes (use /fix), behavior-preserving refactors (use /improve only when the user wants improvement, not pure rename), or single-line config edits. argument-hint: " [--side back|front|both] [--step N] [--skip-docs]" allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git status*), Bash(git branch*), Bash(git diff*), Bash(npm test*), Bash(npm run*), Bash(./gradlew test*), Bash(mvn test*), Bash(pytest*), Bash(go test*), Bash(rspec*), AskUserQuestion, Agent disable-model-invocation: true

/implement — TDD-driven feature implementation

When the user wants to build a new feature, this skill walks the work through a TDD pipeline: read the project, gather feature requirements, plan with explicit file ownership, gate user approval, run Red→Green→Refactor (parallel where safe), verify, review, and report.

Parameters

Workflow

Step 0: Project recognition (CLAUDE.md scan)
Step 1: Context gathering
Step 2: Plan + conflict matrix
Step 3: ★ Approval gate ★          ← user owns this
Step 4: TDD execution (single direct or parallel via Subagent / Agent Team)
Step 5: Integration verification
Step 6: Code review
Step 7: Completion report

Step 0: Project recognition

Read CLAUDE.md plus any */CLAUDE.md to capture tech stack, build / test commands, and conventions. If absent, ask the user before proceeding.

Step 1: Context gathering

1. git status && git branch --show-current — if on the main branch, prompt for a feature branch.
2. Look for design docs at **/docs/**/$ARGUMENTS[0]/**/*.md.
   • Found: extract requirements, scope, API contract.
   • Missing: ask the user (skip when --skip-docs).
3. Read existing patterns in the affected domain to match conventions.

Step 2: Plan

1. Decompose the request into independent feature units (each with files + dependencies).
2. Conflict matrix (multi-feature only): build the file-overlap matrix; identify parallelizable groups.
3. Execution strategy (use ../_shared/execution-strategy.md):
   • 1 unit → direct
   • N units, no conflicts, no inter-worker debate → Subagent (parallel)
   • N units, mid-flight contract negotiation needed → Agent Team
4. Build order: backend (model → repository → service → API) then frontend (API client → state → UI).

Templates: see references/templates.md.

Step 3: ★ Approval gate ★

Use AskUserQuestion with options: approve / modify / cancel. Do not proceed to Step 4 without explicit approval. This is a hard rule.

Step 4: TDD execution

For each file unit, run Red → Green → Refactor:

1. Red — write failing tests covering boundaries, state transitions, error paths.
2. Green — minimum implementation that passes the tests.
3. Test run — PASS → next; FAIL → fix.
4. Refactor — improve while keeping tests green.
5. Incremental commit — call /commit per feature unit.

For parallel multi-feature work, see the spawn prompt template in references/templates.md.

Step 5: Integration verification

Run project verify skills (e.g., /verify-backend, /verify-frontend). For cross-layer changes also run /verify-api-contract. For new user-visible strings, run /verify-i18n.

Step 6: Code review

Run /simplify for quality. Use /code-reviewer for deeper analysis when the diff is non-trivial. Stage any review fixes via /commit.

Step 7: Completion report

Output a report following references/templates.md. Required fields:

• Summary (file counts, test counts, commit counts)
• Per-feature outcome (when multi-feature)
• Verification results
• Next steps

Standing Rules

• Approval-gated: Step 3 must complete before Step 4. Never skip.
• TDD non-negotiable: tests precede implementation. No exceptions for "trivial" features — they're often where edge cases hide.
• File ownership over parallelism: never spawn parallel workers on overlapping files. Conflicts are deterministic, not probabilistic.
• Conventions over novelty: follow existing project patterns. New abstractions need 3 use sites of justification.
• Commit per unit: feature-sized commits, not megacommits. Each commit reviewable in isolation.
• No half-finished work: if a feature unit fails Step 4, finish or roll back. Never leave partial state on disk.

Procedure (one-time)

/implement <issue-id> runs Step 0 → 7 in order. Skip steps only when explicitly directed (--step N) or when an Exception below applies.

Forbidden

• ❌ Skipping Step 3. The user owns approval; bypass = breach of trust.
• ❌ Implementing without a failing test first. "I'll add tests after" never happens reliably.
• ❌ Two parallel workers touching the same file. The conflict matrix exists for this reason.
• ❌ Committing all features as one giant commit. Reviewers cannot bisect.
• ❌ "While I was in there" refactors mixed into a feature commit. Separate concerns.
• ❌ Adding error handling for impossible cases. Validate at boundaries; trust internal calls.
• ❌ Overriding the user's approval decision because "the right answer is obvious." It isn't.
• ❌ Switching strategy mid-execution (e.g., Subagent → direct) without re-gating.

Pitfall / Known Issues

For failure recovery: every Step has an explicit fail action — Step 4 fail → fix or revert; Step 5 fail → roll back the offending unit; Step 6 fail → re-run Step 4 on flagged files. Never silently skip.

Where this fits in the workflow

brainstorm → /generate-teammate (if multi-domain) → /implement → /review → /ship
                                                       │
                                                       └── This skill builds the feature.
                                                           Pre: requirements settled.
                                                           Post: PR-ready code + tests.

Sequencing principles:

• Before /implement: requirements clear (use /brainstorm if fuzzy). Design doc exists or is intentionally skipped.
• During /implement: each step's exit criterion must hold before the next begins.
• After /implement: hand off to /review (PR review), /ship (release), or /document-release (post-ship docs).

Manual decision gating (automated vs taste)

The automated decisions are deterministic given the same input. The taste decisions require human context the skill cannot infer.

Reflection (end of skill)

After Step 7, write 3 short observations into claudedocs/{issueId}-implement-reflection.md:

1. Test gaps caught — what edge cases did Red surface that the requirements doc missed?
2. Parallelism payoff — was the chosen strategy (direct vs Subagent vs Team) the right call? Where did it stall?
3. Convention drift — did this feature fit existing patterns, or did it suggest a new pattern needs discussion?

These feed into future planning (over time, repeated drift signals a refactor candidate).

Persistent artifacts for downstream

BEFORE / AFTER patterns

Test-first vs implementation-first

❌ BEFORE:

1. Write the implementation
2. Add tests later "to cover it"
3. Realize tests just validate what was built — not the requirement

The tests confirm the bug, not the requirement. Useless for catching the next regression.

✅ AFTER (TDD):

1. Read the requirement; write tests for it (Red)
2. Implement the minimum to make Red turn Green
3. Refactor with green tests as a safety net

Tests express the requirement, independent of implementation. Refactors won't break them.

Single mega-commit vs incremental

❌ BEFORE:

git add -A
git commit -m "Implement feature X"

Reviewer must read 800-line diff. Bisect can't pinpoint regressions. Rollback is all-or-nothing.

✅ AFTER:

commit 1: Add Order entity + repository (BE)
commit 2: Add OrderService + tests (BE)
commit 3: Wire OrderController + integration tests (BE)
commit 4: Add api-client.ts for orders (FE shared)
commit 5: Add OrderListPage + component tests (FE)
commit 6: Add OrderDetailPage + state wiring (FE)

Each commit reviewable, bisectable, revertable.

Parallel without ownership vs with ownership

❌ BEFORE — undeclared shared file:

worker-1 (BE)  → src/api/orders.ts, src/utils/format.ts
worker-2 (FE)  → src/components/Order.tsx, src/utils/format.ts
                                                   ^^^^^^^^^^^^ both touched

Last writer wins. Subtle bug surfaces at integration.

✅ AFTER — explicit conflict matrix:

            worker-1   worker-2
worker-1     —          ❌ shared: src/utils/format.ts
worker-2     ❌          —

Resolution: extract format change to its own commit before parallel work,
            OR assign format.ts to a single owner.

Skill verification

python3 [scripts/validate_skill.py](scripts/validate_skill.py)
python3 [scripts/validate_skill.py](scripts/validate_skill.py) --json

The validator (stdlib only, argparse + --json) checks: frontmatter has the required fields, the workflow has all 8 steps, and the body contains the required policy sections (Forbidden / Pitfall / Where this fits / Manual gating / Reflection). Exits 0 on PASS, 1 on FAIL.

Pre-flight checklist

Before Step 4 (TDD execution), confirm:

• Project recognized (Step 0 outputs captured)
• Requirements clear (from design doc or user dialogue)
• Feature decomposition complete with file lists
• Conflict matrix built (multi-feature only)
• Execution strategy chosen with cited rationale
• User approved via AskUserQuestion (Step 3)

Skill integrations

Exceptions

1. Single-file trivial change: skip parallelization; still TDD.
2. Configuration-only change: TDD not applicable; build verification only.
3. Shared-module change: scan dependents; run their tests too.
4. No CLAUDE.md: ask the user for stack and conventions before Step 1.