Sw Implement

---
name: sw-implement
description: Use when the user wants to implement, build, execute, start or continue a Superwiki task or its plan, or invokes sw-implement or sw:implement, with or without a task id.
---

# sw-implement

Runs one task. You keep the task's status true and judge the result. The work is done by subagents that start from a clean context, on the models set in sw-config: an implementer, and a reviewer when the task asks for one. You do not read the code or the plan: their reports are your input. Before the task is closed you summarize it yourself, with a command run for every "Done when" item.

That split is what keeps a task cheap. A long session sends its whole context again on every step; work done in a fresh context does not carry yours, and yours stays small because the work never enters it.

Run commands from the project root. `<skill-dir>` is the directory this SKILL.md is in.

## Steps

1. **Pick the task.** Id given: use it. Otherwise `node docs/.sw/sw.mjs ready` and let the user choose; tasks already in progress come first.
2. **Gate**: `node docs/.sw/sw.mjs check <ID>`.

   | `check` says | Do |
   | --- | --- |
   | `can start: no  open deps: ...` | stop. Tell the user which tasks block it and offer to run the first blocker instead; do not run it unasked. Do not start the task anyway, and do not edit `deps` to get past this |
   | `can start: n/a, status is in-progress` | this is a continuation; skip step 3 |
   | `can start: n/a, status is done` or `cancelled` | stop and ask what the user wants |
   | `plan: ... (draft, not approved)` | stop; the plan needs the user's approval (sw-plan) |
   | `plan: none` | fine for a small task, by the rule below this table. Also fine when the task's "Notes" hold an `Approach (sw-do, ...)` note: sw-do chose the medium route. For anything else, recommend sw-plan first and let the user choose |
   | `review: required (...)` | remember it for step 7 |
   | `can finish: no` and `summary: none` | expected before the work: the summary is written in step 8 |

   The rule for a small task, word for word as sw-do and sw-plan state it:

   A task is small when its task file alone shows all four: one area, meaning its work belongs to the configured area its id prefix names and to no other (`areas` in `docs/.sw/config.json`; with one configured area, every task is in one area); three "Done when" items or fewer, as the `done when:` line of `node docs/.sw/sw.mjs check <ID>` counts them; nothing left open in its "Notes"; and the files that change, named in the task file, three or fewer. A task whose file does not show how many files change is medium at least, never small.

3. **Mark it started** before any work:
   - in the frontmatter of `docs/tasks/<ID>.md`, `status: in-progress` and `started:` today;
   - in `docs/log.md`, a new entry `## [date] task | <ID> started`, in the layout its last entries use;
   - `node docs/.sw/sw.mjs board`, so the task list in `index.md` shows it.
4. **Checks that need the environment.** A check needs the environment when it starts a service, needs a running stack or changes data. Keep one list of them, each `allowed` or `not allowed`; it holds for the implementer, the reviewer and your own summary.
   - With a plan: each hit of `grep -n 'needs:' docs/plans/<ID>-plan.md` is such a check. Ask the user which may run; without a yes a check is `not allowed`.
   - Without a plan the list starts empty; step 6 fills it.
   - The question is asked also when the plan's approval was waived: a waiver of approval says nothing about checks. Only a standing answer in the user's first message ("the dev server may run", "none may run") replaces it, here and in step 6; a first message that gives none leaves the question to ask.
5. **Dispatch the implementer**: the first row under "Dispatching".
6. **Judge the report.** Its `Requirements:` list must name every requirement of the task by the id every role derives from position: `D1` to `D<n>` for the "Done when" items, n from the `done when:` line of step 2's `check`, and `N1` to `N<m>` for the top-level bullets of "Notes", in order. Compare it with the task file.
   - `n/a` is for a note that asks for nothing: a record or a piece of evidence, or a line the skills write about the task's course, which is an `Approach (sw-do, ...)` note (its work is the requirements it orders) or a `Route:`, `Split` or `Changed` line. An answer the user gave, or one assumed for them, asks for something when it bears on a "Done when" item of the task: it is met when the work follows it, shown by that item's check; an answer that bears on none of them asks for nothing. A note that asks for something and comes back `n/a` is `not met`.
   - `met` needs evidence: a command or test and its result. You do not re-run it here; step 8 runs a command for every item.
   - An item marked "(test)" also needs a `red:` line in the report: the run in which its test failed before the code. Keep each such line, from the first report and from each fix round's, for step 8. A line that is missing or says `none` is no reason for a new implementer; the summary marks that item `unverified`.
   - `built, not verified`: the item's only check needs the environment and was not allowed. Ask the user once, in one question, whether each such check not yet answered may run, and add the answers to the list. Then go on either way, with no new implementer: the reviewer and your summary run what is allowed, and a check that cannot run leaves its item `unverified` in the summary and the task `in-progress`.
   - `differs` or `preferred`: the item was built differently from its wording. `differs`: it could not be built as worded. `preferred`: it could, and the implementer chose another way. Either is the user's call: show the wording, what was built and why, and ask. For a `preferred` item the question says that it could have been built as worded. A sensible reason does not accept it.
     - Accepted: rewrite that item in the task file to what was built, and add to the end of "Notes" `- Changed <date>, accepted by the user: D<n> was "<old wording>"; reason: <why>.` (`D<n>`: the item's id; `N<n>` for a note; for a `preferred` item the reason begins `preferred:`). The reviewer and the summary then read one wording.
     - Not accepted: a fix round whose entry is the item in the task's wording; the implementer rebuilds a `preferred` item as worded.
   - `not met`, or missing from the list: the task is not done.

   A fix round's report marks each entry `fixed` or `not fixed`. A `not fixed` entry goes to the user with the implementer's reason. Unless they accept what stands, no review is spent on it: go to step 8.
7. **Review, if the task requires it.** It starts when every requirement is `met`, `n/a`, `built, not verified` or accepted: the review row under "Dispatching".
   - `Verdict: pass`: go on. Pass `important` and `minor` findings to the user in your report; they do not block.
   - `Verdict: changes needed`: a fix round with the blocking findings, then the review row again, with those findings under `Recheck:`; one that comes back `still open` is blocking. After two such rounds that still end in `changes needed`, stop and put the findings to the user.
   - Do not review the change yourself in place of the reviewer, and do not argue a blocking finding away. If you think a finding is wrong, say so to the user and let them decide.
8. **Summarize.** Follow sw-summarize for the task, yourself, in this session: it runs one command per "Done when" item, each one a command that could fail, makes the mutation run for a "(test)" item, ends on the project's full guard run, writes the `## Summary` section into the task file and appends the `summary` log entry. The `red:` lines of step 6 are part of its input: they are in this session's reports, and an item marked "(test)" without one is `unverified` in the summary. This step is not optional and is not delegated to the implementer. Run it whenever the implementer's work is in, also when an item is not met: the summary then records what is open. It does not set the status; step 9 does.
9. **Record the outcome**, then run `node docs/.sw/sw.mjs board`.

   | Outcome | Task file | Log entry, after the `summary` entry |
   | --- | --- | --- |
   | No requirement `not met`, every `differs` and `preferred` item accepted, review passed where required, and `check <ID>` says `can finish: yes` (every item in the summary is `verified`) | `status: done`, `finished:` today | `task \| <ID> done`, then one body line with the summary's count and, where it ran, the review verdict |
   | Requirements met and verified but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
   | The summary holds an `unverified` or `failed` item | stays `in-progress`; add to "Notes" what each open item needs | `task \| <ID> blocked: <n> unverified, <m> failed` |
   | Anything else not met, not reviewed or awaiting the user's call | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |

10. **Keep the area guide, if the area has one.** `node docs/.sw/sw.mjs explain <ID>` prints `area guide:` with a path or `none`.
    - A guide exists: add the reports' `Guide:` lines to it, one line per fact under Layout, Patterns, Verify or Gotchas. Replace a line the new fact corrects, and keep the page under 60 lines.
    - No guide: do nothing. A guide is worth starting once several tasks in an area have needed the same facts; if the user asks for one, create `docs/wiki/guide-<area, lowercase>.md` from `docs/.sw/templates/guide.md` and list it in `index.md`.
11. **File what else was learned.** These are separate offers: act on each only when the user says yes to that one.
    - A report held a decision or constraint the wiki should keep: offer a wiki page (`type: decision` or `concept`), added to `index.md`.
    - The task fixed a problem whose cause is now known, or the review caught a defect worth remembering: offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later.
    - A report named follow-up work, or the review left `important` findings open: offer to create the tasks. A finding that lives only in the log is forgotten.
12. **Report** to the user, in this order. Commit only if the user asks.
    - the outcome;
    - what was planned, and what was built with each deviation from the plan, as the Summary's Plan and Implementation parts say it;
    - each "Done when" item with its verdict and command, taken from the Summary, and each item rewritten after an accepted difference, with its old wording;
    - the review verdict and its findings, and the implementer's open decisions;
    - the files changed, as the Summary lists them;
    - the tasks this unblocked (`node docs/.sw/sw.mjs ready`);
    - what the task cost: run `node docs/.sw/sw.mjs stats` and show its table as printed;
    - one last line: the task is recorded, so the next task is cheapest in a new session.

## Dispatching

What each dispatch gets:

| Dispatch | Goes to | Prompt |
| --- | --- | --- |
| implementer | a fresh implementer | `<ID>`; `Checks:` |
| fix round | the implementer that did the work where the tool can continue it (a further message to that agent), otherwise a fresh one | first line `Fix round for <ID>:`, then each entry word for word; `Checks:` |
| review | a fresh reviewer, every time | `<ID>`; `Files:`, every file the task has changed (the implementer's list plus each fix round's); `Checks:`; from the second review on `Recheck:`, the previous review's blocking findings word for word |

`Checks:` is the list of step 4, one line per check, `- <check>: allowed` or `- <check>: not allowed`; leave the block out while the list is empty. Every prompt names the project root if it is not your working directory.

How to dispatch is the same for both roles: `sw-implementer` with `implementer.md` and the model key `models.implement`, `sw-reviewer` with `reviewer.md` and the model key `models.review`. The key is the role's verb, not the agent's name.

| Tool | How |
| --- | --- |
| Claude Code | the agent by name. If it is not among your agent types, use a general-purpose agent, tell it to read `<skill-dir>/../sw-config/assets/<role file>` first and follow it, and pass the model from `docs/.sw/config.json` if set: `models.implement.claude` for the implementer, `models.review.claude` for the reviewer |
| Codex | spawn the custom agent `sw_implementer` or `sw_reviewer` |
| Copilot CLI | `task` tool with the agent name |
| No subagents available, the agent is not defined, or the project's rules forbid subagents | follow the role file yourself, in this session, and tell the user the configured model and the clean context were not used. A review done this way is weaker: say so |

## Common mistakes

- Marking `done`, or writing `verified`, from the implementer's report. The report is a claim; the check is the summary's commands, run in this session.
- Passing an item marked "(test)" on a green test alone. Without the `red:` line the test has not been seen to fail, and the summary marks the item `unverified`.
- Accepting a `differs` or `preferred` item on the user's behalf. A sensible alternative is still not what the task asked for.
- Leaving the question about checks that need the environment unasked because the plan's approval was waived. Only a standing answer in the first message replaces it.
- Giving a later review only the files the fix touched. A finding in an untouched file is then never rechecked.
- Letting a subagent edit the task file, the log or the task list. One writer for status and for the summary: you.
- Reading the plan or the code "to follow along". The subagents already paid for that; the summary reads only the plan's approach and verification.