# Implement > Execute an approved .specs//spec.md through the TDD Red-Green-Refactor loop, then pass the mandatory reviewer gate before any PR. Use after a spec has been reviewed and approved. - Skill: `m0m0i/implement` (Agent Skill) - Install (CLI): `npx skillmds@latest add m0m0i/implement` - Raw SKILL.md: https://api.skillmd.com/api/skills/m0m0i/implement/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: m0m0i (https://skillmd.com/u/m0m0i) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/m0m0i/implement --- # implement — Build a spec, task by task ## Preconditions - A spec exists at `.specs//spec.md`. If `` is omitted, list the live specs and ask which one. - Its `Status` is `approved`. If it is `draft`, say so and ask before starting — implementing an unreviewed spec is how a misread requirement becomes a merged branch. If it is `done` or `archived`, this is a resume or a mistake; establish which. - The branch is ``. Offer to create it from the default branch. - `.steering/tech.md` names this project's validators and its reviewer. **Read it now; never assume commands.** ## The loop For each task in the spec's Tasks list, in order: 1. **Red** — write the failing test the task names. Run it. Confirm it fails **for the stated reason**, not for a setup error. A test that fails because of a typo has proved nothing. 2. **Green** — the smallest implementation that passes. Run the tests. 3. **Refactor** — clean up under green tests. Re-run the validators. 4. Tick the task, then make one commit scoped to that task, in this project's commit convention (see `.steering/tech.md`). ## Review gate — mandatory When every task is committed and the validators pass: 1. Run the full validator set from `.steering/tech.md`. Set the spec `Status: done`. 2. **Invoke the reviewer subagent** named in `.steering/tech.md`, asking it to review the branch diff against the default branch, and against `.specs//spec.md`. **Invoke it and wait for its result in the same turn. Do not spawn it and carry on.** The review gate runs on turn end, so it assumes the review finished inside the turn. **If your harness returns from the invocation immediately and notifies you later, waiting means keeping the turn open** — keep issuing read-only calls until the result arrives, and emit no final message before it does. Completion normally arrives as a notification without being asked for; if your harness lists running agents, that listing can be polled instead. A turn that has not ended cannot trip a gate that fires on turn end. Announcing that you are waiting *is* ending the turn, and it re-arms the gate every time — that mistake cost twenty-five turns in the repository this harness was built in. Nothing useful can happen during a review anyway, because touching the files it is reading is exactly what must not happen. If the reviewer genuinely cannot be invoked at all — not registered, added mid-session and needing a restart, or the harness has no subagents — run its procedure yourself from its agent file and record `reviewed_by=inline`. 3. Address every **BLOCKER** and **HIGH** through the TDD loop: a failing test, then the fix. Re-run the reviewer until none remain. Triage MEDIUM/LOW/INFO explicitly — fixed, or recorded with a reason. 4. **Write the receipt.** The reviewer is read-only, so you record its result at `.specs//.review-receipt`, copying its Receipt block verbatim: ``` reviewed_sha= reviewer= verdict=CLEAN|BLOCKED blockers= high= reviewed_at= reviewed_by=subagent|inline ``` `reviewed_by` records **how** the review was obtained, not who ran it. `subagent` means the reviewer ran as its own agent, outside this session's context, which is the independence the whole layer exists to provide. `inline` means step 2's fallback was taken and the author of the diff ran the reviewer's procedure themselves — still useful, since it finds real defects, but not independent, and a reader of the receipt cannot tell the difference unless you write it down. **Never record `subagent` for a review you ran inline.** It is the same lie as a receipt for a review that did not happen, one step quieter. The review gate reads this file and refuses to end a turn when a spec whose tasks are all ticked has no receipt, a non-CLEAN one, or one whose `reviewed_sha` predates a later source change. **Never write a receipt for a review that did not run.** The gate catches omission and staleness; a fabricated receipt defeats the only mechanical check in the flow, and it defeats it silently. 5. **Bump the version, if this project carries one.** `.steering/tech.md` says whether a release moves a version and which paths count as shipped. **The version bump lands here, after the receipt — never as a task.** The review gate arms when a spec has no unticked tasks, so a task held back until after the review keeps one box unticked for the whole review, and the gate stays silent through exactly the stretch it exists to cover. That is #113, found on a spec whose last task was the bump. The bump belongs with the other work that lands after the receipt, not in the Tasks list. A manifest normally sits outside the project's `Source globs`, so this does not re-stale the receipt; if it sits inside them, re-review. 6. Run `worklog`. The entry is committed on this branch, so it ships inside this issue's single pull request rather than in one of its own. Then summarize the diff and propose that PR, closing its issue. **That PR is the last step. Do not propose archiving, and do not open a follow-up pull request for it.** Moving a shipped spec into `.specs/_archive/` is a sweep run on request, whenever `.specs/` has grown noisy enough to be worth a minute — a `git mv` is not a change that earns a branch, a review and a merge of its own. Nothing downstream is waiting on it either: the review gate reads `.specs//spec.md` and cannot see a shipped spec still sitting in `.specs/`. ## Rules - **Never write implementation code before its failing test exists.** - One task, one commit. No batching, no half-tasks. - **A task is one COMPLETE Red-Green-Refactor cycle, so a task ends green and is one commit.** Red and green are not separate tasks. The quality gate runs the project's validators on turn end, so a task that is only the red half cannot be committed without ending the turn red — the harness would be blocking its own prescribed workflow. If you are holding a spec whose tasks still split the pair, fold them as you go and say so; the templates were fixed in #10 but a spec written before that keeps the split it was authored with. - **If a task proves the spec wrong, stop.** Amend `.specs//spec.md`, say what changed and why, and get agreement before resuming. Do not code around a spec you no longer believe. - Match the surrounding code. `.steering/structure.md` says where code belongs. - Do not open a PR before the reviewer pass is clean of BLOCKER/HIGH. - Commits landing **after** the review — the work-log entry, the `Status: done` flip, the version bump — do not invalidate the receipt; the gate only re-triggers when reviewable source changes. Fixing a finding *is* source: re-review, and rewrite the receipt.