Implement

---
name: implement
argument-hint: "<ticket> [--stop-after-tests | --fix | --finish]"
description: "Implement a piece of work based on a spec or set of tickets."
disable-model-invocation: true
---

Implement the work described by the user in the spec or tickets.

## What runs

The flag after the ticket number decides which sections run:

| Call | Sections, in order |
|---|---|
| `/skillworks:implement <n>` | Before you start, Building, Reviewing, Fixing, Sweeping comments, Running the suite, Finishing |
| `/skillworks:implement <n> --stop-after-tests` | Before you start, Building |
| `/skillworks:implement <n> --fix` | Before you start, if this session has not read the ticket; then Fixing |
| `/skillworks:implement <n> --finish` | Before you start, if this session has not read the ticket; then Finishing |

The order is the spec loop's own, so the developer at the keyboard and the driver follow one set of rules. Each flag is there because the driver calls that section as a step of its own.

## Before you start

If a ticket number was given, fetch it, and fetch its parent spec too — the ticket is the what, the spec is the why. `tracker` in `docs/agents/loop.json` names the Tracker, and `docs/agents/issue-tracker.md` says how to read each one. With the files Tracker a ticket comes as `<spec>/<ticket>`, such as `7/2`, because its number is local to its spec.

If `docs/agents/loop.json`, `docs/agents/issue-tracker.md` or `docs/agents/suite.json` is missing, stop. Tell the user which file is missing, that `/skillworks:skillworks-setup` writes it, and that nothing was done. Begin that report with the `BLOCKED` line, as Blocked says below.

**Refuse a blocked ticket.** A ticket with an open blocker is not ready. With the GitHub Tracker, ask, with the ticket number in place of `<n>`:

```bash
gh api "repos/{owner}/{repo}/issues/<n>" --jq '.issue_dependencies_summary.blocked_by'
```

`gh api` fills in `{owner}` and `{repo}` from the repo you are in. Anything but `0` means stop, name the open blockers, and do nothing else. With the files Tracker, a ticket is blocked while any ticket in its `blocked-by` is open on the remote's Target branch.

A ticket with an open blocker is work you cannot do, so begin that report with the `BLOCKED` line, as Blocked says below.

## Test runs

Tests, typechecks and lints are deterministic validation: their result, not your expectation of it, decides the next step. Run each one in the foreground, with a timeout long enough for it to finish, and read its result before your next action. A caller may drive you with `claude -p`, which ends the session the moment your turn ends, so a run still going at that moment is lost, and so is the commit it would have allowed.

## Blocked

A step is Blocked when you cannot do its work: a tool call was denied and no allowed way exists, or the ticket has nothing left to build. Begin your report with one line that starts with `BLOCKED` and says what blocks the step, such as:

    BLOCKED .claude/settings.json: the write was refused as a sensitive file.

Say the rest below that line. A driver stops its loop on that line, so a person reads it before more work is spent. A tool call that was denied, and that you then made in a way the rules allow, blocks nothing and earns no line.

## A write under `.claude/` refused

A write under `.claude/` is refused as a sensitive file. No allow rule lifts it, only the permission mode does, so the refusal is the harness and not a fault in the call you made. Do not try the write again, and do not route around it with a shell redirection, a patch command or any other tool.

One refused write blocks one line of the ticket and nothing else. Do every other part of the ticket, and run the tests over what you did write. Then:

1. **Commit the verified work**, with the ticket named in the message as Finishing says. Under `--stop-after-tests` and under `--fix` the run ends before Finishing, so the change stays uncommitted, as Building and Fixing already say.
2. **Leave the ticket open.** Work that is not done is not closed, and the driver reads the `BLOCKED` line as the stop. This holds through Finishing as well: commit as its step 3 says, and skip the close in its steps 2 and 5. Under the spec loop, a later message that tells you to close the ticket does not change this, because the driver sends that message for every ticket still open, whatever kept it open. Begin your answer to it with the `BLOCKED` line, and close nothing.
3. **Write the wall on the ticket.** Comment with the exact path, the exact change you could not write, and that the write was refused as a sensitive file. A developer has to be able to make that change from the comment alone, without opening anything else. With the files Tracker, write it at the end of the ticket file under `## Blocked`, in the commit, and leave its `status` open.

Begin your report with the `BLOCKED` line, and say the same below it, so it reaches the driver's log as well.

## Building

For every change that has behaviour to test, call the Skill tool with "skillworks:tdd".

Run typechecking and single test files regularly.

**A test that a check with an image runs is run as a Trial, and never on the host.** A check with `image` in the Suite file `docs/agents/suite.json` runs in a container, and its tests can take many times as long on the host. Start from that check's own `command`, runner options included, and narrow only its paths and filters, such as a test file and `-k`:

```bash
skillworks-suite --image <the check's Dockerfile> -- <the check's command, narrowed>
```

A Trial prints the command's output and returns its exit code. It keeps no Proof, so it never stands in for the Suite. A test of a check with no image runs on the host as before.

To check the work against the whole Suite, run `skillworks-suite`, never the test commands the Suite file names. It keeps a Proof of each check that passes, so a check whose inputs have not changed does not run again. In a loop the driver runs the Suite as a step of its own, and it reads the Proofs your run kept.

Building is done when the typecheck is clean and every test the change adds or touches passes.

With `--stop-after-tests`, leave the change uncommitted and the ticket open, and report which tests pass.

## Reviewing

Call the Skill tool with "skillworks:review-changes", the skill a person types as `/skillworks:review-changes`, on the uncommitted change, and give it the ticket number. An uncommitted change carries no `Ticket:` trailer, so the Spec axis has nothing to find the ticket in unless you pass it.

Its fan-out to sub-agents needs a session still awake to read what comes back, so a headless run cannot use it. That is why the spec loop runs the three axes as three steps of its own instead, and why the difference stays.

The findings it returns are what the Fixing section acts on.

## Fixing

Work reaches this section three ways, and it covers all of them:

- **Under the spec loop**, `--fix` selects it. Each axis has run in a session of its own, and the reports arrive in this prompt under the axis that wrote each one, each beside the Edit that axis made.
- **Under the spec loop after a red suite**, `--fix` selects it a second time. The prompt carries the three reports again and, beside them, the output of a suite the driver ran as often as the Suite file asks and saw fail every time.
- **Under a hand run**, the Reviewing section produced them in this same session.

1. **Fix every finding, from every axis.** Under the spec loop an axis fixes what it finds, so the Edit beside a report says what is already done — read the change before you fix the same thing twice. Under a hand run the axes only report, so nothing is fixed yet.
2. **Settle a disagreement.** This is the one session holding all three reports at once, so a contradiction between two axes is settled here and nowhere else.
3. **Leave a judgement call you judge wrong**, and keep the reason for the Closing note. A judgement call may be left, with its reason. A hard breach is always fixed and never left, whether it breaches a team check or a rule marked hard, and so is a moved name.
4. **Fix a failing suite the prompt carries.** The driver ran the whole suite as often as the Suite file asks and read a failure every time, so treat it as the work. Make the suite green. Do not weaken a test to get there, and say so in your report if the failure turns out to be nothing this ticket caused.
5. **A prompt carrying neither a report nor a failing suite has nothing to fix**, so go straight on.

Run the tests of a fix as Building runs them: a test that a check with an image runs is run as a Trial, and never on the host.

Leave the change uncommitted. The sweep has still to run, and committing is Finishing's job.

## Sweeping comments

Call the Skill tool with "skillworks:comment-sweep", the skill a person types as `/skillworks:comment-sweep`, on the uncommitted change.

It runs after the findings are fixed, because anything that writes after a sweep puts back the comments the sweep cut.

## Running the suite

Run `skillworks-suite` with no arguments, so that it covers every check the Suite file `docs/agents/suite.json` names, and read its passing result. A partial pass or a skipped suite leaves the ticket open.

Under the spec loop this section never runs. The driver runs the suite as a step of its own, reads the result itself, and hands the passing output to Finishing, so the gate that says a ticket is done rests on nothing a session said about itself.

## Finishing

Run no review of your own, and fix no finding here. Under the spec loop the three axes — Standards, Spec and Architecture — have each already run in a session of its own, and `fix` has already acted on what they found. Under a hand run the Reviewing and Fixing sections have already done the same. A review run again here would be the same work twice, and the two could disagree.

Run no tests here either. One step owns that gate: under the spec loop the driver ran the whole suite and put the passing output in this prompt, and under a hand run the section above has just run it. A result reported here would be one nobody else saw.

1. **Read the passing suite output you were handed.** The checks that ran are what proved the work, and the Closing note names them. A check that did not run has a line of its own in that output, saying it did not run and naming the Proof that holds its inputs: an earlier pass on the same files. The Closing note names each such check and its Proof beside the ones that passed, so a reader sees what this run proved and what an earlier one did. Where no line says a check did not run, every check ran, and the Closing note says nothing about checks that did not run. A check that went red and then passed is a Flake, and the output lists each one under `## Flakes` with the file that keeps its red output. The Closing note names each Flake and its kept file, so the ticket's record says its green took more than one run. Where the output lists no Flake, the Closing note says nothing about Flakes.
2. **With the files Tracker, close the ticket now**, before the commit. Set `status: closed` in the ticket file and add its `## Closing note`, as "The files Tracker" in `docs/agents/issue-tracker.md` says. The note holds what step 5 posts as the Closing note on GitHub. The close then sits in the same commit as the code, so it reaches the remote only when the ticket Lands.
3. **Commit to the branch you are on.** Under the spec loop that is the Job branch, and the ticket Lands on its Target branch later. Under a hand run it is the Target branch, which `target-branch` in `docs/agents/loop.json` names; when that says `spec`, it is the branch the spec names, under `## Branch` on GitHub or as `branch` in `spec.md` with the files Tracker. Do not push. A spec loop pushes the ticket itself, by a step of its own that runs after this one, so the push is checked rather than taken on trust.
   - **Name the ticket in the message.** See "Two conventions the loop leans on" in `docs/agents/issue-tracker.md` for the form, and for why it is not a closing word. With the files Tracker the trailer names the spec and the ticket, as `Ticket: 7/2`.
4. **Leave the working tree clean.** A caller may be driving you in a loop and will stop if it is not.
5. **With the GitHub Tracker, close the ticket** with a comment saying what was done, which tests prove it, which checks did not run, each Flake and its kept file, any finding left unfixed with the reason, and each question the ticket puts to a person with the answer the build gave, so the developer can change that answer later from the ticket. With the files Tracker, step 2 has closed it already.