openspec-context-docs

Two-layer spec documentation separates normative requirements in spec.md from narrative rationale in context.md. This structure ensures clear, maintainable specifications while providing onboarding materials with the rationale and operational notes needed to apply them.

To create OpenSpec context docs, place a context.md file alongside spec.md for each capability. Link context.md back to spec.md, include rationale and examples, and store stable context updates under the openspec/specs directory path.

Update OpenSpec context documentation when creating or updating specs, onboarding guides, or change artifacts. Sync context notes to the main context only after implementation verification to ensure the narrative rationale matches the verified normative requirements.

OpenSpec documentation governance supports syncing context notes to the main context after implementation verification. This ensures the narrative context accurately reflects the verified spec.md requirements before being promoted as a stable update.

The best way to structure onboarding guides is using the two-layer documentation policy. Keep normative requirements in spec.md and provide rationale, examples, and operational notes in context.md to help readers apply the specifications effectively.

A single spec.md file is not recommended under the two-layer OpenSpec policy. Separating normative requirements from narrative context ensures clear, maintainable specifications and prevents rationale from cluttering the core requirements.