When creating or updating capability docs under openspec/specs/<capability>/, use a split-file format:
-
spec.md(normative tests only)- Purpose (1–3 sentences)
- Requirements/Scenarios (normative)
- Links to sibling docs (markdown links)
-
feature.md(black + white box in one file)- Overview / Context / Problems addressed
- Goals / Non-Goals (or In scope / Out of scope)
- Usage workflows / scenarios beyond tests
- Success criteria (if applicable)
- Architecture description
- Constraints
- Entities
- Interfaces (Inputs/Outputs)
- Invariants (if applicable)
- Events / Triggers
- Links to sibling docs (markdown links)
Cross-links are recommended in all files:
- Link to sibling docs within the same capability
- Link across capabilities when concepts are shared
Use markdown links (e.g.,
[feature](feature.md)), not backticked filenames.
Keep spec.md lean; requirements and scenarios are the normative tests.