OpenSpec

OpenSpec — Spec-Driven Development

OpenSpec structures AI-assisted development into trackable changes with artifacts (proposal, specs, design, tasks) that guide implementation.

Setup

# Install globally npm install -g @fission-ai/openspec@latest # Initialize in a project cd /path/to/project openspec init --tools claude # Update after CLI upgrade openspec update

Core Workflow

Each change follows: new → plan → apply → verify → archive

1. Start a Change

# Create change folder with default schema openspec new change <name> # With specific schema openspec new change <name> --schema tdd-driven

2. Plan (Create Artifacts)

Use the CLI instructions command to get enriched prompts for each artifact: # Get instructions for next artifact openspec instructions --change <name> --json # Check progress openspec status --change <name> --json Artifact sequence (spec-driven schema): proposal.md — Why and what (intent, scope, approach) specs/ — Requirements + scenarios (Given/When/Then) design.md — Technical approach and architecture decisions tasks.md — Implementation checklist with checkboxes

3. Implement

Read tasks.md and work through items, marking [x] as complete.

4. Verify

openspec validate --change <name> --json Checks completeness, correctness, and coherence.

5. Archive

openspec archive <name> --yes Merges delta specs into main openspec/specs/ and moves change to archive.

Agent Workflow (How to Use as an AI Agent)

When the user asks to build/migrate/refactor something with OpenSpec: Check project state: openspec list --json # Active changes openspec list --specs --json # Current specs openspec schemas --json # Available schemas Create the change: openspec new change <name> [--schema <schema>] For each artifact, get instructions and create the file: openspec instructions <artifact> --change <name> --json openspec status --change <name> --json Then write the artifact file to openspec/changes/<name>/. Implement tasks from tasks.md. Validate and archive: openspec validate <name> --json openspec archive <name> --yes

CLI Quick Reference

CommandPurposeopenspec list [--specs] [--json]List changes or specsopenspec show <name> [--json]Show change/spec detailsopenspec status --change <name> [--json]Artifact completion statusopenspec instructions [artifact] --change <name> [--json]Get enriched creation instructionsopenspec validate [name] [--all] [--json]Validate changes/specsopenspec archive <name> [--yes]Archive completed changeopenspec schemas [--json]List available schemasopenspec templates [--json]Show template pathsopenspec configView/modify settings Always use --json for programmatic/agent use.

Custom Schemas

Schemas define artifact sequences. Create custom ones for different workflows: # Fork built-in schema openspec schema fork spec-driven my-workflow # Create from scratch openspec schema init my-workflow # Validate openspec schema validate my-workflow Schema files live in openspec/schemas/<name>/schema.yaml with templates in templates/. For schema structure details, see references/schemas.md.

Project Structure

project/ ├── openspec/ │ ├── config.yaml # Project config (default schema, context, rules) │ ├── specs/ # Source of truth — current system behavior │ ├── changes/ # Active changes (one folder each) │ │ └── <change-name>/ │ │ ├── .openspec.yaml │ │ ├── proposal.md │ │ ├── specs/ # Delta specs (what's changing) │ │ ├── design.md │ │ └── tasks.md │ └── schemas/ # Custom schemas └── .claude/skills/ # Auto-generated Claude integration

Spec Format

• Specs use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY) with Given/When/Then scenarios:
• ### Requirement: User Authentication
• The system SHALL issue a JWT token upon successful login.
• #### Scenario: Valid credentials
• GIVEN a user with valid credentials
• WHEN the user submits login form
• THEN a JWT token is returned

Delta Specs

Changes don't rewrite specs — they describe deltas (ADDED/MODIFIED/REMOVED) that merge into main specs on archive.

Config

openspec/config.yaml sets defaults: schema: spec-driven # or tdd-driven, rapid, custom context: | Tech stack: TypeScript, React, Node.js Testing: Jest rules: proposal: - Include rollback plan specs: - Use Given/When/Then format