CrewRig

Specification format

This document defines the normative file format for the SPECS stage of the lifecycle introduced in ADR-0010. It is the contract that every spec under /specs/ SHALL satisfy and that downstream tooling (the spec-author skill in issue #168, the routing engine in issue #172, the future spec linter) will rely on.

The format is intentionally minimal: YAML frontmatter for machine-read fields, Markdown body for human-read content, a fixed set of mandatory sections so a reviewer always knows where to look.

Frontmatter schema

Every spec file SHALL open with a YAML frontmatter block delimited by --- lines. Fields are listed below with their type, cardinality, and constraints. Unknown fields are tolerated by the format but SHOULD NOT be introduced without first amending this document.

Field Type Required Constraint
id string yes <NNNN> zero-padded to four digits, monotonic, allocated by the ticket creator. Must match the filename prefix.
slug string yes kebab-case, ASCII, no leading/trailing hyphen. Must match the filename slug.
status enum yes One of draft, approved, implemented, archived, superseded.
complexity enum yes One of trivial, small, standard, large. Must match an ADR-0010 complexity tier.
interaction-mode enum from approved onward One of FULL, INTERMEDIATE, MINIMAL, AUTO. Must match an ADR-0010 interaction mode. MAY be omitted in draft, in which case the value defaults to INTERMEDIATE; SHALL be present explicitly once the spec reaches approved.
related-issue integer yes The GitHub issue number this spec qualifies (the logbook anchor, per AGENTS.md → Logbook Issues → Rule A).
version semver yes Starts at 1.0.0 on the initial spec. Bumps follow the delta-spec convention below.
max-iterations integer no Overrides the ADR-0010 default of 5. Bounded [1, 20] inclusive. Omit to inherit the default.
superseded-by string conditional Required when status: superseded, prohibited otherwise. Value is the id of the spec that supersedes this one.
unsecured-id boolean no Absent by default, and carries meaning only when present and true. Marks a spec whose id was allocated locally but never secured on the reference repository — the fallback of specs/0112-spec-id-reservation.md requirement 9, reached when the author is offline or contributing from a fork. scripts/reserve-spec-id.sh emits this exact line on stdout on its exit-3 path, so the author pastes rather than composes it. scripts/check-spec-id-reserved.sh reports the condition at pull-request time: blocking for a pull request from the reference repository, non-blocking for one from a fork. The mark SHALL be removed in the same act that secures the id (requirement 10) — a merged spec never carries it. Never back-filled onto an existing spec.

Worked frontmatter

---
id: "0042"
slug: build-dryrun-flag
status: approved
complexity: standard
interaction-mode: INTERMEDIATE
related-issue: 421
version: 1.0.0
---

Mandatory body sections

A spec body SHALL contain the following five sections, in this order, each introduced by a level-2 heading. Sections MAY be empty in a draft but MUST be present (a future linter relies on header presence to validate format conformance).

1. ## Intent

One paragraph, plain prose, that captures the user-facing WHAT in a single breath. The intent answers "what would a user notice if this spec were realized?". HOW words (by, via, using, technology names, library choices) are forbidden here; they belong in the plan artifact defined in issue #169.

2. ## Requirements

Numbered list. Each line is a normative statement using either SHALL or MUST. Imperatives without a modal verb are forbidden ("the system sends a notification" is not a requirement; "the system SHALL send a notification" is). HOW words are forbidden inside a requirement line for the same reason as in ## Intent.

Each requirement SHOULD be independently testable. A requirement that cannot be reduced to a scenario in ## Scenarios is a smell — either split it, or move the untestable part to ## Out of scope.

3. ## Scenarios

Each scenario uses the Given / When / Then form:

**Scenario:** <short title>

Given <pre-condition>
When  <triggering action>
Then  <observable outcome>

A spec SHALL include at least one happy-path scenario and at least one failure-path scenario. Scenarios are the bridge between the spec and the regression tests that the tester agent will produce in DEV; if a scenario cannot be turned into an automated check, escalate to the plan stage for a manual-verification clause.

4. ## Out of scope

Bullet list. Each bullet names a behavior, an integration, or a boundary that this spec deliberately excludes. The spec reviewer rejects implicit scope; if a behavior is not explicitly in ## Requirements and not explicitly excluded here, the spec is under-specified and SHALL be sent back to the author.

This section MAY be empty only for a trivial-tier spec.

5. ## Open questions

Bullet list. Captures unresolved questions at authoring time. The section MAY be empty. If non-empty in a status: approved spec, the reviewer SHALL require written closure on the logbook issue (per AGENTS.md → Logbook Issues) before approval — questions left open in an approved spec are pre-baked spec-class findings in the REVIEW loop and waste a downstream iteration.

Delta-spec convention

spec-class findings produced by the REVIEW loop (per ADR-0010 → Finding classification taxonomy) do not edit the original spec on main. The original's normative content is immutable once merged; corrections chain via delta-spec files. (Lifecycle metadata — status, superseded-by — and meaning-preserving editorial edits are exempt from this freeze; see Lifecycle states → Recording a status transition and Editorial edits.)

File layout

/specs/<NNNN>-<slug>.md                # original (immutable on main)
/specs/<NNNN>-<slug>.delta-01.md       # first delta
/specs/<NNNN>-<slug>.delta-02.md       # second delta, builds on delta-01

Delta numbers are zero-padded to two digits and allocated monotonically per parent spec.

Delta-spec frontmatter

A delta-spec carries the same frontmatter schema as the original, with two additional constraints:

  • id SHALL be the parent's id (the file is identified by its filename suffix, not by a new id).
  • version SHALL bump the parent's version per the rules below.
  • The delta-spec body replaces the mandatory body sections with the three delta sections defined next.

Delta-spec body sections

## ADDED

<requirements, scenarios, or out-of-scope items that the delta introduces>

## MODIFIED

<requirements, scenarios, or out-of-scope items the delta changes; quote the
original line, then show the replacement>

## REMOVED

<items the delta deletes; quote the original line>

The three delta sections SHALL be authored at H2 level. The H1 of a delta-spec file remains the spec's title; no intermediate H2 wrapper (## Body, ## Delta sections, or any other) SHALL be introduced.

All three sections MUST be present (empty is allowed); the linter will check for presence, not content. This mirrors the OpenSpec delta convention so external readers familiar with that vocabulary recognize the structure.

Versioning

The version field on a delta-spec records the cumulative state of the parent after the delta lands. Bump per semver intent:

  • PATCH — clarification, wording fix, scenario added without changing any existing requirement.
  • MINOR — additive normative change (new requirement, new scenario that constrains a previously unspecified case).
  • MAJOR — breaking normative change (requirement modified or removed in a way that invalidates an in-flight implementation).

The cumulative version is read from the highest-numbered delta-spec; the original file's version is never edited after merge.

Lifecycle states

The status field tracks where the spec sits in its own life. Each transition has a single authority and an accompanying artifact; the table below is the contract.

status Trigger Authority Accompanying artifact
draft Spec file opened in the working branch Spec author (human or spec-author skill) Spec file in the worktree, no PR yet
approved Spec PR merged on main Spec reviewer (per the interaction mode declared in frontmatter) Merged spec PR — its own (squash) commit already carries status: approved, so no separate status-transition PR is opened — plus a logbook comment recording the approval
implemented Implementation PR for related-issue merged on main Implementation team's pr-logbook Merged implementation PR — its own (squash) commit already carries status: implemented, so no separate status-transition PR is opened — plus a logbook closure comment
archived Related issue closed without implementation (won't fix, duplicate, abandoned) Ticket closer Logbook comment explaining the archival
superseded A newer spec replaces this one (often through a spec-class loop that grows beyond a delta) Author of the superseding spec superseded-by field set; superseding spec exists with its own id

A status regression (e.g. approved → draft) is prohibited; if a spec must be re-opened, supersede it instead.

No spec on main is a draft

A spec file present on main, other than a delta-spec, SHALL NOT carry status: draft. A spec reaches main only by its own merged spec-PR, which is the trigger the table above assigns to approved; draft on main therefore records a contradiction rather than a lagging value, and leaves a reader unable to use status for the one question it exists to answer — "merged and in force" or "proposed but never landed".

The rule is enforced mechanically rather than by recall. The spec linter (scripts/lib/spec-linter.js, run as task spec:lint in CI) enforces status invariants across all pull requests and on main (governed by specs/0109-spec-status-invariant-on-main.md and specs/0168-spec-status-transition-enforcement.md):

  • Spec PRs (spec/<NNNN>-* or introducing a new spec): CI fails ([FAIL]) if an added or modified non-delta spec file carries status: draft. The spec must transition to status: approved (and declare interaction-mode) before merging to main.
  • Implementation PRs ((feat|fix|refactor|perf|chore)/<NNNN>-*): CI fails ([FAIL]) if the corresponding specification file specs/<NNNN>-*.md does not carry status: implemented.
  • Base branch status check: The linter names every non-delta spec already present on the change's base branch that carries status: draft. Delta-specs are exempt per Spec 0109.

Which build the violation fails, and which it only warns. Being named and being failed are two different things, decided by two different questions. A change that modifies a named spec is failed by it ([FAIL]), because it can record the correct status in the same edit. A change that does not — a pull request touching no spec at all, say — gets the same spec named as a non-blocking warning ([WARN]) and passes: a check a change has no power to satisfy must not block it. The build that does fail in that case is the base branch's own, where HEAD is the base and there is therefore no change to charge the violation to. So a [WARN] met on a pull request is a statement about main, not about that pull request: it is cleared by correcting the named spec's status on the base branch, and nothing in the change under test will make it go away. When the linter cannot determine which files the change modifies, it reports every named spec as blocking and says so — an indeterminate answer never becomes an exemption. specs/0109-spec-status-invariant-on-main.delta-02.md is the contract.

Recording a status transition

The append-only rule (see Delta-spec convention) governs a spec's normative content — the body sections (## Intent, ## Requirements, ## Scenarios, ## Out of scope, ## Open questions) and the identifying frontmatter fields (id, slug). It does not freeze the lifecycle-tracking metadata: the status and superseded-by fields are expected to change, since the table above defines transitions the spec undergoes over its life.

Those transitions divide into three kinds, recorded differently. The first, draft → approved, is recorded inside the spec-PR's own commit, so the spec lands on main already carrying status: approved. The second, approved → implemented, is recorded inside the implementation PR's own commit, so the spec carries status: implemented the moment its implementation lands on main. Every later transition — → superseded, → archived — is recorded after the spec has merged, by a metadata-only edit to the merged spec's frontmatter. The three cases are defined in turn below.

Recording the initial draft → approved transition (in the spec-PR). Every interaction mode has a real approval event whose grant the recorded status: approved reflects, but which user gate constitutes that event is mode-dependent. In FULL, INTERMEDIATE, and MINIMAL the approval event is the SPECS-stage content-approval gate; because the approved spec content becomes a one-file spec-PR that merges unchanged, that same content-approval discharges the spec-PR's merge-authorization request, which is therefore not fired a second time (see interaction-modes.md → User-gate definition). In AUTO, where no SPECS-stage content-approval gate runs, the approval event is the merge-authorization request, which still fires and remains the sole approval event. The rule is thus mode-independent in effect — no mode lacks a real approval decision to record — while the gate that constitutes that decision differs by mode. The transition SHALL be recorded only after that approval event has been secured; recording status: approved ahead of it is a violation, because a recorded approved status must reflect an approval decision that has actually been made, not one presumed before it. The edit stays metadata-only in the sense the next paragraph defines: it sets status to approved and, when interaction-mode was omitted while the spec was draft, sets interaction-mode to the mode the spec was qualified under (the frontmatter schema requires it to be present once a spec is approved); it touches no body line, no id, no slug, and no version. Recorded this way, the merged spec-PR carries status: approved at the moment it lands on main — a merged spec is never at once merged and still draft — and no separate, post-merge, metadata-only pull request is required to record the approval.

Merge mechanic. Strictly after the approval event has been secured and strictly before running bash scripts/merge-spec-pr.sh, on the spec-PR branch (spec/<NNNN>-<slug>) edit the spec's frontmatter (status: draft → status: approved, adding interaction-mode if it was omitted during draft), create a new commit — not git commit --amend — then git push and only then bash scripts/merge-spec-pr.sh. A new commit rather than an amend because the spec-PR squash-merges, so both routes collapse to the same single commit on main carrying status: approved; a new commit needs only a plain git push, whereas an amend would force git push --force-with-lease and risk clobbering a concurrent reviewer or CI push on the shared branch.

Recording the approved → implemented transition (in the implementation PR). The implemented transition is triggered by the merge of the implementation PR for the spec's related-issue — a genuinely later, separate event that cannot be folded into the spec-PR that introduces the spec, but can be folded into the implementation PR itself. On the implementation feature branch, before the implementation PR merges, edit the spec's frontmatter (status: approved → status: implemented), create a new commit — not git commit --amend — then git push. The implementation PR squash-merges, so the transition rides the implementation PR's own squash commit and the spec lands on main already carrying status: implemented at the moment its implementation lands. The authority named in the table above (the implementation team's pr-logbook) performs the edit; it touches nothing else — no body line, no id, no slug, no version. A diff that alters any normative content under cover of the status bump is a violation. No separate, post-merge, metadata-only pull request is required to record the transition.

Recording a post-merge transition (every other transition). Every transition other than draft → approved and approved → implemented — → superseded, → archived — is triggered by a genuinely later, separate event (a superseding spec landing, a ticket closed without implementation) that cannot be folded into the spec-PR that introduces the spec, and so is recorded after merge by a metadata-only edit to the merged spec's frontmatter. The authority named in the table above changes the status field (and sets superseded-by when moving to superseded) and touches nothing else — no body line, no id, no slug, no version. A diff that alters any normative content under cover of a status bump is a violation. The version field stays immutable on the original after merge; the cumulative version lives on the highest-numbered delta (per Versioning).

This carve-out admits lifecycle metadata. A second, equally narrow carve-out admits meaning-preserving editorial edits to body prose; it is defined next.

Editorial edits

Alongside the lifecycle-metadata carve-out above, the append-only rule permits meaning-preserving editorial edits — orthography and typo corrections — to the body prose of a merged spec. An editorial edit may change the spelling or surface form of a word but SHALL NOT alter meaning. Permitted: fixing a misspelling, normalizing a British spelling to American, repairing a typo.

Forbidden, still: any change to the substance of a requirement, scenario, intent, or out-of-scope item. Correcting the spelling of a word inside a requirement is allowed; changing what that requirement obliges, permits, or forbids is not. Substantive corrections chain via delta-specs (see Delta-spec convention), never as in-place edits — exactly as before this carve-out. A diff that alters normative meaning under cover of an editorial fix is a violation, mirroring the same guard on the lifecycle-metadata carve-out.

This carve-out is deliberately narrow in the same spirit as the lifecycle-metadata one: it admits surface-form corrections only, leaving every normative guarantee of the merged spec untouched.

Naming convention

Spec files live under the top-level /specs/ directory. The naming pattern is fixed:

  • Original: /specs/<NNNN>-<kebab-slug>.md
  • Delta: /specs/<NNNN>-<kebab-slug>.delta-<NN>.md

<NNNN> is the spec id, zero-padded to four digits, allocated monotonically across the whole repository (not per-year, not per-component). The ticket creator picks the next free number by inspecting the existing /specs/ directory before opening the spec file. Collisions are resolved by the second author bumping to the next free number; spec ids are cheap and never reused.

<kebab-slug> mirrors the slug frontmatter field. The filename slug and the frontmatter slug SHALL match exactly.

<NN> (delta suffix) is zero-padded to two digits and unique within its parent.

Spec linter

The format is machine-checked by the spec linter (scripts/lib/spec-linter.js, invoked via task spec:lint and enforced in CI on every pull request via the lint-specs job). The linter enforces the following invariants:

  • The file SHALL pass markdownlint-cli with the project's .markdownlintrc configuration (CI invocation: markdownlint "**/*.md" --ignore node_modules --ignore extension-skeleton --ignore communication). In particular: no MD018 traps (do not let a wrapped line start with #NNN at column 1 — write issue #NNN or reflow the sentence).
  • The five mandatory body section headings SHALL be present and SHALL appear in the order defined above. Heading text SHALL match verbatim (case-sensitive, no trailing punctuation).
  • The frontmatter SHALL parse as YAML and SHALL contain every required field listed in the schema table.
  • For a delta-spec, the three delta section headings (## ADDED, ## MODIFIED, ## REMOVED) SHALL be present in that order, at H2 level. The H1 of a delta-spec file is the spec title; no intermediate H2 wrapper is allowed.
  • Enum-valued fields SHALL contain a value from the listed set; any other value is a lint error.
  • Status invariants are verified per the transition rules described above (governed by Spec 0109 and Spec 0168).