State is location
Where a spec lives is its state — there is no frontmatter statusfield to keep in step with the folder. Four folders under docs/ carry the whole lifecycle, and a spec is in exactly one of them. Four moves carry it from an idea to a shipped, archived contract; reshape is a normal move, not a failure. The sequence isn't prescribed — shape, approve, build, and graduate can be one commit or several branches; Specline reads folders, not order. The only place astatus field still appears is archive/ (shipped | killed) — location can't tell those two apart there. A status: line written against an earlier canon (including ratified, building, blocked) is recognised silently.
The locations
Each location names what's true, who moves a spec into it, and where it can go next:
| Location | What it means | Who moves it | Transitions |
|---|---|---|---|
docs/drafts/<slug>/ | Being shaped — an idea, not a commitment. May be incomplete; nothing may depend on it yet, so it may simply be deleted. | Agent / PO, while shaping | → docs/specs/ (the decider's go), or deleted / archived as killed ("abandoned"). |
docs/specs/<slug>/ | Approved for build — the move itself, recorded in git, is the record. No status field tracks progress here; the folder's presence is the state, whether the build hasn't started yet or is well underway. | The decider, by moving the folder | → docs/knowledge/ + docs/archive/ (ships), or → docs/archive/ (killed). |
docs/knowledge/<slug>/ + docs/archive/<slug>/ | Shipped. archive/ holds the contract, verbatim, with an acceptance-results link, status: shipped, read-only forever — what was promised. knowledge/ is the living, present-tense description — what it became. | Graduation, wired to the implementation PR | Terminal. |
docs/archive/<slug>/ (alone) | Dropped. Archived with a one-line tombstone stating why ("abandoned" for a draft dropped before ship) and status: killed. The slug stays burned. | A deliberate kill, or an abandoned draft | Terminal. |
The four moves
The lifecycle loop is the feature's journey across the gates — distinct from the experimental, opt-in build loop that can run inside the build step (unattended builds only; see acceptance altitudes):
Shape agent + PO
An agent drafts the contract in docs/drafts/; the PO edits. Only parse-level integrity runs here — incomplete is what a draft is for.
Approve decider · the first gate
A named human reads the whole contract in one sitting (One sitting) and gives it their go — moving the folder from docs/drafts/ to docs/specs/, in a commit made or approved by the decider, on whichever branch the work is on. Git records who and when. The spec does not have to merge first.
Build builder · attended by default
The builder works from docs/specs/<slug>/ toward the Goal, against the acceptance checks. Attended (the default) the decider is reachable: the builder disagrees out loud and the spec is amended by agreement. Unattended (build: unattended, experimental) it runs the autonomous loop and escalates back to a human at the first of two triggers — loop_budget exhausted or stale_after reached — and a contradiction parks it blocked in status.md.
Graduate agent · wired to the impl PR
An agent-executed editing pass, triggered structurally by the implementation PR: archives the final spec.md as shipped, writes the present-tense knowledge/ doc, and deletes the spec folder. The human acceptance gate reviews the graduated doc — "is this what I decided?"
One branch, or two
The normal shape is one branch: the spec folder is created in drafts/, the decider's go moves it to specs/, the build lands against it, graduation runs, and one pull request carries all of it. Its approving merge is the record of contract, build, and graduation.
A spec landed ahead of the build is the two-branch shape: the move tospecs/ lands first, and the implementation PR follows, referencing the slug. Reach for it when shaping runs well ahead of building, when several branches are shaping in parallel and a slug needs claiming early, or when an unattended runner requires a landed baseline. It is a legal shape, not the rule — and the slug freezes when the spec lands on the merge target, not at the decider's go.
Reshape is a normal move. The spec on the branch being built is the contract, and it changes as the build teaches. Attended: the builder says so in product terms, the decider agrees, the builder edits spec.md in the branch — acceptance checks included, proposed before they're changed — and the diff is the record. No folder move, no separate PR. Unattended (experimental): there's no conversation to have, so it's a handback — set status.md's State to blocked, land a decider-approved spec-amendment commit touching only the spec folder (resetting stale_after in the same commit), then resume.
Up: handbook — building. The law: the canon, "Lifecycle".