Implement the solution for a spec with Test-Driven Development (RED → GREEN → VERIFY). Reads the existing analysis and plan, writes tests first, implements, and runs the quality check. Use when: implementing a solution with TDD, having a completed analysis and implementation plan, coding based on 3-solution.md. Do NOT use for: creation (use aide-create), analysis (use aide-analyze).
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Aide Implement?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/ragnarwestad-aide-implement)
---
name: aide-implement
description: >-
Implement the solution for a spec with Test-Driven
Development (RED → GREEN → VERIFY). Reads the existing analysis and plan,
writes tests first, implements, and runs the quality check.
Use when: implementing a solution with TDD, having a completed analysis and
implementation plan, coding based on 3-solution.md.
Do NOT use for: creation (use aide-create),
analysis (use aide-analyze).
effort: high
---
Implement the solution for a spec with TDD.
**Input:** the argument the run's prompt gives
## The spec
The argument's first word is the spec: its number, its folder name, or an issue key its title began with —
`55` or `55-dark-mode`.
---
## Workflow
The steps below are this skill's own, inside the queue's `implement`
step. Mark each one in the log, so a reader can follow the run: when it
starts, write one line `--- Step N of 4: <title> — started`, and
when it ends, one line `--- Step N of 4: <title> — done`. A step
that ends the run early says `— stopped: <why>` in place of `— done`, and one that does not apply to this run `— skipped: <why>`.
Step 3 also marks each task it takes from the plan, as it finishes it:
`--- Step 3 of 4, task K of M: <task> — done`, where M counts the
task rows of `4-status.md`'s GREEN tables.
### Before Step 1: a merge left open for you
When `aide-run-spec` could not bring the spec's branch up to date with
the default branch, it starts this step with the merge still **open** in
the worktrees the prompt names: `MERGE_HEAD` is set and the conflicted
files carry markers. Finish that merge before any of your own work; it
is not leftover state, and aborting it or resetting over it ends the run
`merge-unfinished`, with your work sitting on the old default branch.
1. `git diff --name-only --diff-filter=U` lists the files; `ours` is the
spec's branch, `theirs` the default branch.
2. Resolve each file so that **both** sides' intent survives — never
`--ours`/`--theirs` across the board. Two sides adding to one import
list, one table or one document's sections is the common case. Two
sides that changed the same logic in incompatible ways are not
guessed at: `git merge --abort`, and stop with what the two sides
wanted.
3. Remove every marker, `git add` the files, check with
`git diff --check`, and finish with `git commit --no-edit`.
4. Then begin Step 1. The tests you run in Step 4 cover what the merge
brought in as well as your own change.
Never push, and never touch the default branch: the dashboard lands the
branch afterwards, as it lands every step's work.
### Step 1 of 4: Preparation
First write `--- Step 1 of 4: Preparation — started`, and when this step ends, `--- Step 1 of 4: Preparation — done`.
1. Read `specs/XX-slug/2-analysis.md` (affected files)
2. Read `specs/XX-slug/3-solution.md` (implementation plan). Build its
recommended solution. On a spec that asked to choose the approach, a
choice not saved on the Specs list never stops this step: the
recommended approach is built. When `2-analysis.md`'s Tracking info
reads `- **Analysis:** short`, `3-solution.md` holds no plan and no plan
review by design: build the change `1-description.md` asks for, in the
files `### Files to change` names, with the tests at the places `###
Where the tests sit` names. A short analysis is never a reason to stop
for want of a plan; it is one only when the spec turned out not to be
small. Before any test or code is written, check the change against the
limits of a short analysis (the prompt states them: the files to change
and the grade). When it is past one, write one sentence
saying what made the spec larger to the file the prompt names, changes
nothing else and ends with `--- Step 1 of 4: Preparation — stopped: sent
back to a full analysis`; the runner then sends the spec back to a full
analysis. Never write that file on a full analysis
3. If the spec is MEDIUM/HIGH and `3-solution.md` has no "Plan review"
section: proceed, and say in the summary that the plan was not reviewed
4. Read the project's coding standard, where it has one (its
`CLAUDE.md`, `AGENTS.md` or `CONTRIBUTING.md`)
5. Read `specs/XX-slug/4-status.md`'s task tables. An earlier run
stopped by its time limit lands what it wrote, so some of the steps
below may already be done. A step whose task rows are
all ✅ is done: skip it. A step whose table is marked 🔄, with some
rows ✅ and some ⬜: keep the ✅ ones and resume at the first ⬜.
Start at Step 2 only when every row is still ⬜ Not started.
**Where a symbol is used or defined, ask the language server first.**
When an `LSP` tool is listed, it is usually deferred: load it once with
`ToolSearch` (`select:LSP`) before the first search, then make the FIRST
search for where a function, type or constant is used or defined a
`findReferences` or `goToDefinition` call — never `grep`. It answers with
the real references, not every line that happens to contain the name.
Fall back to `grep` only when the language server gives no answer (it
errors, or the file's language has none), and for text that is not a
symbol — a message, a config key, a CSS class.
### Step 2 of 4: RED — Write failing tests
First write `--- Step 2 of 4: RED — Write failing tests — started`, and when this step ends, `--- Step 2 of 4: RED — Write failing tests — done`.
Skip this step entirely if item 5 of Step 1 found it already done;
resume it at the first unticked task if it found it in progress.
1. Read "Task 0" (the tests the plan asks for), the acceptance
criteria and the `### Where the tests sit` subsection from
3-solution.md. A short analysis has no Task 0: write one failing test
per `AC-n` of `1-description.md` at the places `### Where the tests
sit` names
2. Run `aide-emit-run --phase red --spec <ID>` (see [Reporting RED, GREEN and VERIFY](#reporting-red-green-and-verify))
3. Write the tests at the places `### Where the tests sit` names in
`3-solution.md` — at least one failing test per acceptance criterion
it gives a place. A criterion an existing test already proves gets no
second test: add the AC-id to that test's name instead (step 4). What
a test is for, and what it is not, is the testing rule's "What to test"
4. **Put the AC-id in the test's name.** First ask for the project's
prefix for it:
```bash
aide-ac-prefix --project-dir . --spec <spec-folder>
```
`<spec-folder>` is the spec's folder name, so the number is the one
the folder writes. A test written for a criterion that opens with an
AC-id carries that id in its own name, as the name's last words,
after the `prefix` the command printed and a space:
`test("the total keeps counting (F02 AC-2)", ...)` for the prefix
`F02`, and `test("the total keeps counting (AC-2)", ...)` when the
prefix is empty, or when the command is not found or refuses. Two ids
in one name each carry it: `(F02 AC-2, F02 AC-3)`. Only the ids this
step writes carry it: a name an earlier spec gave a test is left as
it is. The runner reads these names after the step to show, on the
row the user ticks, which test covers which requirement — a test
without the id is a requirement shown as untested
5. **Write a browser test for a *(browser)* criterion,** where the
project keeps its browser tests; a project with none names that
criterion in `3-solution.md`'s Manual testing note instead
6. **Check the list before running anything:** every AC-id the places
list gives a place appears in at least one test name from steps 3-5,
with the prefix or without it.
An id with none gets its test now, at its place. An id the plan
leaves untested, with its reason under Manual testing, gets none
7. Run the tests — verify that they FAIL
8. Tick this step's task rows in `4-status.md` — ✅ once a row's test is
written and confirmed to fail, not merely planned. Write the result
with `aide-write-spec --file 4-status.md` (never Write/Edit)
9. Report the RED result briefly and continue to GREEN
A test steps 3-6 need in a file the places list does not name is written
all the same, and the Notes cell of the Phase 1 RED row of the task that
wrote it gets one sentence per such test, in the form
`Outside the plan's places: <test file> — <why>`. A plan without the
section leaves the places to this step, and every AC-id gets a test.
### Step 3 of 4: GREEN — Implement until tests pass
First write `--- Step 3 of 4: GREEN — Implement until tests pass — started`, and when this step ends, `--- Step 3 of 4: GREEN — Implement until tests pass — done`.
1. Run `aide-emit-run --phase green --spec <ID>`
2. Implement each task from 3-solution.md's plan (on a short analysis the
change itself is the one task) — before writing to a file,
check its current line count against any limit the project's coding
standard states (e.g. dashboard/AGENTS.md's "Code health" section),
and split by responsibility instead of appending past it
3. Run the tests after each task, and log the task as done
4. Verify that the tests PASS, by changing the code. Never skip, disable
or weaken an existing test to get green or fast; one that is itself
wrong is changed only with the reason in the step's summary
5. Tick this step's task rows in `4-status.md` as each one's tests turn
green. Write the result with `aide-write-spec --file 4-status.md`
(never Write/Edit)
6. Report the GREEN result briefly and continue to VERIFY
### Step 4 of 4: VERIFY — Full suite, types, lint, build
First write `--- Step 4 of 4: VERIFY — Full suite, types, lint, build — started`, and when this step ends, `--- Step 4 of 4: VERIFY — Full suite, types, lint, build — done`.
**The whole suite is the runner's, not yours.** `aide-run-spec` runs the
project's test command once on what you deliver, and that run is the one
that decides: a green one ticks the "Run the full test suite" row, and a
red one comes back to this session as a follow-up turn with the failing
lines. Never run the whole suite yourself — not through
`aide-record-test-run`, not directly. Under load it takes ten minutes and
decides nothing.
1. Run `aide-emit-run --phase verify --spec <ID>`
2. Run the tests that cover the change: every test file this step wrote
or changed, and the existing test files for the source files it
changed — each file once. Red is fixed back through Step 3. A test that
fails and has nothing to do with the change is the machine's load, not
a fault: name it in the step's summary and go on.
A browser test this step wrote for a *(browser)* criterion is run
too, each file on its own and once — never the project's whole
browser suite. Red is fixed back through Step 3 like any red test. A
file that could not start at all (no browser on the machine) is named
in the step's summary, never passed over in silence.
3. **Look at the pages the change affects.** Only when the spec's branch,
compared with the default branch, changes a file under
`dashboard/src/render/` or a stylesheet, and the project has
`dashboard/scripts/look-at-pages.ts` (Aide's own repository);
otherwise take no screenshots.
- Write a scene that brings the changed part onto each page it
affects (the spec, queue and settings data; the live spec is
`81-queue-and-runner`, and the fields are listed at the top of the
script). Where the changed part shows names or lists, make the scene
hard on it as well: a very long title or name, and an empty list. Then
run
`bun dashboard/scripts/look-at-pages.ts --scene <scene.json> --out <folder> <path>...`
once, with every affected path. The folder is the one the prompt
names. The
script serves this checkout's own code on throwaway data and takes
each path at 1440 px and at 390 px wide.
- Read every picture with your image viewer and look at it against the
description and `dashboard/docs/design-system.md`. Fix what is wrong
back through Step 3, then take them again; the folder keeps the last
round.
- If the script cannot serve or take a page, it says why in
`not-taken.txt` in the folder. Go on with the step.
4. TypeScript check
5. ESLint
6. Build
7. Tick this step's task rows in `4-status.md` as each check above
passes. Leave "Run the full test suite" as it is: the runner ticks it.
Write the result with `aide-write-spec --file 4-status.md` (never
Write/Edit)
8. Before reporting anything: confirm every row in this step's own table
reads ✅, the full-suite row apart. This is a separate, required
write, the last one this step makes.
9. Show a summary
**Find a table in `4-status.md` by its HEADING TEXT, never by its
number.** This skill's RED, GREEN and VERIFY are its Steps 2-4;
`4-status.md` has four tables for them, because its GREEN work is split
into implementing and verifying. So RED is `## Phase 1: RED`
there, this skill's GREEN covers BOTH `## Phase 2: GREEN - Implement`
and `## Phase 3: GREEN - Verify tests`, and this skill's VERIFY phase is
`## Phase 4: VERIFY` — or, on a spec whose `4-status.md` was created
before this table was renamed, `## Phase 4: REFACTOR`, the same table
under its old heading. A tick placed by matching a number in this
skill to a number there lands in the wrong table.
In a Tasks table's Status cell, write the SYMBOL its Notation section
gives — `✅`, `⬜`, `🔄` — never the word beside it, and never both
together (`✅ Completed` is wrong the same way `Completed` alone is
wrong).
None of Steps 2-4 above ever ticks a row under a `## Acceptance
criteria` heading, if `4-status.md` has one — never tick that section,
and never touch a TICKED row's Notes cell either. Implement never writes
`Not verified` to any Status cell: the mark counts as done, so writing
it would let a run past the archive gate that only the user may open. It
never writes `Failed` either: that mark says a check made after the
deploy did not hold, and only the person who made the check can say so. Those rows name the
spec's own AC-tagged acceptance criteria, and ticking one is a judgment
only the user the spec is for can make.
**One narrow carve-out.** On a held-back spec, or a reopened spec
(`aide-reopen-spec`, files kept), taking another round on its open checks
(`../aide-analyze/references/requirements-tracing.md`'s
"A held-back spec's second round"), the Notes cell of a row that is
still OPEN (`⬜`) may be written. The Status cell of that same row, and
every cell of a row that is already ticked, stays exactly as found
regardless. On any spec that is not in a held-back or reopened round, leave every
row exactly as you found it, Notes cell included — this carve-out does
not widen the rule above it.
**The cell is REWRITTEN, never added to, and it is one or two
sentences: what is missing for a user to tick this row, and nothing
else.** Whatever the earlier round left there is replaced — what each
round found, ran and measured belongs in `2-analysis.md` and
`3-solution.md`, which carry a `## Round N` section for exactly that.
Nothing is missing is a cell left empty, not a sentence saying so.
One sentence is kept as it is: a cell that starts `Failed:` (what did
not hold, written when a check after the deploy failed) keeps that
sentence first until the row is ticked, because the next round reads it
as the reason the round is needed.
Leave `Workflow steps completed:` and this phase's `Repo`/`Model`/
`Result`/`Time spent`/`Cost` lines in `3-solution.md` as you found them:
`aide-run-spec` writes them. The percentage above it is still yours: it
says how far RED, GREEN and VERIFY got, which is the field for partial
work.
This session does not run `git commit` or `git push`: the runner commits
the specs repository and the project's code, and pushes them.
### Reporting RED, GREEN and VERIFY
One Bash call at the start of Steps 2, 3 and 4, with the spec's ID:
```bash
aide-emit-run --phase red --spec 81
```
It is a fire-and-forget report, not a gate: it prints nothing, never
asks anything, always exits 0, and does nothing at all unless
`AIDE_RUN_URL` is set. A run that reports them can be followed from
the dashboard while it works; the steps still run through without
stopping.
See `references/tdd-phases.md` for the detailed workflow with commands
and expected output per phase.
Rules:
- Run all four steps through without stopping to ask for
confirmation — report each step's result as you pass it. Stop only
when genuinely blocked (a decision only the user can make, or a
step that cannot be completed)
---
## Quality check
Use the project's own test/lint/build commands — detect them, never assume
a toolchain (see the "Project commands" section of the tools-and-scripts
rules). Example for a pnpm/TypeScript project:
```bash
npx tsc --noEmit # TypeScript check
pnpm run eslint # ESLint
pnpm run build # Build
```
**The project's test command is the runner's to run.** It is the
manifest's `AIDE_TEST_CMD` (the tools-and-scripts skill, "Project
commands"), and `aide-run-spec` runs it on the step's result. A change to
Markdown files alone runs the project's documentation check instead.