implement

Files (2)

• SKILL.md
• STEPS.md

SKILL.md (first lines)

You are the **driving session**: you orchestrate, sub-agents plan, implement, review, and verify. You hold the Step index, each sub-agent's short report, the findings that go back to the next Iteration, and any deviations — that is the whole of your context, and it is what lets a Spec of any size land inside one session. So you hand paths, and the sub-agent that needs a document reads it. While a sub-agent runs, waiting is the work.

A **Planner** first slices the Spec into **Steps**, each small enough for one fresh agent; most Specs are one Step. Then the run is a loop over the whole Spec, at most three **Iterations** ([ADR-0072](../../docs/adr/0072-implement-plans-steps-then-loops-implement-review-verify.md)):

1. **Implement** — on Iteration 1, a fresh `skills:implementer` builds each Step in order; on a later one, a single fresh Implementer fixes what the last Iteration found.
2. **Review** — `/code-review` judges the diff on its Standards axis: the repo's Coding standards and the design principles. A **Hard violation** sends the run back to 1; a **Judgement call** waits for the next Implementer, or the final report. From Iteration 2 on, Review reads only that Iteration's fix.
3. **Verify** — a fresh `skills:verifier` checks the change does what the Spec asks: the Spec read against the diff, the build and the whole test suite, and the Spec's Hand checks. A finding sends the run back to 1.

The run lands when one Iteration passes both Review and Verify. The Planner, the Implementer, and the Verifier are pinned in their agent files (`agents/planner.md`, `agents/implementer.md`, `agents/verifier.md` at the plugin root) to Sonnet at high effort, because the Spec was decided before they started; the Reviewer `/code-review` starts is pinned to Opus at high ([ADR-0049](../../docs/adr/0049-agents-are-pinned-in-their-agent-files.md)).

Every sub-agent closes leftover gaps from the documents it was handed and the code. See [ADR-0026](../../docs/adr/0026-implement-agents-close-leftover-gaps.md).

No sub-agent pushes, publishes, or changes a live system; work that needs that **halts**. The run reaches outside the local checkout twice: the **claim** on its Issue, so concurrent runs skip that Issue, and [the push](#the-push) of `<base>` once it has landed. Its `/retro` may also file an Issue or comment on one. The closing reference its landing commit carries is how the Tracker learns the work is done. Under [benchmark mode](#benchmark-mode) it reaches outside zero times. See [ADR-0028](../../docs/adr/0028-implement-claims-its-issue-and-pushes-only-what-lands.md) and [ADR-0001](../../docs/adr/0001-each-repo-describes-its-tracker.md).

## Process

### 1. Enter the worktree

Issues live in the repo's **Tracker**: carry out each operation on one — file, read, list, rewrite, set status, comment, link, claim, close — as `.agents/refs/tracker.md` says, or as [setup/LOCAL.md](../setup/LOCAL.md) says when the repo has no ref.

The argument is an Issue reference — normally an Issue in `ready-for-agent` — or a description of the change, which touches no Tracker; an issue outside this repo's Tracker is read as a description. A description is the Spec: it gets no interview, and the user who wants one runs `/grill-with-docs` first. Read the Issue. Derive `<slug>`: the Issue's run slug as the Tracker ref gives it, otherwise a kebab-case slug from the description.

When this session already drives the run for `<slug>` and a sub-agent it dispatched for that run has not reported yet, this invocation is a repeat and the run is still going: say so, and keep waiting for that report. A repeat claims, resets, and dispatches nothing ([ADR-0064](../../docs/adr/0064-a-repeated-implement-command-waits-for-its-run.md)).

`<base>` is the **base branch**: `git branch --show-current` in the original directory when this command starts, read again on a resume. The run branches from it, is reviewed and verified against it, and lands back on it ([ADR-0055](../../docs/adr/0055-a-run-lands-on-the-branch-it-started-from.md)). If it is empty, **halt** — HEAD is detached. The main checkout's working tree is the user's and stays as you found it until step 4.

An Issue blocked by another Issue waits on it: while the blocker is open, stop before anything else and say it lands first — unless `<base>` already holds the blocker's closing reference, found as the Tracker ref says ([ADR-0047](../../docs/adr/0047-a-wayfinder-map-ends-in-one-or-more-specs.md)).

Then claim the Issue as the Tracker ref says. When the ref says another user holds it, stop and name them. A ref that gives no claim for Issues skips this.

Find worktrees with `git worktree list` (or the host's equivalent). The **run worktree** is the one whose branch is `<slug>` (or the name a host tool recorded). A prior run is **in flight** when that run worktree exists, when branch `<slug>` exists, or when any linked worktree contains `.agents/runs/<slug>/`.

- **In flight** → a run worktree whose lock names a live process is another session's run: stop and say so. Otherwise:
  - Put the session's working directory on the run worktree's path. When the branch exists without a worktree, `git -c checkout.workers=0 worktree add` at `.agents/worktrees/<slug>` on branch `<slug>` first (ensure `.agents/worktrees/` is ignored; prefer a local ignore when the repo uses one).
  - `git reset --hard && git clean -fd` drops whatever a halted sub-agent left behind. If the host refuses the reset, `git stash push -u` and name the stash in the final report.
  - When `.agents/runs/<slug>/` holds Step files (`[0-9][0-9]-*.md`), the Steps are already planned: skip step 2 and resume Iteration 1 of step 3 at the lowest-numbered Step whose `Status:` is not `done`, or at its Review when every Step reads `done`. With no Step files, continue at step 2. The branch's commits are the work so far; the Implementer builds on them.
- **Fresh** → open a worktree for this run, put the session's working directory inside it, then `git reset --hard <base>` so the run starts from the `<base>` you actually have — the new branch has no commits of its own yet:
  - If this host has a tool that **creates the worktree and moves the session into it**, use that tool — even when its path is not the fallback below. Decide from the tool list you already have rather than searching the host's CLI or docs. Record the branch name it chose when that name is not `<slug>`.
  - Otherwise ensure the consuming repo ignores `.agents/worktrees/` (add the line if missing; prefer a local ignore when the repo uses one), then `git -c checkout.workers=0 worktree add` at `.agents/worktrees/<slug>` on branch `<slug>`, and change the session's working directory there.

The session must work *inside* the run worktree for the rest of the run — creating a worktree alone is not enough. Run every command from there as a **plain** command: every argument spelled out, and files written with the host's file tools. A host that isolates the session in its worktree refuses a command it cannot prove stays inside, such as one with a `cd` or `git -C`, a shell variable, `$(…)`, or a heredoc, and says how to split it. Scope every search to the worktree, and name it in every sub-agent prompt as the only directory the agent works in. On a host whose shell starts every command in the original directory, resolve the worktree's absolute path once with `pwd` inside it and begin every command with `cd <that path> &&`. An `/implement` prompt that explicitly waives the worktree takes the branch in [Worktree waived](#worktree-waived) instead.

Before leaving this step, when `.agents/runs/<slug>/spec.md` is missing, write **the Spec** to it — the Issue's title as an H1 and its body, or the description as the argument gave it — and nothing else, then commit it as `spec: <slug>`. The commit keeps it through a resume's reset. From here on every sub-agent reads that copy, and a resume reads it rather than the Issue.

`<scratch>` is `.agents/runs/<slug>/scratch/`, by absolute path: the Verifier's throwaway scripts, screenshots, and transcripts. Create it when it is missing, with a `.gitignore` inside that holds `*`, so no commit sweeps it in. The land deletes it with the run folder; a halt leaves it.

### 2. Plan the Steps

Dispatch a `skills:planner`. Give it the Spec's path, `<slug>`, and the absolute path to [STEPS.md](STEPS.md) in this skill's directory — those three and nothing else. It reads the slicing rules itself, writes one Step file per Step to `.agents/runs/<slug>/`, and commits them before returning, so the resets later in the run cannot delete a Step not yet built. When `git status` still shows Step files afterwards, commit them yourself as `plan: <slug>`.

It returns the index and nothing else: one line per Step, `NN | title | one-line deliverable`. Tell the user how many Steps it planned, with their titles.

The plan succeeded when that reply is the index and `.agents/runs/<slug>/` holds Step files. Otherwise the Planner gets the retry in [The limit](#the-limit), and a second failure **halts** the run. The commit above is your only write in this step: the Step files are the Planner's to write.

### 3. Loop

Run Iterations, numbered from 1, until one passes both Review and Verify. Each Iteration is the three parts below, in order.

#### Implement

On Iteration 1, run each Step in `NN` order, skipping a Step whose `Status:` already reads `done`; its Implement is done when every Step file, `.agents/runs/<slug>/[0-9][0-9]-*.md`, reads `Status: done`. On a later Iteration, run one Implementer for the findings, with no Step file.

Hold `git rev-parse HEAD` as `<start>` before the Iteration's first dispatch. For each dispatch, hold `git rev-parse HEAD` as `<before>`, then dispatch a fresh `skills:implementer` with a prompt of paths and section names — it reads what is behind them:

- the Spec, and `<base>`, the branch its tests are measured against
- on Iteration 1: its own Step file, and an instruction to read the `## Outcome` of every lower-numbered Step file before starting
- `CONTEXT.md` and any ADR covering the area it touches, for vocabulary
- the Coding standards, found the same way `/code-review` finds them — `.agents/refs/` first, then a root-level coding-standards or contributing file when that is what the repo has; only documents that say how code should be written — when those exist
- the design principles, [PRINCIPLES.md](../code-review/PRINCIPLES.md) in the `code-review` skill's directory by absolute path — the Review judges the diff by them and by the Coding standards
- the Spec's Testing Decisions section, when it has one, which governs what it tests, and the testing documents it names
- from Iteration 2 on: every Hard violation and Verify finding the last Iteration reported, and every Judgement call held, verbatim; and every finding an earlier Iteration declined, with its reason
- the deviations reported so far, verbatim, when there are any
- its Iteration number and the limit of three, on Iteration 1 its Step number and the total, and the report format below

Require of it: **its build and the tests closest to its change passing before it finishes**, and its work committed. The whole suite is the Verifier's to run. On Iteration 1, it builds every project on its Footprint's `Projects:` line, appends a short `## Outcome` to its Step file (what it built, where the code differed from the Footprint, and what a later Step needs to know), sets that file's `Status:` to `done`, and commits the file with its code. From Iteration 2 on, it fixes every Verify finding, and fixes each Review finding or declines it on its `declined:` line with the reason. A Review finding that contradicts the Spec is declined: the Spec wins.

Its entire response is four lines:

```
status: done | blocked
built: <one sentence on what now works, or what it fixed>
declined: <each Review finding left as it is, with why — or "none">
deviations: <what contradicts the Spec or changes a later Step, or "none">
```

Then **check it structurally**: `git rev-parse HEAD` differs from `<before>` and `git status` is clean, or every finding it was handed is on its `declined:` line and HEAD has not moved. On Iteration 1, `grep '^Status:'` on its Step file also reads `done`. That is the whole check; read the diff only when it fails. Tell the user `Step <NN>/<total> — <title>: done` after each Step passes it.

#### Review

**Run `/code-review` yourself** on the Standards axis alone. The fixed point is `<base>` on Iteration 1, so the first Review reads the whole change. From Iteration 2 on it is `<start>`, so a later Review reads only that Iteration's fix; when HEAD has not moved from `<start>` because every finding was declined, it is `<base>` again, and the Review judges the declines alone. Tell it:

- the Spec's path, `.agents/runs/<slug>/spec.md`
- that `.agents/runs/<slug>/` is run bookkeeping, not code under review
- that only agents read its report
- every finding declined so far with its reason: a declined finding is raised again only when the reason does not hold, and the report says why
- from Iteration 2 on, every finding the last Implementer was handed, to judge as fixed or declined, with the fix itself judged against the standards

Hold the Standards report; weigh it on the report alone. `/code-review` opens each finding with `Hard violation:` or `Judgement call:`. Hold its Judgement calls with any held from earlier Iterations until the next Implementer is handed them.

Review passes when the report has no Hard violation. Tell the user `Iteration <N>/3 — review: passed`, with `(<j> judgement calls)` after it when there are any, or `Iteration <N>/3 — review: <h> hard violations, <j> judgement calls`, then go on without waiting: a passed Review goes to Verify; a Hard violation starts the next Iteration at Implement, with Verify skipped.

#### Verify

Dispatch a fresh `skills:verifier` with a prompt of paths: the Spec, `<base>`, the Spec's Testing Decisions section when it has one, `<scratch>`, and the report format below.

```
status: passed | failed | blocked
deviations: <failures red on <base> too, tests that passed only on a re-run, Hand checks skipped with what they need — or "none">
findings:
- <one line per Spec requirement missing, partial, or wrong; scope the Spec did not ask for; a red test; a Hand check that failed twice — or "none">
```

Tell the user `Iteration <N>/3 — verify: passed`, or `Iteration <N>/3 — verify: <count> findings`. `passed` goes to step 4. `failed` starts the next Iteration at Implement.

#### The limit

An Iteration 3 that ends on a Hard violation or a Verify finding **halts** the run, and the halt report quotes those findings. Judgement calls alone never halt a run.

A `blocked` report, a failed structural check, or any result that is not the report — a question, a progress note, a pause to wait on a background run — earns exactly one retry, for the Planner, each Implementer, and the Verifier alike, and the retry is not a new Iteration. When the host can resume the same agent, resume it once with one line: the work is still yours to finish; return the report. Otherwise `git reset --hard && git clean -fd`, then re-dispatch the same agent with the same prompt, appending a test or environment failure in its own words, or that the previous run returned something other than the report. Commits it made survive that reset. A second failure **halts** the run.

From michielvandermeer/skills, MIT.

More from michielvandermeer/skills