fix: standardize GIVEN scenario guidance

[georgemclaughlin]

Summary

• Make OpenSpec's generated scenario guidance consistently show GIVEN before WHEN and THEN.
• Update spec templates, schema guidance, onboarding examples, and validation remediation examples.
• Add an OpenSpec change proposal for the convention update.

Scope

This updates framework guidance and generated templates only. It does not add parser enforcement, validation warnings, or rewrite existing specs.

OpenSpec already recognizes GIVEN, WHEN, THEN, and AND as valid scenario keywords, and that shape aligns with the common Given/When/Then style used in behavior-driven specifications. The current generated guidance mostly shows only WHEN and THEN, which can unintentionally steer new specs toward a narrower subset of the scenario language. This PR keeps the guidance non-enforcing, but makes the generated examples show the fuller pattern so preconditions have a clear place when they matter.

The intent is to make new generated examples match the existing Given/When/Then convention while preserving compatibility with specs that currently omit GIVEN.

Validation

• node bin/openspec.js validate standardize-given-scenario-guidance
• npm exec -- changeset status --since=origin/main
• npm run build
• npm run lint
• npx vitest run test/core/templates/skill-templates-parity.test.ts test/core/validation.enriched-messages.test.ts test/core/artifact-graph/instruction-loader.test.ts
• npm test

AI Assistance

Prepared with Codex using GPT-5.5 and manually reviewed/validated with the commands above.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR standardizes OpenSpec's scenario step guidance across schemas, templates, examples, and validation messages to consistently use GIVEN/WHEN/THEN format instead of WHEN/THEN-only. The change updates documentation, workflow schemas, code templates, validation messages, and test baselines without breaking existing specs.

Changes

Scenario Step Standardization

Layer / File(s)	Summary
Change documentation and specification .changeset/given-scenario-guidance.md, openspec/changes/standardize-given-scenario-guidance/*	Changeset entry documents the patch fix. Design, proposal, and tasks define goals (make GIVEN visible in default path), constraints (maintain compatibility, limit to templates/guidance), non-goals (no parsing/validation enforcement), and semantic roles. Formal spec added for Behavioral Spec Format conventions.
Schema and built-in template updates schemas/spec-driven/schema.yaml, schemas/spec-driven/templates/spec.md, schemas/workspace-planning/schema.yaml	Spec-driven workflow schema updated to require GIVEN/WHEN/THEN format in instructions and examples. Workspace-planning schema updated to prefer GIVEN/WHEN/THEN steps. Built-in spec template adds GIVEN placeholder.
Embedded workflow templates and validation guidance src/commands/schema.ts, src/core/templates/workflows/onboard.ts, src/core/templates/workflows/sync-specs.ts, src/core/validation/constants.ts	Onboarding and sync-specs workflow templates updated to show GIVEN as first step in examples. Schema init command template and validation remediation message examples expanded to include GIVEN/WHEN/THEN/AND format.
Test baseline hash updates test/core/templates/skill-templates-parity.test.ts	Parity test baseline hashes updated for template factory functions (getSyncSpecsSkillTemplate, getOnboardSkillTemplate, getOpsxSyncCommandTemplate, getOpsxOnboardCommandTemplate) and generated skill content (openspec-sync-specs, openspec-onboard) to reflect template changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Fission-AI/OpenSpec#698: Introduced the workflow template modules and parity testing scaffold that this PR updates with GIVEN-inclusive examples and hash baselines.

Suggested reviewers

• TabishB

Poem

🐰 In GIVEN state, we start anew,
WHEN triggers dance, then THEN comes true,
Three steps now guide the spec-writer's way,
Scenario steps shine bright today! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main change—standardizing scenario guidance to include GIVEN before WHEN and THEN across templates, schemas, and examples.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}