Skip to content
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
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
13 changes: 12 additions & 1 deletion schemas/spec-driven/schema.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,20 @@ artifacts:
- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
- **Capabilities**: Identify which specs will be created or modified:
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty only when the change introduces new capabilities instead.
- **Impact**: Affected code, APIs, dependencies, or systems.

IMPORTANT: The Capabilities section is critical. It creates the contract between
proposal and specs phases. Research existing specs before filling this in.
Each capability listed here will need a corresponding spec file.

Every change must declare at least one capability (new or modified) -
`openspec validate` rejects a change with zero deltas. Even a pure
refactor with no user-visible behavior change should name at least one
explicit, testable property or guarantee it changes (often a
non-functional requirement such as performance, compatibility, or
observability). Do not leave both capability sections empty.

Keep it concise (1-2 pages). Focus on the "why" not the "how" -
implementation details belong in design.md.

Expand Down Expand Up @@ -55,6 +62,10 @@ artifacts:
- 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.

There must be at least one spec file - `openspec validate` rejects a change
with zero deltas. If the proposal lists no capabilities, revisit the
proposal first.

Delta operations (use ## headers):
- **ADDED Requirements**: New capabilities
- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
Expand Down
6 changes: 5 additions & 1 deletion schemas/spec-driven/templates/proposal.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,11 @@
### Modified Capabilities
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
Only list here if spec-level behavior changes. Each needs a delta spec file.
Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
Use existing spec names from openspec/specs/. Leave empty only when the change
introduces new capabilities instead - every change needs at least one capability
(new or modified); openspec validate rejects a change with zero deltas. Even a
pure refactor should name at least one explicit, testable property or guarantee
it changes. -->
- `<existing-name>`: <what requirement is changing>

## Impact
Expand Down
Loading