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

DocumentWhat it holds
specWhat and why, with the functional requirements (FR-1, FR-2, …).
planHow it will be built.
tasksSmall tasks with a phase, a parallel flag, FR references and a Done when check.
researchFindings that answer open questions.
validationEach 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.

HTTP 409
{ "code": "conflict", "message": "revision conflict: current revision is 42", "current_revision": 42 }

list_revisions lists the revisions of a document or of the constitution, newest first, and get_revision reads one by its id.