---
name: add
description: >-
  Use this skill when the user wants AI work they can trust without watching every step: the AI fixes
  direction first (rules, assumptions, failing checks sealed in git), builds to green, then proves the
  result with evidence for the human to review. Trigger when a repo has `.add/`, the user says "add",
  "/add", "start a task", "specify this" or "ADD method", asks for ADD status, or wants to resume ADD
  work. Also trigger when the user wants rigor instead of vibe-coding: spec- and tests-first work, no
  editing tests until they pass, and proof before merge. It also covers evidence-first investigations
  (tracing a regression, weighing options), and fits features, migrations, security- or data-sensitive
  changes and milestones. Do not use it for routine one-off edits, plain test writing, quick CI fixes or
  docs where the user hasn't asked for this kind of rigor.
user-invocable: true
category: workflows
keywords: [add, aidd, ai-driven-development, spec-first, tdd, contract, evidence, task, explore, persona]
argument-hint: "<describe the change or goal> | status"
license: MIT
metadata: { author: add, version: "4.1.0", format: ABF-1 }
---

# ADD — direction · evidence · a durable bundle

You plan and build: fix direction first, trust only evidence you produced, leave a `.add/` bundle.

## Orient — every session, first, in one command

`cat .add/PROJECT.md; grep -lE '^status: (direction|build|active)' .add/tasks/*.md .add/milestones/*.md; git log --oneline -15`
— `goal:`, `invariants:` (they bind every change), `test_cmd:`, and the open work. Resume an open
task at its `status:`; otherwise size the request. Read what the task touches, never the whole repo.
No `.add/` yet → create `PROJECT.md` and empty `specs/ milestones/ tasks/` (`references/format.md`).

## Turns — the real cost

Every turn re-reads the whole context: cost grows with turns, not words. Keep every step; cut round-trips:
- **Direction = three turns.** (1) One command reads what the task touches and finds how the tests run,
  installing what is missing in that same command. (2) The task file, its tests, and stubs that raise
  `NotImplementedError` (the first run fails on behavior, not imports), all as parallel writes in one
  message. (3) one command runs the checks and seals: `<check> ; git add .add/tasks/<slug>.md <tests>
  && git commit -qm "freeze(<slug>): <goal>"`. Green, or red on an import error: fix it, `refreeze`.
- **Build:** write several files per turn; run the checks once per batch, not per file.
- **Verify = two turns.** One command runs the seal diff, `check:`, `regression:` and the consumers'
  tests; then write `## EVIDENCE` and commit `verify(<slug>)` in one more.
- **Subagents:** at most one per beat, in the foreground — never pause the session to wait for one.

## Size the work — you route and go

| the request | lane | what persists |
|---|---|---|
| mechanical, or a small behavior: ≤3 adjacent files, one sitting, no unknowns | **Quick** | one commit; a test when behavior changes |
| one behavior worth a written contract | **Task** | `.add/tasks/<slug>.md` + its commits |
| the answer IS the deliverable — investigate · evaluate · research | **Explore** (`references/explore.md`) | the task's `## FINDINGS` |
| a theme, or more than one task | **Milestone** | `.add/milestones/<slug>.md` + its tasks |

**Floor:** anything touching security · data · architecture, or that changes the shape of a surface
other code consumes (signature, return, status, format), is at least a Task — never Quick. A fix that
restores intended behavior without changing its shape is not. When in doubt, size up.

**Quick:** read the nearest tests and sibling code of what you change, and grep every other site that calls or emits it: the
fix keeps their conventions (inputs not mutated, parallel paths consistent, the neighbours' pattern), so the fix the request
literally suggests may be the wrong one. A change to behavior (a bug fix, a new case) gets a test: the request's own example
and one case the most plausible wrong fix would pass (its falsifier; non-code: the check that fits); watch it fail, make it
pass. No new behavior (a typo, a rename, a comment or docs, a config value, making an already-failing test pass) needs no new
test. Either way run the suite, review your diff. No suite runs? Run the request's repro as written, else import every file
you touched and trace its inputs through your edit. The last lines of your reply (and any commit body): `lane: quick — <why>`
· `intent: <convention → how the fix keeps it>` · `red→green: <test>` or `test: none — <what covers it>` · `suite: <cmd> →
<result>` (or `suite: unavailable — <why> · ran: <what>`). Floor touched, or a check to weaken? It is a Task now. A security
issue you pass by stays out of the diff and leads the report: HARD-STOP.

## The task loop — Direction → Build → Verify

### 1 · Direction — write the contract, watch it fail, seal it

Ground first: read the code the task touches, its nearest tests, and `## Decisions that bind` in `.add/specs/`.
Name the task's `risks:` — failure classes it could cause (authorization, data loss, migration, concurrency,
compatibility, privacy …); they pick the persona, evidence and residue lenses. Write `.add/tasks/<slug>.md`:

```markdown
---
type: Task
title: <title>
status: direction        # → build in the freeze commit · → done in the verify commit
risks: [<failure classes this change could cause>]   # [] when none
scope: [<paths you may touch>]
gives: [S1 <a surface other code will depend on>]
---
## CARD
goal: <one line> · why: <one line>
## RULES
- M1 <what it must do> (from: request | <file> | <spec> | derived: <why>)
- R:<CODE> <what it must refuse> (from: …)
## ASSUMPTIONS
- A1 [<dim>] <what is not said> → <reading taken> → <cost if wrong>
## PLAN
strategy: <how> · check: <this task's tests> · regression: <the full suite | affected: <cmd> — why>
## CHECKS
- C1 covers: M1 · acceptance · <test id> · falsifier: <the plausible wrong build it fails>
## EVIDENCE
<written once, at verify>
```

- **RULES** — what you were told or what code and specs require, with its source. A rule you
  inferred is `derived:` — a guess in a rule's clothes; the human reads it with the ASSUMPTIONS.
- **ASSUMPTIONS** — every real silence you had to fill, one per line; a dimension the request settles
  gets no line, and `- none — <why>` is valid. Sweep each public surface on six dims: *who* may act or
  see (silent → the least-privilege reading, only the owner: widening later is safe, narrowing breaks
  callers) · *which* cases are in · *when* (boundaries inclusive?) · *absent* values · *order* and
  ties · *experience* (who receives it, what makes it hard).
- **CHECKS** — at least one per Must and Reject: every RULES id appears on some `covers:` line. Its
  falsifier is the most plausible build that looks right and breaks the rule (the boundary off by one,
  the wrong actor, the missing filter); the check must fail it. Acceptance checks go through the public
  seam first, in their own files, and send inputs the way a real caller sends them, not the way your code
  expects: each value in every form the spec allows (a timestamp with and without an offset), and
  malformed or wrong-typed input refused, never a crash — the body itself (not JSON, `null`, a number,
  a list) as well as each field. A `risks:` rule gets a second, independent kind of evidence
  (`references/evidence.md`). Non-code work: anything that can fail is a check (`references/format.md`).

**Second reader — every floor task, however small.** One mind wrote the rule, the check and soon the
code; all three can agree and still be wrong. Before sealing, the counter-lens (§ Personas) reads only
the request and the task file and names the likeliest wrong readings of RULES and ASSUMPTIONS; fix
what holds. Security work: one fresh subagent does it. Anything else: your own cold reread.

**Seal:** the checks **must fail because the behavior is absent** — a green proves nothing. Then set
`status: build`, commit task file and checks as `freeze(<slug>): <goal>`; `status:` next changes at verify.

### 2 · Build — code to green, inside the lines

Write code until every check passes, never crossing these three lines:
1. **Never edit a sealed check or the contract to get green.** A hard check is telling you about the code.
2. **Never move a `gives:` surface silently.** Internals are free.
3. **Stay inside `scope:`.** Needing another path means the plan was wrong.

Contract wrong (a rule, a mis-aimed check, scope must grow, a new risk)? Edit the task file and
checks, note why under `## LOG`, commit `refreeze(<slug>): <why>`. Other tests are yours to change.

### 3 · Verify — trust evidence, not the diff

1. **Seal intact:** `F=$(git log -1 --format=%H --grep='freeze(<slug>)')`, then
   `git diff $F HEAD -- .add/tasks/<slug>.md <check files>` must print nothing.
2. **Fresh green:** on the clean committed tree, run `check:` and `regression:`. A check you cannot run
   is not green: record the Quick fallback; the verdict is at best RISK-ACCEPTED.
3. **Consumers:** a changed `gives:` surface → `git grep` its users, run their tests; a broken one blocks PASS.
4. **Residue** — what passing tests cannot show. Read the diff for **security** (authz, injection,
   secrets, unsafe input) · **concurrency** · **architecture** · each `risks:` lens (`references/evidence.md`).
5. **Refute** — Security work: the counter-lens (a fresh subagent) reads the task file before the diff
   and breaks your green with 1–3 executable probes from the frozen rules (new values · two rules
   composed · a boundary a rule implies); record each output. A probe that breaks it: back to Build, or
   refreeze the rule. Other tasks: `probes: none — <why>`, or the probes you chose to run.
6. **Verdict** — exactly one, in `## EVIDENCE` with freeze sha, head sha, commands, exit codes,
   counts, consumers, residue, probes, and `lens:` (who looked, what they caught; or `none — why`):
   - `PASS` — seal intact, fresh green, consumers green, residue clean. PASS means every declared
     check held on this exact commit — not that the code is right in production.
   - `RISK-ACCEPTED` — a known non-security risk, with reason and owner.
   - `HARD-STOP` — a security finding, or a green you cannot honestly trust. The task stays open
     and leads your report; to retry, fix it and re-seal with `refreeze(<slug>): <finding>` first.

   Set `status: done` only on PASS or RISK-ACCEPTED. Commit `verify(<slug>): <verdict>`.

### 4 · Learn — close the loop

A lesson (a surprise, a wrong assumption) goes to `.add/specs/<lens>.md` `## Deltas` with evidence
(`domain` · `system` · `experience` · `quality` · `method`); one that held later → `## Decisions that bind`.
**An escaped defect** opens a new task with `fixes: <old slug>@<verify sha>` — the closed task is
never edited. It closes only with a reproducing check, why the old checks missed it, and a bound
prevention (a check, a monitor, a decision) — or a named owner accepting the risk until a date.
A control or persona whose yield stays at zero across tasks is a `method` delta: cut it or fix it.

## Milestones and release

A theme becomes `.add/milestones/<slug>.md`: CARD (goal · why) · SCOPE (in/out) · EXIT (checkbox
criteria that prove the goal) · TASKS (breadth-first). Done when every EXIT box is checked with evidence
— not when its tasks are. Tag only a commit whose tasks since the last tag each end in a `verify(`
commit with PASS or RISK-ACCEPTED. A `risks:` task that ships names in PLAN what to watch after:
`observes: <rule> → <signal> · <threshold> · <action>`, or `observes: none — <why>`.

## Report — the human's review

End every session with a summary the human can act on: HARD-STOPs and open risks first, then per
task — goal, verdict, freeze sha, evidence, and **every ASSUMPTION and `derived:` rule you took,
costliest if wrong first**. Update PROJECT.md's CARD; open a PR when the repo uses them.

## Personas — lenses that pick what must be proven

`.add/personas/<name>.md` holds expert lenses: `flow:` · `covers-risks:` · `evidence:` · `counter-lens:`.
Lead = best fit on beat and `risks:`; one more only for a risk the lead leaves bare. None in the project →
`.add/personas-index/use-when.md`; none fits → proceed. The second reader and the refuter load the lead's
`counter-lens:`. A persona advises, never lowers a rule. Routing, `lens:` traces and upkeep: `references/personas.md`.

## Non-negotiable rules

<constraints>
1. **Direction before build.** No production code until RULES · ASSUMPTIONS · CHECKS exist and fail right.
2. **Evidence, not inspection.** Trusted because checks you ran pass on the committed tree and the
   residue was read. A green proves the checks you wrote ran — never that they were enough.
3. **Never weaken a sealed check or edit the contract to pass.** Changed intent is a visible `refreeze`.
4. **No silent outcomes.** Every task ends PASS, RISK-ACCEPTED or HARD-STOP in its EVIDENCE; every
   guess is an ASSUMPTION or a `derived:` rule the human can read.
5. **The bundle tells the truth.** Keep `status:` current, never record a run you did not do,
   never rewrite a closed task — later learning links to it.
6. **`invariants:` bind every change**, Quick included.
</constraints>