mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
aeaa1d50cc
Remove the Format Flexibility section as it's not needed for the structured spec format. Keep focus on behavioral specifications only.
177 lines
6.4 KiB
Markdown
177 lines
6.4 KiB
Markdown
# OpenSpec Conventions Specification
|
|
|
|
## Purpose
|
|
|
|
OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions.
|
|
|
|
## Core Principles
|
|
|
|
The system SHALL follow these principles:
|
|
- Specs reflect what IS currently built and deployed
|
|
- Changes contain proposals for what SHOULD be changed
|
|
- AI drives the documentation process
|
|
- Specs are living documentation kept in sync with deployed code
|
|
|
|
## Directory Structure
|
|
|
|
### Requirement: Project Structure
|
|
|
|
An OpenSpec project SHALL maintain a consistent directory structure for specifications and changes.
|
|
|
|
#### Scenario: Initializing project structure
|
|
|
|
- **WHEN** an OpenSpec project is initialized
|
|
- **THEN** it SHALL have this structure:
|
|
```
|
|
openspec/
|
|
├── project.md # Project-specific context
|
|
├── README.md # AI assistant instructions
|
|
├── specs/ # Current deployed capabilities
|
|
│ └── [capability]/ # Single, focused capability
|
|
│ ├── spec.md # WHAT and WHY
|
|
│ └── design.md # HOW (optional, for established patterns)
|
|
└── changes/ # Proposed changes
|
|
├── [change-name]/ # Descriptive change identifier
|
|
│ ├── proposal.md # Why, what, and impact
|
|
│ ├── tasks.md # Implementation checklist
|
|
│ ├── design.md # Technical decisions (optional)
|
|
│ └── specs/ # Complete future state
|
|
│ └── [capability]/
|
|
│ └── spec.md # Clean markdown (no diff syntax)
|
|
└── archive/ # Completed changes
|
|
└── YYYY-MM-DD-[name]/
|
|
```
|
|
|
|
## Specification Format
|
|
|
|
### Requirement: Structured Format for Behavioral Specs
|
|
|
|
Behavioral specifications SHALL use a structured format with consistent section headers and keywords to ensure visual consistency and parseability.
|
|
|
|
#### Scenario: Writing requirement sections
|
|
|
|
- **WHEN** documenting a requirement in a behavioral specification
|
|
- **THEN** use a level-3 heading with format `### Requirement: [Name]`
|
|
- **AND** immediately follow with a SHALL statement describing core behavior
|
|
- **AND** keep requirement names descriptive and under 50 characters
|
|
|
|
#### Scenario: Documenting scenarios
|
|
|
|
- **WHEN** documenting specific behaviors or use cases
|
|
- **THEN** use level-4 headings with format `#### Scenario: [Description]`
|
|
- **AND** use bullet points with bold keywords for steps:
|
|
- **GIVEN** for initial state (optional)
|
|
- **WHEN** for conditions or triggers
|
|
- **THEN** for expected outcomes
|
|
- **AND** for additional outcomes or conditions
|
|
|
|
#### Scenario: Adding implementation details
|
|
|
|
- **WHEN** a step requires additional detail
|
|
- **THEN** use sub-bullets under the main step
|
|
- **AND** maintain consistent indentation
|
|
- Sub-bullets provide examples or specifics
|
|
- Keep sub-bullets concise
|
|
|
|
|
|
## Change Storage Convention
|
|
|
|
### Requirement: Future State Storage
|
|
|
|
Change proposals SHALL store complete future state specifications without diff syntax.
|
|
|
|
#### Scenario: Creating change proposals
|
|
|
|
- **WHEN** creating a change proposal
|
|
- **THEN** store the complete future state of affected specs
|
|
- **AND** use clean markdown without diff syntax
|
|
|
|
The `changes/[name]/specs/` directory SHALL contain:
|
|
- Complete spec files as they will exist after the change
|
|
- Clean markdown without `+` or `-` prefixes
|
|
- All formatting and structure of the final intended state
|
|
|
|
### Requirement: Proposal Format
|
|
|
|
Proposals SHALL explicitly document all changes with clear from/to comparisons.
|
|
|
|
#### Scenario: Documenting changes
|
|
|
|
- **WHEN** documenting what changes
|
|
- **THEN** the proposal SHALL explicitly describe each change:
|
|
|
|
```markdown
|
|
**[Section or Behavior Name]**
|
|
- From: [current state/requirement]
|
|
- To: [future state/requirement]
|
|
- Reason: [why this change is needed]
|
|
- Impact: [breaking/non-breaking, who's affected]
|
|
```
|
|
|
|
This explicit format compensates for not having inline diffs and ensures reviewers understand exactly what will change.
|
|
|
|
## Change Lifecycle
|
|
|
|
The change process SHALL follow these states:
|
|
|
|
1. **Propose**: AI creates change with future state specs and explicit proposal
|
|
2. **Review**: Humans review proposal and future state
|
|
3. **Approve**: Change is approved for implementation
|
|
4. **Implement**: Follow tasks.md checklist (can span multiple PRs)
|
|
5. **Deploy**: Changes are deployed to production
|
|
6. **Update**: Specs in `specs/` are updated to match deployed reality
|
|
7. **Archive**: Change is moved to `archive/YYYY-MM-DD-[name]/`
|
|
|
|
## Viewing Changes
|
|
|
|
### Requirement: Change Review
|
|
|
|
The system SHALL support multiple methods for reviewing proposed changes.
|
|
|
|
#### Scenario: Reviewing changes
|
|
|
|
- **WHEN** reviewing proposed changes
|
|
- **THEN** reviewers can compare using:
|
|
- GitHub PR diff view when changes are committed
|
|
- Command line: `diff -u specs/[capability]/spec.md changes/[name]/specs/[capability]/spec.md`
|
|
- Any visual diff tool comparing current vs future state
|
|
|
|
The system relies on tools to generate diffs rather than storing them.
|
|
|
|
## Capability Naming
|
|
|
|
Capabilities SHALL use:
|
|
- Verb-noun patterns (e.g., `user-auth`, `payment-capture`)
|
|
- Hyphenated lowercase names
|
|
- Singular focus (one responsibility per capability)
|
|
- No nesting (flat structure under `specs/`)
|
|
|
|
## When Changes Require Proposals
|
|
|
|
A proposal SHALL be created for:
|
|
- New features or capabilities
|
|
- Breaking changes to existing behavior
|
|
- Architecture or pattern changes
|
|
- Performance optimizations that change behavior
|
|
- Security updates affecting access patterns
|
|
|
|
A proposal is NOT required for:
|
|
- Bug fixes restoring intended behavior
|
|
- Typos or formatting fixes
|
|
- Non-breaking dependency updates
|
|
- Adding tests for existing behavior
|
|
- Documentation clarifications
|
|
|
|
## Why This Approach
|
|
|
|
Clean future state storage provides:
|
|
- **Readability**: No diff syntax pollution
|
|
- **AI-compatibility**: Standard markdown that AI tools understand
|
|
- **Simplicity**: No special parsing or processing needed
|
|
- **Tool-agnostic**: Any diff tool can show changes
|
|
- **Clear intent**: Explicit proposals document reasoning
|
|
|
|
The structured format adds:
|
|
- **Visual Consistency**: Requirement and Scenario prefixes make sections instantly recognizable
|
|
- **Parseability**: Consistent structure enables tooling and automation
|
|
- **Gradual Adoption**: Existing specs can migrate incrementally |