Specs, documents and revisions
A spec is a numbered unit of work with up to five documents and a status.
The server numbers specs (001, 002, …) when you create them with create_spec, which takes a slug of one to four lowercase words joined by hyphens. Each spec also gets a branch name such as 004-diesel-orm. The active spec is the non-archived spec with the highest number, and get_active_spec returns it.
Documents
| Document | What it holds |
|---|---|
spec | What and why, with the functional requirements (FR-1, FR-2, …). |
plan | How it will be built. |
tasks | Small tasks with a phase, a parallel flag, FR references and a Done when check. |
research | Findings that answer open questions. |
validation | Each requirement and the test that covers it. |
Status
A spec is draft, clarified, approved or archived. The allowed moves are draft to clarified, clarified to approved, clarified back to draft and approved back to draft. Owners can archive a spec, and an archived spec cannot change status again.
Only a clarified spec can be approved, and not while it has open markers (see Tasks and markers). A project can also require several approvals and forbid approving a spec to people who contributed to it. A refused move says which targets are allowed.
Revisions and conflicts
put_document writes the full body of a document as a new revision; nothing is updated in place. When the document already exists, pass expected_revision, the revision your edit is based on. If someone else wrote first, the write is refused with conflict and the current revision, so the agent reads it, merges and writes again. Nothing is overwritten and both changes stay in the history.
list_revisions lists the revisions of a document or of the constitution, newest first, and get_revision reads one by its id.