openspec-context-docs

Two-layer documentation separates normative requirements from narrative context by keeping requirements in spec.md as the authoritative source and capturing rationale, decisions, and operational notes in context.md.

Onboarding docs are structured by placing spec.md with normative requirements and context.md with purpose, constraints, and examples under openspec/specs, optionally adding overview, rationale, and ops notes for maintainers.

After implementation, stable context from change notes is promoted to the main context docs, with a link back to the spec to maintain synchronization between implemented changes and authoritative requirements.

Use a two-layer spec and context approach when you need a disciplined structure to keep normative requirements in a single place while separately capturing narrative rationale, failure modes, constraints, and rollout notes.

Context.md should document purpose, decisions, constraints, examples, failure modes, operational notes, and links back to the spec to fully capture the narrative rationale alongside the normative requirements.

Spec and context files should be organized under openspec/specs, with optional overview, rationale, and ops notes placed alongside to support both readers and maintainers effectively.