OpenSpec Workflows

When to Create Proposals

Create proposals for:

• New features or capabilities
• Breaking changes (API, schema)
• Architecture changes
• Performance optimizations (behavior changes)
• Security pattern updates

Skip proposals for:

• Bug fixes (restoring intended behavior)
• Typos, formatting, comments
• Non-breaking dependency updates
• Configuration changes
• Tests for existing behavior

Quick Commands

openspec list                  # List active changes
openspec list --specs          # List specifications
openspec show [item]           # Display change or spec
openspec validate [item] --strict  # Validate changes
openspec archive <change-id> --yes  # Archive after deployment

Creating Change Proposals

1. Context Checklist

Before starting:

• Read openspec/project.md for conventions
• Run openspec list to see active changes
• Run openspec list --specs to see existing capabilities
• Check for conflicts with pending changes

2. Choose Change ID

• Use kebab-case, verb-led: add-, update-, remove-, refactor-
• Examples: add-two-factor-auth, update-parquet-support
• Ensure uniqueness

3. Scaffold Structure

mkdir -p openspec/changes/<change-id>/specs/<capability>

Create:

• proposal.md - Why, what, impact
• tasks.md - Implementation checklist
• design.md - Only if needed (cross-cutting, architectural, or complex decisions)
• specs/<capability>/spec.md - Delta changes

4. Write Spec Deltas

Use operation headers:

• ## ADDED Requirements - New capabilities
• ## MODIFIED Requirements - Changed behavior (include full requirement)
• ## REMOVED Requirements - Deprecated features
• ## RENAMED Requirements - Name changes

Critical: Every requirement MUST have at least one scenario:

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

5. Validate

openspec validate <change-id> --strict

Fix all issues before sharing the proposal.

Implementation Workflow

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
5. Update checklist: mark all tasks - [x] when complete
6. Do not start implementation until proposal is approved

Archiving Changes

After deployment:

openspec archive <change-id> --yes

This moves changes/[name]/ → changes/archive/YYYY-MM-DD-[name]/

Common Patterns

Multi-Capability Changes

Create separate delta files:

changes/add-feature/
└── specs/
    ├── capability-a/
    │   └── spec.md   # ADDED: Feature A
    └── capability-b/
        └── spec.md   # ADDED: Feature B

MODIFIED Requirements

Always include the complete requirement:

1. Copy entire requirement from openspec/specs/<capability>/spec.md
2. Paste under ## MODIFIED Requirements
3. Edit to reflect new behavior
4. Keep at least one scenario

Troubleshooting

"Change must have at least one delta"

• Check changes/[name]/specs/ exists with .md files
• Verify files have operation prefixes

"Requirement must have at least one scenario"

• Use #### Scenario: format (4 hashtags)
• Don't use bullet points for scenario headers

Debug delta parsing:

openspec show [change] --json --deltas-only