Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
clay-good merged 1 commit into from
Jul 17, 2026
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions schemas/spec-driven/schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,23 @@ artifacts:
instruction: |
Create specification files that define WHAT the system should do.

A spec is a behavior contract, not an implementation plan.

@TabishB TabishB Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 clay-good Jul 8, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


Good spec content:
- Observable behavior users or downstream systems rely on
- Inputs, outputs, and error conditions
- External constraints (security, privacy, reliability, compatibility)
- Scenarios that can be tested or explicitly validated

Avoid in specs:
- Internal class/function names
- Library or framework choices
- Step-by-step implementation details
- Detailed execution plans (those belong in design.md or tasks.md)

Quick test: if the implementation can change without changing externally
visible behavior, it likely does not belong in the spec.

Create one spec file per capability listed in the proposal's Capabilities section.
- New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
- Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
Expand Down
Loading