fix(schemas): include spec content guidance from concepts docs in specs instructions

[clay-good]

Closes #1289

What was missing: docs/concepts.md explains that a spec is a behavior contract — what belongs in one (observable behavior, inputs/outputs, constraints, testable scenarios) and what doesn't (class names, framework choices, implementation steps). But that guidance never reached agents: the specs instructions shipped with OpenSpec don't include it, so agents only follow it when a user pastes it in by hand (as reported in #1289).

What this does: Adds that guidance, verbatim from docs/concepts.md, to the specs artifact instruction in schemas/spec-driven/schema.yaml. Every agent authoring specs now sees it via openspec instructions specs, in new and existing projects alike (the built-in schema resolves from the package, so no migration is needed).

Proof it works: openspec instructions specs on a fresh project now emits the guidance inside the <instruction> block; resolver, instruction-loader, and skill-template parity tests pass.

Notes: Deliberately narrow — one file, +17 lines, no skill template changes (the broader rewrite in #1284 was closed in favor of surgical fixes).

Note

For the reviewer: one path is intentionally not covered — the sync-specs skill carries its own inline delta-format guidance and doesn't go through openspec instructions specs, so it won't show this guidance. Covering it means touching skill templates (and their golden hashes), so I left it as a possible follow-up.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

The artifacts.specs generation instruction in schemas/spec-driven/schema.yaml was extended with guidance defining a "good spec" as a behavior contract, listing what to include and avoid, and adding a quick-test heuristic for spec suitability.

Changes

Spec Guidance Documentation

Layer / File(s)	Summary
Good-spec guidance addition schemas/spec-driven/schema.yaml	Instruction text added specifying behavior-contract framing, inclusion/exclusion criteria, and a quick-test heuristic for specs.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• Fission-AI/OpenSpec#595: Also modifies the artifacts.specs generation instruction in schemas/spec-driven/schema.yaml, extending the same instruction block.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The added schema guidance matches issue #1289's requirements for good spec content and exclusions.
Out of Scope Changes check	✅ Passed	The PR is limited to one schema instruction update and does not introduce unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding spec content guidance to schema instructions.

✨ 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.}

[TabishB]

Happy to try this out. Need a way to eval or A/B test these kinds of things.

I think defining an eval would be a good way for us to describe the desirable condition.

[TabishB]

Hm thining about this more: should this be in the instructions or in a skill? <- unsure how we should be thinking about this.

I believe the instructions only get applied at skill/command invocation time?

if someone is editing this directly with their agents, will the agent keep these instructions in mind?

[clay-good]

No, if someone edits specs directly with their agent, the agent won't see these instructions. They only surface when something runs openspec instructions specs.

Moving the guidance into a skill wouldn't change that: skills are also only in context when invoked, so a direct edit bypasses both equally. The instruction block is just the cheapest single place that covers all the skill-driven flows (new-change, continue-change, ff-change, propose all route through it).

For direct edits, a realistic backstop would be a content-level check in openspec validate maybe?