fission-ai__openspec/openspec/README.md

OpenSpec Instructions

Instructions for AI coding assistants using OpenSpec for spec-driven development.

Three-Stage Workflow

Stage 1: Creating Changes

Create proposal when you need to:

• Add features or functionality
• Make breaking changes (API, schema)
• Change architecture or patterns
• Optimize performance (changes behavior)
• Update security patterns

Skip proposal for:

• Bug fixes (restore intended behavior)
• Typos, formatting, comments
• Dependency updates (non-breaking)
• Configuration changes
• Tests for existing behavior

Stage 2: Implementing Changes

1. Read proposal.md - Understand what's being built
2. Read design.md (if exists) - Review technical decisions
3. Read tasks.md - Get implementation checklist
4. Implement tasks sequentially - Complete in order
5. Mark complete immediately - Update - [x] after each task

Stage 3: Archiving Changes

After deployment, create separate PR to:

• Move changes/[name]/ → changes/archive/YYYY-MM-DD-[name]/
• Update specs/ if capabilities changed
• Use openspec archive [change] --skip-specs for tooling-only changes

Before Any Task

Context Checklist:

• Read relevant specs in specs/[capability]/spec.md
• Check pending changes in changes/ for conflicts
• Read openspec/project.md for conventions
• Run openspec list to see active changes
• Run openspec list --specs to see existing capabilities

Before Creating Specs:

• Always check if capability already exists
• Prefer modifying existing specs over creating duplicates
• Use openspec show [spec] to review current state

Quick Start

CLI Commands

# Essential commands
openspec list                  # List active changes
openspec list --specs          # List specifications
openspec show [item]           # Display change or spec
openspec validate [item]       # Validate changes or specs
openspec archive [change]      # Archive after deployment

# Project management
openspec init [path]           # Initialize OpenSpec
openspec update [path]         # Update instruction files

# Interactive mode
openspec show                  # Prompts for selection
openspec validate              # Bulk validation mode

# Debugging
openspec show [change] --json --deltas-only
openspec validate [change] --strict

Command Flags

• --json - Machine-readable output
• --type change|spec - Disambiguate items
• --strict - Comprehensive validation
• --no-interactive - Disable prompts
• --skip-specs - Archive without spec updates

Directory Structure

openspec/
├── project.md              # Project conventions
├── specs/                  # Current truth - what IS built
│   └── [capability]/       # Single focused capability
│       ├── spec.md         # Requirements and scenarios
│       └── design.md       # Technical patterns
├── changes/                # Proposals - what SHOULD change
│   ├── [change-name]/
│   │   ├── proposal.md     # Why, what, impact
│   │   ├── tasks.md        # Implementation checklist
│   │   ├── design.md       # Technical decisions (optional)
│   │   └── specs/          # Delta changes
│   │       └── [capability]/
│   │           └── spec.md # ADDED/MODIFIED/REMOVED
│   └── archive/            # Completed changes

Creating Change Proposals

Decision Tree

New request?
├─ Bug fix restoring spec behavior? → Fix directly
├─ Typo/format/comment? → Fix directly  
├─ New feature/capability? → Create proposal
├─ Breaking change? → Create proposal
├─ Architecture change? → Create proposal
└─ Unclear? → Create proposal (safer)

Proposal Structure

1. Create directory: changes/[descriptive-name]/

2. Write proposal.md:

## Why
[1-2 sentences on problem/opportunity]

## What Changes
- [Bullet list of changes]
- [Mark breaking changes with **BREAKING**]

## Impact
- Affected specs: [list capabilities]
- Affected code: [key files/systems]

3. Create spec deltas: specs/[capability]/spec.md

## ADDED Requirements
### Requirement: New Feature
The system SHALL provide...

#### Scenario: Success case
- **WHEN** user performs action
- **THEN** expected result

## MODIFIED Requirements
### Requirement: Existing Feature
[Complete modified requirement]

## REMOVED Requirements
### Requirement: Old Feature
**Reason**: [Why removing]
**Migration**: [How to handle]

4. Create tasks.md:

## 1. Implementation
- [ ] 1.1 Create database schema
- [ ] 1.2 Implement API endpoint
- [ ] 1.3 Add frontend component
- [ ] 1.4 Write tests

Spec File Format

Critical: Scenario Formatting

CORRECT (use #### headers):

#### Scenario: User login success
- **WHEN** valid credentials provided
- **THEN** return JWT token

WRONG (don't use bullets or bold):

- **Scenario: User login**  ❌
**Scenario**: User login     ❌
### Scenario: User login      ❌

Every requirement MUST have at least one scenario.

Delta Operations

• ## ADDED Requirements - New capabilities
• ## MODIFIED Requirements - Changed behavior
• ## REMOVED Requirements - Deprecated features
• ## RENAMED Requirements - Name changes

Headers matched with trim(header) - whitespace ignored.

Troubleshooting

Common Errors

"Change must have at least one delta"

• Check changes/[name]/specs/ exists with .md files
• Verify files have operation prefixes (## ADDED Requirements)

"Requirement must have at least one scenario"

• Check scenarios use #### Scenario: format (4 hashtags)
• Don't use bullet points or bold for scenario headers

Silent scenario parsing failures

• Exact format required: #### Scenario: Name
• Debug with: openspec show [change] --json --deltas-only

Validation Tips

# Always use strict mode for comprehensive checks
openspec validate [change] --strict

# Debug delta parsing
openspec show [change] --json | jq '.deltas'

# Check specific requirement
openspec show [spec] --json -r 1

Best Practices

Simplicity First

• Default to <100 lines of new code
• Single-file implementations until proven insufficient
• Avoid frameworks without clear justification
• Choose boring, proven patterns

Complexity Triggers

Only add complexity with:

• Performance data showing current solution too slow
• Concrete scale requirements (>1000 users, >100MB data)
• Multiple proven use cases requiring abstraction

Clear References

• Use file.ts:42 format for code locations
• Reference specs as specs/auth/spec.md
• Link related changes and PRs

Capability Naming

• Use verb-noun: user-auth, payment-capture
• Single purpose per capability
• 10-minute understandability rule
• Split if description needs "AND"

Tool Selection Guide

Task	Tool	Why
Find files by pattern	Glob	Fast pattern matching
Search code content	Grep	Optimized regex search
Read specific files	Read	Direct file access
Explore unknown scope	Task	Multi-step investigation

Error Recovery

Change Conflicts

1. Run openspec list to see active changes
2. Check for overlapping specs
3. Coordinate with change owners
4. Consider combining proposals

Validation Failures

1. Run with --strict flag
2. Check JSON output for details
3. Verify spec file format
4. Ensure scenarios properly formatted

Missing Context

1. Read project.md first
2. Check related specs
3. Review recent archives
4. Ask for clarification

Quick Reference

Stage Indicators

• changes/ - Proposed, not yet built
• specs/ - Built and deployed
• archive/ - Completed changes

File Purposes

• proposal.md - Why and what
• tasks.md - Implementation steps
• design.md - Technical decisions
• spec.md - Requirements and behavior

CLI Essentials

openspec list              # What's in progress?
openspec show [item]       # View details
openspec validate --strict # Is it correct?
openspec archive [change]  # Mark complete

Remember: Specs are truth. Changes are proposals. Keep them in sync.