Skip to content

Validation and Specification Lifecycle

Specification validation

JSON Schema validation

Every specification must be validated:

# Validate a single change
openspec validate add-barcode-scan --strict

# Validate all changes
openspec validate --changes

# Validate all specs
openspec validate --specs

# Validate everything
openspec validate --all

Validation rules

For specs (current truth)

  • ✅ Must contain ## Purpose
  • ✅ Must contain ## Requirements
  • ✅ Every requirement must have a ### Requirement: header
  • ✅ Every requirement must contain SHALL or MUST
  • ✅ Every requirement must have ≥1 #### Scenario:
  • ✅ No duplicate requirement headers

For changes (delta specs)

  • ✅ Must contain at least one delta operation (ADDED/MODIFIED/REMOVED/RENAMED)
  • ✅ ADDED/MODIFIED requirements must include full text
  • ✅ ADDED/MODIFIED must contain SHALL/MUST
  • ✅ ADDED/MODIFIED must have ≥1 scenario
  • ✅ REMOVED contains only names (no content)
  • ✅ RENAMED must have FROM and TO
  • ✅ No duplicates between sections

Sample validation error

✗ Validation failed for add-barcode-scan

warehouse/spec.md:
  - ERROR at ADDED[0]: Requirement "Barcode scanning"
    missing SHALL/MUST keyword
    → Add: "The system SHALL allow scanning..."

  - WARNING at MODIFIED[0]: Requirement "Automatic numbering"
    scenario count changed from 1 to 2
    → Consider if additional scenario is necessary

Specification lifecycle

1. Create a change proposal

sequenceDiagram
    participant Dev as Developer
    participant Spec as Specification
    participant Review as Review
    participant Impl as Implementation

    Dev->>Spec: Create changes/add-feature/
    Dev->>Spec: Write proposal.md
    Dev->>Spec: Write tasks.md
    Dev->>Spec: Write delta specs
    Dev->>Spec: openspec validate --strict

    Spec->>Review: Submit for review
    Review-->>Dev: Feedback
    Dev->>Spec: Fix per feedback

    Review->>Impl: Approved
    Impl->>Spec: Implement per spec
    Impl->>Spec: openspec archive add-feature

2. Archive a completed change

After implementation and validation:

# Verify implementation matches the spec
openspec validate add-barcode-scan --strict

# Archive - applies delta to specs/
openspec archive add-barcode-scan --yes

# Result:
# - specs/warehouse/spec.md updated
# - changes/add-barcode-scan/ moved to archive/

CLI commands

# Initialize OpenSpec in the project
openspec init

# List active changes
openspec list

# List specs
openspec list --specs

# Show detail
openspec show add-barcode-scan

# Validation
openspec validate add-barcode-scan --strict

# Archive
openspec archive add-barcode-scan --yes

# Update instructions
openspec update

AI Agent commands

Slash commands available for AI assistants:

  • /openspec:proposal - Create a new change proposal
  • /openspec:apply - Implement an approved proposal
  • /openspec:archive - Archive a completed change

➡️ Continue to Iterative development for the ongoing development workflow.