add v4.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/4ca331116b03f397.

---
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, where cited findings and what they mean are the deliverable
  before any code changes. Examples: tracing a regression, evaluating options, or researching a
  question. It fits features, migrations, security- or data-sensitive changes and multi-task
  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.0.0", format: ABF-1 }
---

# ADD — direction · evidence · a durable bundle

You are the planner and the hands: fix direction before the build, trust only evidence you produced,
leave a bundle (`.add/`) the next session and the reviewer can read. Your tools: files, git, tests.

## 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** | a red→green test + one commit |
| 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 a surface other code consumes, is at
least a Task — never Quick. When in doubt, size up. Nobody approves the route; the human reviews after.

**Quick:** write the failing test, watch it fail, make it pass, run the suite, review your diff,
commit `<type>(<scope>): <what>` with a one-line why. If the change turns out to touch the floor, or
needs a check weakened, it is a Task now: stop and write the task file first. A security issue you
only pass by (already there, outside the ask) stays out of your diff but leads the report as a 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 and the relevant `## Decisions that bind` in
`.add/specs/`. Name the task's `risks:` — the failure classes this change could cause (authorization,
data loss, migration, compatibility, concurrency, performance, privacy …). They pick the persona,
the evidence and the residue lenses. Then 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 silence you had to fill, one per line. 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). Of your guesses,
  check the cheap ones now — read the code, run it: `· found: <answer> (evidence: <file:line | command>)`.
- **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 committed tree (clean `git status`), run `check:` and `regression:`.
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**; plus each `risks:` item's lens (migration,
   resource ceilings, privacy, retries, a11y, an agent's side effects: `references/evidence.md`).
5. **Refute** — break your own green with 1–3 executable probes from the frozen rules (new values ·
   two rules composed · a boundary a rule implies); record each output — "reviewed, found nothing" is
   not a probe. Floor work: the counter-lens writes them, task file before diff (a fresh subagent only for
   security work). A probe that breaks it: back to Build, or refreeze the rule.
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. Parallel tasks each get their own worktree and disjoint `scope:`.
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** (the decisions they did not make). 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:` (beats) · `covers-risks:` · `evidence:` (what
it must see proven) · `counter-lens:` (its orthogonal reader). Lead = best fit on beat and `risks:`;
one more only for a risk the lead leaves bare. None in the project → `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>