Change the Beskid Standard
OpenSpec is the sole normative authority. Docs are informative and must not create a second requirement.
Prerequisites
Section titled “Prerequisites”Describe the observable behavior that must change. Identify the stable capability identifier and existing requirements that the change affects.
Actions
Section titled “Actions”- Create an OpenSpec change with a proposal, design when needed, tasks, and a capability delta.
- Write each normative requirement with
SHALL or MUST. - Give every scenario
GIVEN, WHEN, and THENconditions. - Run
openspec validate <change-id> --strict --no-interactivefor the selected change. - Run
pnpm run openspec:validatefrom the repository root. - Regenerate
openspec/catalog.jsononly when the owning change requires the deterministic projection.
flowchart LR accTitle: OpenSpec authority and publication flow accDescr: A contributor validates an OpenSpec change. Accepted requirements enter the canonical specification. The catalog projects identifiers. Docs then link to that authority. C[OpenSpec change] --> V[Strict validation] V --> S[Canonical specification] S --> K[Catalog projection] K --> D[Docs summary]
Diagram text
Section titled “Diagram text”| Stage | Result |
|---|---|
| OpenSpec change | The proposal identifies scope and the capability delta contains each proposed requirement. |
| Strict validation | Every SHALL or MUST rule and every GIVEN, WHEN, and THEN scenario passes validation. |
| Canonical specification | Accepted files under openspec/specs/ become the normative source. |
| Catalog projection | openspec/catalog.json publishes stable identifiers and source relationships. |
| Docs summary | The informative Docs explain a task and link to the canonical requirement. |
Expected result
Section titled “Expected result”Validation accepts complete SHALL or MUST requirements and GIVEN, WHEN, and THEN scenarios. The catalog keeps stable identifiers for the accepted source.
Recovery
Section titled “Recovery”If strict validation reports a validation error, correct the OpenSpec change. Run the focused command again. In this case, do not change Docs to hide a normative conflict. If a generated catalog differs unexpectedly, stop and inspect the source change and generator revision.