Living specs and changes
agent-kit's SDD is spec-anchored: specs are not throw-away planning documents, they stay true for as long as the code lives.
Living specs
work/specs/<capability>/spec.md says how one area of the system behaves now. A capability is an area users recognise — auth, invoices, user-roles — not a page or a table.
---
capability: auth
retired: [auth.R1]
---
# Auth
## Purpose
Who can sign in and how.
## Requirements
### auth.R2 — Session restore
While a session is stored, the app shall restore it on reload.
#### auth.R2.S1 — Reload keeps the user signed in @simple
- Given a signed-in user
- When the page reloads
- Then the user is still signed in
The session context lists the capabilities (one line); the agent reads a capability's spec before changing its behaviour. The notation is described in Notation.
Changes
Complex work is a change in work/changes/NNN-slug/, created with agent-kit work new change <slug>:
| File | What |
|---|---|
proposal.md | Why, what changes (in / out), capabilities touched, open questions. The first artifact you approve. |
specs/<capability>.md | Delta spec: ## ADDED, ## MODIFIED (the whole block as it must read after) and ## REMOVED Requirements (with a reason). |
plan.md | Files, schema / RPC changes, decisions, risks. |
tasks.md | Ordered tasks tagged with the scenario ids they cover, evidence under each, and a verification table. |
Merge
When the change is verified, agent-kit specs merge NNN:
- applies every delta of the change all or nothing — it refuses and names the conflict when a MODIFIED or REMOVED requirement is missing, or an ADDED id is taken or retired;
- retires removed requirement ids and scenarios left out of a MODIFIED block (they are never reused, so old tests, QA runs and fixtures can't point at the wrong behaviour);
- marks the proposal
merged: <date>and refreshes the QA checklist.
The change folder stays as the record of why the behaviour changed.
Ids
agent-kit specs next <capability> hands out the next requirement id; agent-kit specs next <capability>.R<n> the next scenario id. Both count living, retired and pending-delta ids, so two open changes don't collide.
Tools
| Command | Does |
|---|---|
agent-kit specs lint [cap|NNN] | Checks the notation and the ids (exit 1 on errors). |
agent-kit specs list | Capabilities with requirement and scenario counts. |
agent-kit specs trace [NNN|cap] | Scenario → tests or ✅ checks. |
agent-kit work status / board | Active work and its next task. |