OpenSpec Instructions

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

TL;DR Quick Checklist

Three-Stage Workflow

Stage 1: Creating Changes

Create proposal when you need to:

Triggers (examples):

Loose matching guidance:

Skip proposal for:

Workflow

  1. Review openspec/project.md, openspec list, and openspec list --specs to understand current context.
  2. Choose a unique verb-led change-id and scaffold proposal.md, tasks.md, optional design.md, and spec deltas under openspec/changes/<id>/.
  3. Draft spec deltas using ## ADDED|MODIFIED|REMOVED Requirements with at least one #### Scenario: per requirement.
  4. Run openspec validate <id> --strict and resolve any issues before sharing the proposal.

Stage 2: Implementing Changes

Track these steps as TODOs and complete them one by one.

  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 in tasks.md is finished before updating statuses
  6. Update checklist - After all work is done, set every task to - [x] so the list reflects reality
  7. Approval gate - Do not start implementation until the proposal is reviewed and approved

Stage 3: Archiving Changes

After deployment, create separate PR to:

Before Any Task

Context Checklist:

Before Creating Specs:

Search Guidance

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-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)

# 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

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; see criteria)
│   │   └── 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/[change-id]/ (kebab-case, verb-led, unique)

  2. Write proposal.md: ```markdown

    Change: [Brief description of change]

Why

[1-2 sentences on problem/opportunity]

What Changes

Impact

  1. Create spec deltas: specs/[capability]/spec.md ```markdown

    ADDED Requirements

    Requirement: New Feature

    The system SHALL provide…

Scenario: Success case

MODIFIED Requirements

Requirement: Existing Feature

[Complete modified requirement]

REMOVED Requirements

Requirement: Old Feature

Reason: [Why removing] Migration: [How to handle]

If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.

4. **Create tasks.md:**
```markdown
## 1. Implementation
- [ ] 1.1 Create database schema
- [ ] 1.2 Implement API endpoint
- [ ] 1.3 Add frontend component
- [ ] 1.4 Write tests
  1. Create design.md when needed: Create design.md if any of the following apply; otherwise omit it:
    • Cross-cutting change (multiple services/modules) or a new architectural pattern
    • New external dependency or significant data model changes
    • Security, performance, or migration complexity
    • Ambiguity that benefits from technical decisions before coding

Minimal design.md skeleton:

## Context
[Background, constraints, stakeholders]

## Goals / Non-Goals
- Goals: [...]
- Non-Goals: [...]

## Decisions
- Decision: [What and why]
- Alternatives considered: [Options + rationale]

## Risks / Trade-offs
- [Risk] → Mitigation

## Migration Plan
[Steps, rollback]

## Open Questions
- [...]

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.

Requirement Wording

Delta Operations

Headers matched with trim(header) - whitespace ignored.

When to use ADDED vs MODIFIED

Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.

Authoring a MODIFIED requirement correctly: 1) Locate the existing requirement in openspec/specs/<capability>/spec.md. 2) Copy the entire requirement block (from ### Requirement: ... through its scenarios). 3) Paste it under ## MODIFIED Requirements and edit to reflect the new behavior. 4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one #### Scenario:.

Example for RENAMED:

## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`

Troubleshooting

Common Errors

“Change must have at least one delta”

“Requirement must have at least one scenario”

Silent scenario parsing failures

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

Happy Path Script

# 1) Explore current state
openspec spec list --long
openspec list
# Optional full-text search:
# rg -n "Requirement:|Scenario:" openspec/specs
# rg -n "^#|Requirement:" openspec/changes

# 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 (example)
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

Multi-Capability Example

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

auth/spec.md

## ADDED Requirements
### Requirement: Two-Factor Authentication
...

notifications/spec.md

## ADDED Requirements
### Requirement: OTP Email Notification
...

Best Practices

Simplicity First

Complexity Triggers

Only add complexity with:

Clear References

Capability Naming

Change ID Naming

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

File Purposes

CLI Essentials

openspec list              # What's in progress?
openspec show [item]       # View details
openspec validate --strict # Is it correct?
openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)

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