OpenSpec Workflow

Guide Claude Code through spec-driven development using OpenSpec's three-stage workflow. This skill ensures proposals are created before implementation, specs are properly formatted, and changes are archived after deployment.

When to Use This Skill

Use OpenSpec workflow when:

• Adding new features or capabilities
• Making breaking changes (API, schema, behavior)
• Changing architecture or patterns
• Optimizing performance (changes behavior)
• Updating security patterns
• User mentions: proposal, spec, change, plan, feature, breaking, architecture

Skip OpenSpec workflow for:

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

Three-Stage Workflow

Stage 1: Creating Changes

Before starting:

1. Check existing work: openspec list and openspec list --specs
2. Review project conventions: Read openspec/project.md
3. Search for conflicts: rg -n "Requirement:|Scenario:" openspec/specs

Create proposal:

1. Choose unique change-id (kebab-case, verb-led: add-, update-, remove-, refactor-)
2. Scaffold directory structure:

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

3. Create required files:
   • proposal.md - Why, what changes, impact
   • tasks.md - Implementation checklist
   • design.md - Technical decisions (only if needed, see criteria below)
   • specs/<capability>/spec.md - Delta changes

When to create design.md: Create design.md only if ANY of these apply:

• Cross-cutting change (multiple services/modules) or new architectural pattern
• New external dependency or significant data model changes
• Security, performance, or migration complexity
• Ambiguity that benefits from technical decisions before coding

Otherwise, omit design.md to keep proposals lean.

Validate before sharing:

openspec validate <change-id> --strict

Fix all errors before requesting approval. Common issues:

• Missing scenarios (every requirement needs ≥1 scenario)
• Wrong scenario format (must use #### Scenario: with 4 hashtags)
• Missing delta operations (need ADDED/MODIFIED/REMOVED headers)

Stage 2: Implementing Changes

Approval gate: Do NOT start implementation until proposal is reviewed and approved.

Implementation steps:

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. Confirm completion - Ensure every item finished
6. Update checklist - Set every task to - [x] after completion

Track as TODOs: Use TodoWrite to track each task and mark complete as you go.

Stage 3: Archiving Changes

After deployment, archive the change:

openspec archive <change-id> --yes

This will:

• Move changes/<name>/ → changes/archive/YYYY-MM-DD-<name>/
• Merge spec deltas into specs/ (source of truth)
• Validate the archived change passes checks

For tooling-only changes (no spec updates):

openspec archive <change-id> --skip-specs --yes

Spec Format Conventions

Delta Operations

Use these headers in changes/<id>/specs/<capability>/spec.md:

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

Critical: MODIFIED requirements When using MODIFIED:

1. Locate existing requirement in openspec/specs/<capability>/spec.md
2. Copy entire requirement block (header + scenarios)
3. Paste under ## MODIFIED Requirements and edit
4. Include ALL previous content + your changes (archiver replaces entire requirement)

Common mistake: Using MODIFIED to add new concerns without including previous text. This causes data loss. If not changing existing requirement, use ADDED instead.

Requirement Format

### Requirement: Feature Name
The system SHALL/MUST provide [capability].

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

#### Scenario: Error case
- **WHEN** invalid input provided
- **THEN** error message shown

Critical rules:

• Use ### Requirement: (3 hashtags) for requirement headers
• Use #### Scenario: (4 hashtags) for scenario headers
• Every requirement MUST have ≥1 scenario
• Use SHALL/MUST for normative requirements
• Don't use bullets or bold for scenario headers

Multi-Capability Changes

If change affects multiple capabilities, create multiple delta files:

openspec/changes/add-2fa-notify/
├── proposal.md
├── tasks.md
└── specs/
    ├── auth/
    │   └── spec.md   # ADDED: Two-Factor Authentication
    └── notifications/
        └── spec.md   # ADDED: OTP Email Notification

CLI Command Reference

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-id> --yes  # Archive after deployment

Useful flags:

• --json - Machine-readable output
• --strict - Comprehensive validation
• --yes / -y - Skip confirmation prompts
• --skip-specs - Archive without spec updates

For detailed CLI reference, see references/cli-reference.md.

Common Errors and Solutions

"Change must have at least one delta"

• Check changes/<name>/specs/ exists with .md files
• Verify files have operation headers (## 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 failures

• Always use --strict flag for comprehensive checks
• Check JSON output: openspec show <change> --json | jq '.deltas'

For more troubleshooting, see references/troubleshooting.md.

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)

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"

Change ID Naming

• Use kebab-case: add-two-factor-auth
• Prefer verb-led prefixes: add-, update-, remove-, refactor-
• Ensure uniqueness; if taken, append -2, -3, etc.

Quick Reference

Stage Indicators

• changes/ - Proposed, not yet built
• specs/ - Built and deployed (source of truth)
• archive/ - Completed changes

File Purposes

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

Happy Path Script

# 1) Explore current state
openspec list
openspec list --specs

# 2) Choose change id and scaffold
CHANGE=add-two-factor-auth
mkdir -p openspec/changes/$CHANGE/specs/auth
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md

# 3) Add deltas
cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
## ADDED Requirements
### Requirement: Two-Factor Authentication
Users MUST provide a second factor during login.

#### Scenario: OTP required
- **WHEN** valid credentials are provided
- **THEN** an OTP challenge is required
EOF

# 4) Validate
openspec validate $CHANGE --strict

Additional Resources

• CLI Reference: See references/cli-reference.md for all commands and flags
• Spec Format: See references/spec-format.md for detailed format rules
• Troubleshooting: See references/troubleshooting.md for error solutions

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