Skills/implement/SKILL.md

---
name: implement
description: Use when an implementation plan exists under docs/plans and is ready to execute, OR when a debug/tdd RED-test is handed off for the GREEN side. Runs the `implement-loop` Workflow — a deterministic script that executes the per-task loop (implementer → spec-compliance → quality, each a separate agent call) and aggregates in code, writing edits and tests to the working tree without committing. The orchestrator reads the end-report, writes the stats file (and `BLOCKED.md` on PARTIAL/BLOCKED) from the contents the end-report carries, inspects the working tree, decides commit shape, and performs all commits. Also documents the `compiler-driven` light-edit arm.
---

# implement — plan execution on the Workflow substrate

> **Violating the letter of these rules is violating the spirit.**

## Overview

Plan execution runs as the **`implement-loop` Workflow** (shipped at
`workflows/implement-loop.js`, symlinked into `~/.claude/workflows/` by
`install.sh`). The orchestrator invokes it through the Workflow tool;
the script runs the entire per-task loop deterministically — for each
task, implementer → spec-compliance → quality, **each a separate
`agent()` call** dispatching the surviving phase agent-types
(`implementer`, `spec-reviewer`, `quality-reviewer`, and `tester` for
the E2E phase). The inter-phase re-loop, the aggregation, and the
DONE/PARTIAL/BLOCKED verdict are code in the script, not
natural-language reasoning between dispatches.

This replaces the former `implement-orchestrator` agent, which carried
the loop as inline role-switches inside one subagent context because
Claude Code forbids nested-subagent dispatch. A Workflow orchestrates
from the top level, so that workaround is retired: each phase is now a
real, **independently-invokable** agent call, and the routing keys on
the structured verdict each agent reports (which encodes the project's
real build/test outcome). The four phase agents survive unchanged as the
agent-types the script dispatches; only the dispatch/aggregation prose
the orchestrator-agent carried is gone.

All code edits live in the working tree. The stats file and — on
PARTIAL/BLOCKED — `BLOCKED.md` are **built by the script and carried in
the end-report** (`artifacts.stats_json` / `artifacts.blocked_md`): the
script has no filesystem access of its own, and dispatching an agent
just to template the script's own aggregate cost ~41k real tokens per
run (issue #29). The orchestrator writes them byte-identical, filling
the two runtime slots it owns anyway — `{{DATE}}` (`date +%F`) and
`{{FILES_TOUCHED}}` (`git status --porcelain`). The script **never
commits** and never moves main HEAD. The orchestrator reads one
end-report (the workflow's return value), writes the artifacts,
inspects the unstaged tree, and decides commit shape.

## When to Use / Skipping

Triggers:

- A plan exists under `docs/plans` (standard mode → `implement-loop`
  with `mode: "standard"`).
- A `debug` (RED test + cause) or `tdd` (RED executable-spec) handoff
  for the GREEN side (mini mode → `implement-loop` with `mode: "mini"`).

**Never skipped when there is plan-driven or RED-handoff code to ship.**

### The compiler-driven arm (light path)

A **behaviour-preserving type/signature edit at a definition site** —
one the type checker enumerates across N sites, e.g. a carrier/newtype
narrowing or a constructor rename propagated mechanically — does NOT go
through the full per-task loop. It is the `compiler-driven` selector
arm (see `../boss/SKILL.md` "Entry-path reflection"), routed here by a
**positive** trigger matched on the edit's signature, not reached by
elimination.

Its executor is **observe-then-bounce**, shipped as
`workflows/compiler-driven-edit.js`:

1. Make the edit; propagate it mechanically across the sites the build
   flags. Introduce no new behaviour; add or weaken no test.
2. **Run the project's real build + full suite.** This run — not an
   ex-ante guess that the change is "behaviour-preserving" — is the
   oracle.
3. **Done-signal: an edit actually landed AND clean build AND suite
   green unchanged → the edits sit unstaged for the orchestrator to
   commit.** That conjunction is the whole gate; it keeps the light path
   light without letting a green-but-wrong change through. The
   "edit actually landed" conjunct is load-bearing: `clean build AND
   suite green` is *vacuously* true on an empty tree, so a no-op edit
   would otherwise read as DONE. A clean working tree after the edit
   phase is a no-op, not a success → distinct `BLOCKED` (no-op-edit),
   never DONE. Positive evidence (tree differs from HEAD) is required,
   checked both at the edit phase and independently at verify. (A
   malformed or missing carrier is likewise a distinct `BLOCKED`
   (bad-carrier) before any agent runs — never a bounce.)
4. **Bounce** otherwise — the change was not purely behaviour-preserving
   after all, so route up per the straddle rule: a site that forces a
   design decision → `specify`; a site that turns out to **encode new
   behaviour** pinnable as one assertion → `tdd`, RED-first; the suite
   not green-unchanged (a regression surfaced) → `debug`, RED-first. The
   fallible ex-ante guess becomes a cheap ex-post detection.

A truly trivial mechanical edit (a one-line typo, a rename across a
handful of files) the orchestrator MAY still do inline without running
the workflow — but the **same done-signal binds**: clean build + suite
green unchanged, or it bounces. No review-and-commit discipline is shed;
the orchestrator still inspects and commits.

**Hard gate — observed bugs never enter this arm.** An observed bug is
`debug`'s job (RED-first), even when the fix is a one-line type edit.
The selector places the observed-bug check *before* the type-edit arm
for exactly this reason; "the fix is mechanical" must not reroute a
regression around the RED-first gate.

## The Iron Law

```
THE LOOP NEVER COMMITS. CODE EDITS AND TESTS LIVE IN THE WORKING TREE AS UNSTAGED CHANGES UNTIL THE ORCHESTRATOR COMMITS THEM; THE STATS FILE AND BLOCKED.md ARE WRITTEN BY THE ORCHESTRATOR FROM THE CONTENTS THE END-REPORT CARRIES.
WITHIN THIS LOOP, MAIN HEAD IS SACROSANCT — NO RESET, NO REVERT; THE LOOP ONLY EVER WRITES UNSTAGED CHANGES. MAIN MOVES FORWARD ONLY VIA ORCHESTRATOR COMMITS. (THE `/boss` ROLLBACK SANDBOX WINDS BACK ALREADY-COMMITTED AUTONOMOUS WORK — A BOSS-LEVEL RECOVERY, NOT A STEP IN THIS LOOP.)
NO IN-LOOP AGENT EVER DISCARDS WORKING-TREE STATE VIA `git checkout` / `git restore` — WHOLE-FILE OR `--patch`: NOTHING COMMITS BETWEEN TASKS, SO A SHARED FILE CARRIES EARLIER TASKS' UNCOMMITTED DONE WORK, AND A CHECKOUT SILENTLY DESTROYS IT (issue #23). RECOVERY IS FORWARD — EDIT BACK, OR REPORT `BLOCKED`. (THE ORCHESTRATOR'S OWN END-OF-ITERATION `git checkout -- .` DISPOSITION HAPPENS OUTSIDE THE LOOP.)
PER-TASK PHASES ARE SEPARATE AGENT CALLS IN THE WORKFLOW SCRIPT — implementer, then spec-compliance, then quality. SPEC COMPLIANCE IS GATED BEFORE QUALITY.
TASKS RUN SEQUENTIALLY; A BLOCKED TASK STOPS THE LOOP — NO SKIP-AHEAD (TASK ORDERING DEPENDENCIES ARE UNKNOWN).
NEVER PUSH PAST `BLOCKED` BY HAND.
ON `PARTIAL` OR `BLOCKED`, THE END-REPORT CARRIES THE `BLOCKED.md` CONTENT (`artifacts.blocked_md`); THE ORCHESTRATOR'S FIRST ACTION ON READING SUCH A REPORT IS WRITING IT VERBATIM TO `BLOCKED.md` AT THE REPO ROOT — UNCOMMITTED BY CONVENTION. ON `DONE`, `artifacts.blocked_md` IS NULL. (EXCEPTIONS WHERE IT IS ALSO NULL: A NO-OP ITERATION — ITS TREE IS ALREADY CLEAN — AND ANY PRE-LOOP EARLY EXIT (MALFORMED CARRIER, DIRTY-TREE PREFLIGHT, PLAN-EXTRACT GUARD): NOTHING RAN AND NOTHING WAS WRITTEN, SO THE STATUS + `infra:`-PREFIXED REASON RIDE THE END-REPORT AND THERE IS NOTHING TO CLEAN UP OR EXPLAIN.)
`DONE` REQUIRES POSITIVE EVIDENCE THAT AN EDIT LANDED — A NO-OP ITERATION (`git status --porcelain` EMPTY, untracked files INCLUDED) IS NEVER `DONE`, IT IS `BLOCKED` (the issue #11 vacuous-green shape, guarded on the main path). THE VERDICT IS THE GIT TREE COUNT, NEVER A SELF-REPORT.
IN MINI MODE THE RED->GREEN IS OBSERVED, NOT ASSERTED: AN INDEPENDENT VERIFY RE-RUNS THE HANDED-OFF RED TEST AND THE SUITE; A STILL-RED TEST OR A REGRESSION IS `BLOCKED` (route back to debug, RED-first).
THE COMPILER-DRIVEN ARM COMMITS ONLY ON CLEAN BUILD + SUITE GREEN UNCHANGED; ELSE IT BOUNCES (specify for a design hole, tdd for discovered new behaviour, debug for a regression).
```

## Per-task loop mechanics

The script runs, per task: implementer phase, then spec-compliance,
then quality — gated in that order. Each is a separate `agent()` call
with a structured-output schema, so the script branches on a real
verdict. The re-loop limit is **2 repair retries per failure-mode per
task; the 3rd unresolved attempt escalates to `BLOCKED`** — except that
a quality round whose findings are all `Minor`, arriving after at least
one repair dispatch, surfaces them as concerns and closes the task
instead of gating (cosmetic residue must not discard a green task). A
`non_compliant` / `changes_requested` verdict re-dispatches the
`implementer` with the review findings as the repair brief; `unclear`
task text → `spec-ambiguous` BLOCKED; a tooling failure → `infra`
BLOCKED. This logic lives as the loops in
`workflows/implement-loop.js` — the single source; it is deliberately
not restated as prose elsewhere, so the two cannot drift.

**Positive-evidence precondition on `DONE`** (issue #12 — the issue #11
vacuous-green shape on the main path). `build green AND suite green` is
not enough: it is satisfiable by doing nothing. So `DONE` also requires
positive evidence that an edit landed. The verdict is taken from **git
ground truth, never a self-report** — a self-report must never be able to
*fail* a run that actually did the work:

- **Iteration gate (standard mode)** — a dedicated `tree-check` agent runs
  `git status --porcelain | wc -l` after the per-task loop but **before**
  E2E and finalize. A `DONE` outcome with a zero count is a no-op iteration
  → `BLOCKED`. `git status --porcelain` (not `git diff HEAD`) is used so a
  brand-new **untracked** file — the implementer leaves edits unstaged —
  still counts; running before E2E/finalize keeps fixtures and the
  stats/`BLOCKED.md` artefacts from inflating it; and a non-returning agent
  is treated as `BLOCKED` (infra), never waved through. A clean-tree no-op
  writes no `BLOCKED.md` (nothing to clean up — see Step 4).
- **Mini mode gate** — an independent `mini-verify` agent re-runs the
  handed-off RED test and the suite and checks the tree is dirty
  (`git status --porcelain`); a still-red test, a regression, or a clean
  tree is `BLOCKED`. The GREEN is observed, not taken from the
  implementer's self-report.
- **Per-task `applied_changes`** (self-report, OR-ed across the initial
  dispatch and every repair) does NOT gate the outcome — a self-report must
  never be able to *fail* a run that actually did the work (e.g. the initial
  implementer no-ops but a repair writes the files). It feeds only a neutral
  concern when a task wrote nothing (it may be genuinely already-satisfied —
  the orchestrator weighs it).

The E2E phase's `status` is also read now (not just its fixtures): a
non-`DONE` E2E status or a zero-fixture run surfaces as a concern.

**Cross-task discard guard** (issue #23). In a multi-task run nothing
commits between tasks, so one task's file-level `git checkout`/`git
restore` can silently destroy an earlier task's DONE work in a shared
file — invisible to the reviewers (scoped to the current task's
footprint) and to the tree-count gate (the surviving changes keep the
count nonzero). The loop therefore records a snapshot boundary after
every task (`git stash create` — a dangling commit; HEAD, index, and
working tree untouched) and hard-`BLOCK`s when a path that was
HEAD-modified at one boundary is HEAD-identical at the next: the
end-report names the lost paths, the boundary, and the recovery
snapshot sha the discarded content can be read from
(`git show <sha>:<path>`). Coarse by design, in both directions: a
checkout followed by re-edits of the same file, or a `--patch`-level
restore of a single hunk, escapes the comparison (the path never
leaves the diff) — the snapshot still keeps any loss diagnosable and
recoverable; conversely a task that legitimately edits a shared file
back to byte-identical HEAD content trips the guard, so a tripped
verdict means *adjudicate against the snapshot*, not proven malice.
Renames do not trip it (the boundary diff runs `--no-renames`, so a
renamed file's old path stays listed as a deletion). Untracked files
sit outside the threat model (`git checkout -- <path>` cannot discard
them). Cost: one extra sonnet/medium snapshot call per task of a
multi-task run; single-task and mini runs skip the guard. The
detection details live in `workflows/implement-loop.js`, the single
source.

## The Process — orchestrator side

### Step 1 — Run the `implement-loop` workflow

Before invoking: ensure the working tree is clean
(`git status --porcelain` empty). The workflow's preflight refuses to
start on a dirty tree.

For a standard iteration:

```
Workflow({ name: "implement-loop", args: {
  mode: "standard",
  iter_id: "<iter_id>",
  plan_path: "<path under docs/plans>",
  task_range: [3, 8]            // optional
}})
```

For a RED-first handoff from `debug` or `tdd` (mini mode):

```
Workflow({ name: "implement-loop", args: {
  mode: "mini",
  iter_id: "bugfix-<short-symptom>",   // tdd: "feat-<short-behaviour>"
  red_test_path: "<absolute path>",
  cause_summary: "<1-2 sentences from debugger>",   // tdd: the desired-behaviour line
  constraint: "minimal fix, no surrounding cleanup"  // tdd: "minimal feature, no surrounding scope"
}})
```

The carrier fields are defined authoritatively at the top of
`workflows/implement-loop.js`. The load-bearing `iter_id` rule is there
too: it names the scratch dir and the stats filename, NOT a branch
(the loop creates no branch of its own; it runs in whatever checkout
the session sits in — under the worktree convention, the run's
worktree branch).

### Step 2 — Read the end-report

The workflow returns a small structured end-report (its return value):
`status`, `iter_id`, `started_from`, `tasks_total` / `tasks_completed`,
per-task summaries, concerns, E2E fixtures, the `artifacts` block
(`stats_json`, `stats_path_hint`, `blocked_md`), and — on
PARTIAL/BLOCKED — the blocked detail. Per-task chatter stayed inside
the workflow's agent contexts and never reached the orchestrator. Read
the end-report; it is the per-task summary you build the commit body
from. **First action, before anything else:** materialise the
artifacts — write `artifacts.stats_json` to the stats path (fill
`{{DATE}}` with `date +%F`), and when `artifacts.blocked_md` is
non-null write it verbatim to `BLOCKED.md` at the repo root (fill
`{{DATE}}` and `{{FILES_TOUCHED}}` from `git status --porcelain`). The
contents are the script's single-sourced templates — do not rephrase,
restructure, or embellish them. An **infra early-exit** (malformed or missing carrier, dirty-tree
preflight, a plan-extract guard) returns a minimal report instead:
`status: BLOCKED` plus an `infra:`-prefixed `reason`, no `blocked_detail`
and none of the per-task fields — nothing ran.

### Step 3 — Orchestrator inspect + commit step (on DONE)

The workflow returns with code edits sitting in the working tree as
unstaged changes; the stats file was just written by you from
`artifacts.stats_json` (Step 2). Nothing is committed yet, and there
is no `BLOCKED.md` (`artifacts.blocked_md` is null on DONE).

1. Inspect: `git status` and `git diff` — confirm the changes match
   what the end-report claims. The end-report is the per-task summary;
   use it as the basis for the commit body.
2. Decide commit shape — by default one cohesive commit for the whole
   iter; split into a few logical commits only if the diff genuinely
   covers multiple unrelated changes. Per-task commit splitting is NOT
   a goal; the iter is the unit of consistency the orchestrator is
   committing to.
3. Write the commit body. It carries everything a future reader needs
   that the diff itself does not: the *why*, the alternatives
   considered and rejected, the verification steps run, and any
   concerns that remain. Detail-fill comes from the end-report.
   A concern phrased as a *held* or *unresolved quality finding* (the
   per-task quality gate kept a plan-prescribed element against a
   reviewer finding, or a repair was a no-op) is the gate handing you
   the judgement it could not make in code: verify that finding by
   hand against the diff before committing — do not auto-sign past it,
   even under `/boss`. Keep it if it is a principled plan-hold; if it
   is an unaddressed defect, send the iter back rather than commit.
4. Stage + commit the code edits and the stats file.
5. If the trigger is done-state and the user is away, run the project's
   configured notification command per `../boss/SKILL.md` "Done-state
   notifications".

### Step 4 — Orchestrator handling (on PARTIAL or BLOCKED)

The workflow returns with whatever work-in-progress it managed;
`BLOCKED.md` at the repo root carries the diagnostic — written by you
in Step 2 from `artifacts.blocked_md`. Nothing is committed. The
orchestrator decides what to do with the dirty working tree:

0. **No-op `BLOCKED` special case** — if the end-report's status is
   `BLOCKED` with `artifacts.blocked_md` null and a no-op `blocked_detail`
   (the reason names a no-op iteration or a clean-tree no-op fix;
   `files_touched` is 0 in standard mode, null in mini), there is
   **no `BLOCKED.md`** and the tree is already clean. The diagnostic is in the end-report's `blocked_detail`, not
   a file. Nothing to clean up or stash; re-plan or re-run from the same
   clean tree.
   The same no-file shape occurs for an **infra early-exit** (`reason`
   prefixed `infra:` — malformed/missing carrier, dirty preflight tree, a
   plan-extract guard): no `BLOCKED.md`, no `blocked_detail`, and the tree
   exactly as the loop found it. Fix the invocation (or clean the tree) and
   re-invoke.
1. Read `BLOCKED.md` — `## What did not` names the failure mode and the
   blocked task's reason. Read `git diff` to see what was attempted.
2. Decide:
   - **Repair:** keep the working-tree changes in place (or `git stash`
     them if a clarifying read of clean main is needed first). Adjust
     plan or extend context; **delete `BLOCKED.md`** (`rm BLOCKED.md`)
     before re-running the workflow — its preflight clean-tree check
     counts the file as dirt. Either stash everything and re-run on a
     clean tree, or commit the known-good subset, then `rm BLOCKED.md`,
     then re-run.
   - **Discard:** `git checkout -- .` to drop unstaged file changes;
     `git clean -fd` / `rm BLOCKED.md` plus anything else new. main HEAD
     does NOT move.
   - **Escalate:** ask the user via the configured notification
     command. `BLOCKED.md` sits in the working tree until the
     conversation resumes.

Within the `implement` loop the orchestrator does not `git reset` or
`git revert` on main: there is nothing on main to undo — the workflow
never commits, it only writes unstaged working-tree changes. (The one
place autonomous work is ever wound back is the `/boss` rollback sandbox,
which hard-resets *already-committed, unpushed* autonomous commits above
the session anchor on a dead-ended run — a boss-level recovery, not a
step in this loop. See `../boss/SKILL.md` § Direction freedom.)

## Handoff Contract

`implement` consumes:

| Source | Carrier |
|--------|---------|
| from `planner` | path to plan under `docs/plans` (+ optional `task_range`) → `implement-loop` standard mode |
| from `debug` / `tdd` | RED-test path + cause/spec summary + minimal-change constraint → `implement-loop` mini mode |
| from the `compiler-driven` selector arm | a type/signature edit + its definition site → `compiler-driven-edit` workflow |

`implement` produces: an unstaged working tree containing the code
edits and the stats file; on PARTIAL/BLOCKED, also `BLOCKED.md` at the
repo root. The orchestrator inspects, commits the code + stats (DONE)
or repairs/discards (PARTIAL/BLOCKED). The `compiler-driven-edit`
workflow produces an unstaged edit on `DONE`, or a `BOUNCE` verdict
naming `specify` / `debug`. No further hand-off — `audit` runs
independently at cycle close.

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| "Single task, running a whole workflow exceeds the work" | The workflow IS the discipline. Invoking it is cheap; the gated per-task phases and the working-tree isolation are the value. For a genuinely trivial mechanical edit, the inline compiler-driven path exists — but its done-signal still binds. |
| "Let me have the workflow commit the per-task work, it's cleaner" | The workflow never commits. Orchestrator-only commit is a project-wide rule: only the orchestrator decides when a state is consistent enough to enter main history. |
| "Per-task commits would help bisection later" | The workflow's per-task phases are review gates, not bisection points. Iter-level commits are the bisection unit — and they only exist if the whole iter passes review. |
| "BLOCKED end-report, let me dig into BLOCKED.md and continue myself" | Read the `## What did not` section first. The loop stopped at the re-loop limit for a reason. Continuing by hand undoes the discipline. |
| "End-report says PARTIAL with 4/5 tasks DONE — close enough, commit them" | The 5th task may carry an invariant the earlier 4 silently depend on. Either re-run for the missing task or `git checkout -- .` and re-plan. |
| "BLOCKED.md feels redundant — the end-report already has the detail" | The end-report dies when the chat scrolls; `BLOCKED.md` sits in the working tree across pauses and inspection rounds. It is the durable handoff. |
| "The compiler-driven edit built fine, ship it without running the suite" | Clean build is half the done-signal. Suite-green-UNCHANGED is the other half — it is what catches a behaviour change the build can't see. No suite run, no commit. |
| "The compiler-driven suite went red but the fix is one line — I'll just fix it here" | A red suite means the edit was not behaviour-preserving. That is an observed regression → bounce to `debug`, RED-first. Patching it inline reintroduces exactly the green-but-wrong path the bounce prevents. |
| "Nested-subagent dispatch is back via workflows, so an agent can spawn agents" | No. The Workflow orchestrates from the TOP level; the agents it spawns still cannot spawn further agents. The platform constraint is unchanged — the workflow simply does not need nesting. |

## Red Flags — STOP

- Orchestrator dispatching `implementer` directly outside the workflow
  (bypassing the gated loop).
- Orchestrator running `git reset` or `git revert` on main.
- The workflow (or any agent it spawns) running `git commit`.
- Two `implement-loop` runs overlapping on the same working tree.
- `BLOCKED.md` staged or committed by anyone.
- A compiler-driven edit committed without a clean build AND an
  unchanged-green suite.
- An observed bug routed to the compiler-driven arm instead of `debug`.

## Cross-references

- **Workflows dispatched:**
  - `workflows/implement-loop.js` — the per-task loop (standard + mini).
    Single source for the carrier contract, the re-loop limit, the
    stats schema, the `BLOCKED.md` template, and the end-report shape.
  - `workflows/compiler-driven-edit.js` — the observe-then-bounce light
    path for a behaviour-preserving type/signature edit.
- **Phase agent-types the workflow dispatches** (they survive the
  migration; the inline-role-switch orchestrator-agent does not):
  - `agents/implementer.md` — implementer phase (TDD discipline)
  - `agents/spec-reviewer.md` — spec-compliance phase
  - `agents/quality-reviewer.md` — quality phase
  - `agents/tester.md` — E2E coverage phase
- **Selector that routes here:** `../boss/SKILL.md` "Entry-path
  reflection" — the `compiler-driven` arm names this executor, and this
  file names that arm. They are co-located on purpose: a future edit
  re-routing the light path back through the full loop changes both
  cross-references and is a visible regression.
- **Why the substrate, not nested subagents.** Claude Code still
  forbids a subagent from spawning subagents. A Workflow script
  orchestrates from the top level, so the per-task phases run as its own
  agent calls without nesting — see `../docs/design.md` § Plugin layer.
- **Input sources:** `../planner/SKILL.md` (plans), `../debug/SKILL.md`
  and `../tdd/SKILL.md` (RED-test handoff for mini mode).
- **Output target:** orchestrator reads the end-report, inspects, and
  commits; `../audit` runs at cycle close.