Implement the following using test-driven development: $ARGUMENTS
Tests give Claude a self-verification loop. Instead of producing code that looks right, write tests first, then implement until they pass, so correctness is checked by execution rather than by inspection.
| Claude Code Phase | Implement Phase | What Happens |
|---|---|---|
| Explore | Phase 1: Analysis | Read files, trace data flow, check standards |
| Plan | Phase 2: Planning | Chunk decomposition, dependency graph, approval |
| Implement | Phases 3-5: TDD Cycle | Per-chunk: failing test -> code -> passing test |
| Commit | (user-initiated) | Commit when user requests |
| Scope | Approach |
|---|---|
| Trivial (typo, rename, version bump) | Don’t use this skill – just do it directly |
| Small (single-file logic, simple bug fix) | Small feature shortcut (1-chunk tracker) |
| Medium+ (multi-file, unfamiliar code) | Full process |
| Large (cross-cutting, multi-session) | Full process + session resets between chunks |
Small feature shortcut: For single-file or few-file changes with no new domain logic, collapse to: Analysis -> Pre-Test (verify existing coverage) -> Implement -> Post-Test (regression) -> Quality Verification. Use a 1-chunk tracker (see tracker-schema.md §Single-Chunk Features). Only Plan Mode (2.4) and chunk decomposition (2.1-2.2) collapse, Phase 2.5 (review-plan) and Phase 6 (review-impl + red-team) still run; small features carry the same regression risk.
Load these on demand, not all upfront:
| File | When to Load |
|---|---|
| chunk-template.md | Phase 2, when decomposing into chunks (skip for small features) |
| tracker-schema.md | Phase 2.3, when creating the tracker (all features) |
| quality-checklist.md | Phase 2.5 (plan review) and Phase 6 (final verification, or agent-failure fallback) |
Phase 1: Analysis
Phase 2: Planning
└─ 2.5: Plan Review Gate (review-plan agent, blocks Phase 3)
Phase 3: Pre-Test (per chunk)
Phase 4: Implementation (per chunk)
Phase 5: Post-Test (per chunk)
Phase 6: Quality Verification
└─ Gate: review-impl + red-team agents (parallel, blocks completion)
Each phase must complete before the next begins. For multi-chunk features, Phases 3-5 repeat per chunk. Gates are artifact-triggered: the tracker file triggers review-plan (2.5), all chunks complete triggers review-impl + red-team (6).
PROJECT.md, default docs/specs/)
for an existing spec file matching the feature. If found, use it as
primary input, user stories, acceptance criteria, and edge cases
become the basis for chunk decomposition in Phase 2. (Specs are
produced by the companion /spec skill in this plugin, which writes
to the same configurable location.)Context tip: For broad exploration across unfamiliar code, use subagents to investigate. They run in a separate context and report back summaries, keeping your main context clean for implementation.
Load PROJECT.md for build/test/lint commands, architecture rules,
standards, and blindspots, and verify the change aligns with them. If it’s
absent or only template placeholders (YOUR_*_HERE), proceed without it:
infer the test/build commands from the project (build files, CI config,
Makefile), confirm them with the user before relying on them in Phase 3+,
note the miss in the tracker, and suggest creating one.
Common patterns to verify:
PROJECT.mdBreak the feature into implementation chunks. See chunk-template.md.
Rules:
notes field captures pattern hints / pitfalls a resuming
session can’t infer from name + files + tddOrganize chunks into layers:
Layer 1 (no deps): Chunks that can start immediately
Layer 2 (deps on L1): Chunks needing Layer 1 complete
Layer N (final): Regression + quality verification
Create a tracker file following the schema in tracker-schema.md. The tracker is always created, even for single-chunk features (see §Single-Chunk Features in the schema).
The tracker is the single source of truth for progress.
Always update status to in_progress BEFORE starting a chunk.
Why always? The tracker is a file-based artifact that survives context resets. Relying on in-context memory loses state when sessions end or context is compacted. The tracker ensures any session, current or future, can pick up exactly where work stopped.
Enter Plan Mode (Shift+Tab twice from Normal Mode) and present:
Press Ctrl+G to open the plan in your text editor for direct
editing before proceeding.
Get user approval, then switch back to Normal Mode (Shift+Tab)
before proceeding to implementation.
GATE: The tracker artifact from 2.3 triggers this review. Do not proceed to Phase 3 until review completes.
The tracker file is the review input. Spawn the review-plan
agent as a subagent so the reviewer operates in a fresh context
without author bias:
Use the review-plan agent to review [path to tracker]
The agent evaluates 8 criteria against the plan: completeness, correctness, functional gaps, standards, regression risk, robustness, architectural gaps, and TDD quality.
FAIL: update the plan and re-run review-plan. PASS-WITH-WARNINGS: proceed with a note. PASS: proceed to Phase 3. Agent failure (timeout, error): fall back to self-check against quality-checklist.md and proceed.
Record the verdict in the tracker’s top-level plan_review field
(e.g., "plan_review": "PASS") so the gate survives session resets.
| Chunk Type | Test Strategy |
|---|---|
| Data class with logic | Computed properties, boundary values |
| Sealed type / union | Property delegation for each variant |
| Repository / service impl | Conversion helpers, filtering, errors |
| Observer / manager | Lifecycle, debounce, state changes |
| Configuration / preferences | Defaults, type conversions, round-trips |
| Composite / aggregating layer | Merge logic, fallbacks, empty states |
| Interface / trait only | No test (tested via downstream fake) |
| UI: state-holder / hoisted state | TEST, extract holder, unit-test transitions |
| UI: rendering only (no logic) | No test (build + regression) |
| DI wiring / config | No test (verified by compilation) |
| Type migration / rename | No test (verified by compilation) |
State-holder detection: Hoisted state (mutableStateOf,
useState, ref, @State), branching effects (LaunchedEffect,
useEffect with deps), or input transformation = testable logic.
Extract the holder out of the framework component and unit-test
the transitions. “UI = no test” is the most-abused row in this
table; a state machine inside a Composable is still a state
machine.
If the test strategy says “No test,” verify existing coverage is green and skip to Phase 4. Otherwise:
Run the project’s test command (see PROJECT.md) targeting
the specific test class. Confirm tests fail for the right
reason (compile error or assertion failure, not infrastructure).
Set chunk status to in_progress in the JSON tracker.
When adding a dependency to a class or changing a function signature:
When a fix eliminates a code path, remove the dead code in the same chunk. Don’t leave it for a future cleanup pass.
Examples:
Why same chunk? Dead code left behind confuses future readers and creates false grep matches. The person implementing the fix has the best context for what’s now unreachable.
Run the project’s test command targeting the specific test class. All tests must pass. If a test fails, fix the code (not the test) unless the test is wrong about expected behavior.
For intermediate chunks, skip the full suite - chunk tests are sufficient. Run the full suite after the last chunk before Phase 6 (or if a chunk touches widely-shared code).
Check for regressions. Note pre-existing flaky tests but don’t block.
Run the project’s build command. Compilation must succeed.
Set chunk status to complete in the JSON tracker.
Prefer context resets over compaction. A clean session with the tracker as handoff preserves more fidelity than compacted context, which loses information unpredictably.
Between chunks (preferred): Start a new session. The JSON
tracker (name + files_* + tdd + acceptance_criteria + any
notes) gives the new session everything it needs. Use /rename
to name the session for reference.
Mid-chunk (fallback only): If you must compact within a chunk,
run /compact Focus on the current chunk, tracker path, and test
results. This is a fallback, finish the chunk and reset.
After all chunks complete, run the 8-point checklist. See quality-checklist.md for detail:
GATE: All chunks complete triggers parallel review. Spawn two
independent agents in a single message so they run concurrently. Both
are read-only (red-team in both mode reports; it does not apply),
so concurrent runs are safe:
review-impl agent, plan-conformance reviewer. Runs the 8
quality-checklist criteria against the tracker. Answers “does the
implementation match what was planned?”red-team agent (mode: both), adversarial diff reviewer.
Hunts correctness bugs (5 angles) and flags cleanup (reuse,
simplification, efficiency, altitude), verifies each finding
(recall-biased), then sweeps for gaps. Answers “what is wrong or
wasteful in this diff, regardless of the plan?”In parallel:
- Use the review-impl agent to review implementation against [path to tracker]
- Use the red-team agent in mode: both to review the changed files (pass the tracker path)
Complementary by design: review-impl checks conformance to intent
(conservative, PASS when the plan is met); red-team checks
correctness independent of intent (recall-biased, surfaces
everything, then verifies). A bug conforming to a flawed plan is caught
only by red-team; a correct-but-off-spec change only by review-impl.
Merge findings. Address every red-team FAIL (CONFIRMED
correctness) and every review-impl FAIL before completing; treat WARN
as a judgment call. Re-run the suite after any fix.
Why not
/code-review? A skill runs in the main loop and can’t invoke another skill or slash command, so it can’t trigger/code-review(itself a forked subagent).red-teamports the same finder-angle engine into an agent this skill can spawn via the Agent tool. For the cleanup-only pass (the/simplifyequivalent), spawnred-teaminmode: cleanup: only the four cleanup angles, applies safe fixes, skips anything behavior-changing, no bug hunting.
Agent failure (timeout, error): fall back to self-check against the full quality-checklist.md. Document any agent failures in the tracker.
Create or update a reference document when the work will outlive this session, multi-chunk features, deferred follow-ups, bug fixes with a non-obvious root cause, or changes to a subsystem that already has a design/analysis doc. It’s the single source of truth for what was done, why, and what remains, and it survives context compaction.
Skip it for small, self-contained changes whose full story is already in the diff, the commit message, and the tracker’s acceptance criteria. Writing one anyway is scope the user didn’t ask for. When in doubt: would a future session be lost without it? If the diff and commit answer that, don’t write the doc.
When you do write one, cover: what changed and why (bugs found, spec sections, fixes applied); what was tested and confirmed working; what remains (known gaps, future work); test file locations and counts.
If the feature already has an analysis/design doc or issue tracker, update it instead of creating a new one: update implemented-item status, add a commit/version reference, mark remaining items pending.
in_progress BEFORE starting workthrow to continue (resilience fix),
narrow catch scope. Fatal errors (OOM, stack overflow) mean
the runtime is broken, continuing cascades failures. Verify
cancellation exceptions can’t reach the catch siteDo not commit proactively. Wait for the user to request it.
Refer to PROJECT.md for project-specific commit conventions
(author, message format, trailers).
When resuming work on an in-progress feature:
plan_review field, if missing or "FAIL", run Phase 2.5
before proceedingpending chunk where all depends_on are completename, files_create/files_modify, tdd,
acceptance_criteria, and any notes on that chunkTip: Use --resume to continue a named session, or read the
JSON tracker if starting a fresh session on an existing feature.