The spec folder
One folder per in-flight feature, living in docs/specs/<slug>/ — the folder name is the slug, which is the spec's identity. The folder
is its spec.md — the build contract — and everything else orbits it:
the graph that connects it, the questions still open, the build's own memory, and optional
research and plan. Three files are always present, one more whenever a build runs autonomously,
the rest only when there's something to put in them.
Knowing which file a thing belongs in — and which it does not — is what lets a fresh-context agent load only what the task needs:
spec.md required
Its purpose. The build contract — the one artifact that carries the whole decision so a fresh-context agent can build from it.
When present. Always. A spec folder is its spec.md; everything else orbits this file.
relations.md required
Its purpose. Forward edges only, authored — depends_on / part_of / supersedes / conflicts_with, each with a one-line why.
When present. Always. "none" is a valid value; the file's absence is not. Reverse edges live in the generated relations-index.yml.
open-questions.md required
Its purpose. Unresolved decisions, each carrying who decides, the options, the default, and the deadline.
When present. Required while unresolved decisions exist. An entry with a default and a future deadline is legal during building — indecision becomes a logged choice with an override window.
status.md required
Its purpose. The build's memory across fresh-context iterations — the resume point and the dead ends a stateless re-entry cannot reconstruct from the diff.
When present. Required for autonomous builds. Fixed schema (State / Done / In progress / Last green checkpoint / Dead ends); Specline checks shape, never prose.
discovery.md optional
Its purpose. Customer evidence, code research, rationale — the why behind the shape.
When present. Optional. Loaded for product thinking and reshape, not for the build.
implementation.md optional
Its purpose. The build-scratch: the 'how' B6 keeps out of spec.md — implementation proposals, mechanics, and suggested UI approach. (Adopts an engineering design-doc format.) A repo's design system / UI standards are NOT this file — they live at the repo level alongside architecture.md.
When present. Optional. Relocate the 'how' here, NOT into spec.md. It does not graduate.
api.md optional
Its purpose. A feature-specific API contract.
When present. Optional. Only when the spec defines an interface worth pinning separately.
No recursion. Sub-folders inside a spec folder are prohibited. A module needing sub-specs gives each its own slug with part_of: <slug> — flat folders with explicit edges beat nested trees.
Up: handbook — anatomy of a spec. The law: the canon, "Spec folder anatomy".