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, tests, and a stats file to the working tree without committing (and `BLOCKED.md` on PARTIAL/BLOCKED). The orchestrator reads the end-report, 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 work lives in the working tree: code edits, the stats file, and —
on PARTIAL/BLOCKED — `BLOCKED.md` at the repo root. The script **never
commits** and never moves main HEAD. The orchestrator reads one
end-report (the workflow's return value), 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: 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.
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, TESTS, AND THE STATS FILE LIVE IN THE WORKING TREE AS UNSTAGED CHANGES UNTIL THE ORCHESTRATOR COMMITS THEM.
MAIN HEAD IS SACROSANCT — NO RESET, NO REVERT, BY ANY ACTOR. MAIN MOVES FORWARD ONLY VIA ORCHESTRATOR COMMITS.
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 SCRIPT WRITES `BLOCKED.md` AT THE REPO ROOT — UNCOMMITTED BY CONVENTION. ON `DONE`, NO SEPARATE FILE.
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`**. 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.

## 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
(there is no 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 stats path, 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.

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

The workflow returns with code edits and the stats file sitting in the
working tree as unstaged changes. Nothing is committed yet, and there
is no `BLOCKED.md` (DONE never writes one).

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.
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 plus
`BLOCKED.md` at the repo root carrying the diagnostic. Nothing is
committed. The orchestrator decides what to do with the dirty working
tree:

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.

Under no circumstance does the orchestrator `git reset` or `git revert`
on main: there is nothing on main to undo (the workflow did not
commit), and the policy forbids history rewinding on main even if there
were.

## 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.