/add

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`:

---
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> · fa