spec

A spec — a design document describing work to be done. Specs are markdown files with YAML frontmatter in docs/specs/. State is derived from location: docs/specs/ = active, docs/specs/done/ = done.

Metadata	Value
Plural	`specs`
Subtitle field	`state`
Also	`task` · `file`

Fields

Field	Type
`problem`	`text`
`successCriteria`	`text`

Relations

Relation	Target
`dependsOn`	`spec[]`
`supersedes`	`spec[]`

Inherited

From task · file:

Field	Type
`encoding`	`string`
`filename`	`string`
`format`	`string`
`kind`	`string`
`labels`	`string[]`
`lineCount`	`integer`
`mimeType`	`string`
`path`	`string`
`priority`	`integer`
`remoteId`	`string`
`sha`	`string`
`size`	`integer`
`startedAt`	`datetime`
`state`	`string`
`targetDate`	`datetime`

Relation	Target
`assignedTo`	`person`
`attachedTo`	`message`
`blockedBy`	`task[]`
`blocks`	`task[]`
`children`	`task[]`
`parent`	`task`
`project`	`project`
`repository`	`repository`

Prior art

External standards this shape draws from or aligns with. See Shape design principles for how prior art informs shape design.

IETF RFC process — Canonical “design doc with problem statement and success criteria” lineage. Our problem/successCriteria mirror the RFC structure.
Architectural Decision Records (ADR / MADR) — Modern in-repo equivalent. supersedes[] matches ADR’s “Supersedes” link; dependsOn[] has no direct ADR peer.
Python PEP (spec-as-markdown) — PEP states problem, rationale, spec, rejected alternatives. Our fields are a slim version of the PEP template.