Resources

How we write specifications

One template, one lifecycle, one way to version.

Approved by the Board for implementation · 20 November 2026

Status

Every specification here is a draft (version below 1.0). Build to them and comment on them, knowing they may change. No licence is granted yet.

In short

Every CRIS specification follows one template, moves through the same states, and is versioned the same way, so that a reader who knows one can read them all. These are proposals for Systems Engineering to adopt (Q1, Q2).

The template

Header, from data: state, version, date, owner, licence, side of the line, relies on, comment link1 Purpose2 What it is, and is not3 Terms4 The format, rule or method5 Rules6 Illustrative example7 Conformance8 Security, privacy, protected line9 Open questions and deferred values10 ChangelogThe same names and numbering, in the same order, on every specification. Old anchors are kept as aliases.
One shape for every specification: a header from data and ten numbered sections.
#SectionWhat goes in itRequired
—HeaderFrom data: state, version, date, owner, licence, side of the line, relies on, comment linkAlways
1PurposeWhat it is for and which design principle it serves, in one paragraphAlways
2What it is, and is notIts scope; what it never covers; any money or personal-data lineAlways
3TermsOnly words a reader would not knowWhen needed
4The format, rule or methodThe heart: a field table, a statement, or numbered stepsAlways
5RulesNumbered, each one testableAlways
6Illustrative exampleWith the standard “Illustrative only” labelFrom 0.2
7ConformanceLevels and test vectors, from dataBefore 1.0
8Security, privacy, protected lineWhat it never carries; signatures; who may see whatAlways (may be one line)
9Open questions and deferred valuesEach with an owner, from dataWhile 0.x
10ChangelogPrinted from the changelog dataAlways

The states

PlannednoneDraft0.xCandidate1.0.0-rc.nStable1.x and aboveRetiredlast version keptowner and template;a changelog entrylicence published;vectors; 30-day reviewonly fixes; owner andFounder signa successor named,or the system withdrawna substantive problem in review reopens as the next 0.xToday: all six are drafts; two are planned. Nothing leaves draft without a published licence.
Lifecycle: five states, and what each move needs.
StateVersionLicenceWhat it means for a builder
Plannednone—Named so you know it is coming; nothing to build to yet
Draft0.xmay be to be confirmedBuild to it and comment; it may change without notice
Candidate1.0.0-rc.nrequiredFrozen for public review; only fixes
Stable1.x and aboverequiredChanges follow the versioning rules
Retiredlast version keptas publishedKept for reference; its successor is named

Moving from draft to candidate needs a published licence, open questions closed or moved to a later version, test vectors, and a public review period of [30] days (proposed). Candidate to stable needs nothing but fixes during review, and the owner’s and the Founder’s signatures.

Versions

1 . 2 . 3majorminorpatchmay breakaddsfixesOne changelog entryin dataThe specification pageThe hub changelog and feedVersion history
Versioning: three numbers, and one changelog entry printed everywhere.
ChangeFrom 1.0Below 1.0
Major (1.x → 2.0)Something that conformed may no longer conform—
Minor (x.1 → x.2)Something added; anything that conformed still doesMay break: that is what draft means
Patch (x.y.1 → x.y.2)Wording, examples or fixes; conformance unchangedSame

The developer hub changelog is the one record of every version. Each specification prints its own changelog from it; no page types a changelog line.

Our rules

  1. Drafts are 0.x. (enforced by the build today)
  2. Stable is 1.0 or above. (enforced by the build today)
  3. No licence, no exit from draft. (enforced by the build today)
  4. Published side only, and a changelog entry for every version. (enforced by the build today)
  5. One shape: every specification follows the ten-section template.
  6. Examples are labelled: every example says example, and every example block says “Illustrative only. Not from a running system.”
  7. Deferred values are tracked: each is listed with its owner.
  8. Dependencies are declared, from data.
  9. A named owner who answers: an owner in post, or a named interim owner while the role is recruited.
  10. One changelog, printed from data, never typed.
  11. Status from data: a specification never says the system it describes is running.
  12. Board-only changes stay board-only: a change that would weaken the Continuity Invariant or either gate goes to the board under the proposed AI Constitution.

Back to the specifications

Owner: Systems EngineeringNext review: 2027-05-11