Spec frontmatter
Frontmatter is identity — nothing else: four keys, always present. There is no status field to keep in step with the folder — where a spec lives is its state (see lifecycle). The graph lives only in relations.md. An agent triages any spec from its path and its first ten lines.
| Field | Values | When |
|---|---|---|
slug | kebab-case | Always. The spec's identity — matches the folder name; unique to one feature across specs/, knowledge/, and archive/. Graduation preserves the same slug in its knowledge + archive pair. Frozen once the spec lands on the merge target: renaming a referenced spec dangles its inbound edges. Re-slugging before it lands is legal — nothing points at it yet. |
type | feature | bug | chore | parent | Always. A bug is a spec with type: bug; a decomposition parent is type: parent. |
decider | a named human | Always. The PO accountable for this spec. |
created | date | Always. Spec authoring date; the lead-time clock starts here. |
status | shipped | killed | Only in archive/ — location can't tell the two apart there. Dropped everywhere else: where a spec lives (drafts/ → specs/ → knowledge/ + archive/) is its state. A status: line written against an earlier canon (draft, ratified, building, blocked) is recognised silently. |
The unattended envelope
Experimental — in force only when specline.yml setsunattended: true. Off by default; nothing here is checked or listed until you turn it on.
Legal on any spec, but what build: unattended promises — a builder that can't ask needs the routing, the leash, and the clock on the page. An attended spec may carry them when they're useful, but Specline only checks their completeness once the spec declares build: unattended.
| Field | Values | When |
|---|---|---|
build | attended | unattended | Optional — write it whenever the posture is known. Absent means attended: the builder can reach the decider. unattended is a promise that a fresh-context builder who cannot ask has everything it needs; it is what puts the envelope fields below in scope, and it changes no rule's severity. |
blast_radius | low | medium | high | Legal on any spec; checked only when unattended. Declared risk surface; drives reviewer depth, implementer effort, and model tier. |
size | small | large | Legal on any spec; checked only when unattended. Declared build size (default small). small = one slice; large = an atomic batch. The build axis — distinct from appetite (the review axis). |
target_model | light | standard | frontier | Optional; checked only when unattended. Pins a capability tier; if absent, derived from blast_radius and the coupling proxy. |
stale_after | date | Checked only when unattended. Set on entering building or blocked — the staleness / abandonment trigger. |
loop_budget | positive integer | Optional; checked only when unattended. The PO's autonomy grant — the cap on autonomous build cycles with no green-checkpoint advance. |
acceptance_results | a link | On archived specs only; checked only when unattended — the structural proxy that graduation ran the acceptance checks. |
These are per-spec, set at the decider's go. loop_budget lives here, in the spec's frontmatter — it is the PO's autonomy grant for this build, not a repo-wide setting in specline.yml. The build escalates back to a human gate at the first of two triggers: loop_budget exhausted (no progress) or stale_after reached (too much time).
Up: handbook — building. The law: the canon, "Frontmatter".