OpenSpec

Write better code with less back-and-forth. OpenSpec is an AI-powered, spec-driven development workflow that brings the structure of formal specification to your coding assistant workflow.

Instead of iterating endlessly on what to build, OpenSpec shifts the conversation to "before we code, let's agree on what we're building."

---

Why OpenSpec?

AI coding assistants are powerful, but they often miss the mark because they lack context, make incorrect assumptions, or skip important edge cases. OpenSpec solves this by creating a shared understanding between you and your AI before any code is written.

Core Problem

• AI writes code based on incomplete understanding
• You spend time correcting and guiding
• Missed edge cases cause rework
• No record of why decisions were made

OpenSpec Approach

• Shared understanding first — Define what you're building together
• Structured exploration — Investigate the problem space before coding
• Documented decisions — Keep a record of intent and reasoning
• Iterative refinement — Evolve specs as you learn

---

Quick Start

1. Install

npm install -g @fission-ai/openspec

2. Initialize

openspec init

3. Work with your AI

/opsx:propose add-dark-mode   # Create a change with all artifacts
/opsx:apply                    # Implement tasks
/opsx:archive                  # Finalize and merge specs

---

Key Concepts

Specs

The source of truth for how your system works. Specs are organized by domain and describe behavior using requirements and scenarios (Given/When/Then format).

Changes

Proposed modifications to your system. Each change is self-contained with:

• proposal.md — Why you're doing this
• specs/ — What you're adding/changing
• design.md — How you'll implement it
• tasks.md — Implementation checklist

Delta Specs

Changes don't modify main specs directly. Instead, they use delta specs that show what was ADDED, MODIFIED, or REMOVED. When archived, these are merged into the main specs.

---

Commands

Command	Purpose
/opsx:propose	Create change + planning artifacts
/opsx:explore	Think through ideas before committing
/opsx:apply	Implement tasks
/opsx:archive	Archive completed change

---

Supported Tools

OpenSpec works with Claude Code, Cursor, Windsurf, GitHub Copilot, Amazon Q, Trae, and many more.

Getting Started

This guide explains how OpenSpec works after you've installed and initialized it.

How It Works

OpenSpec helps you and your AI coding assistant agree on what to build before any code is written.

Default quick path (core profile):

/opsx:propose ──► /opsx:apply ──► /opsx:archive

Expanded path (custom workflow selection):

/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

The default global profile is core, which includes propose, explore, apply, and archive. You can enable the expanded workflow commands with openspec config profile and then openspec update.

What OpenSpec Creates

openspec/
├── specs/              # Source of truth (your system's behavior)
│   └── <domain>/
│       └── spec.md
├── changes/            # Proposed updates (one folder per change)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs (what's changing)
└── config.yaml         # Project configuration (optional)

Two key directories:

• specs/ — The source of truth. These specs describe how your system currently behaves.
• changes/ — Proposed modifications. Each change gets its own folder with all related artifacts. When a change is complete, its specs merge into the main specs/ directory.

Understanding Artifacts

Artifact	Purpose
proposal.md	The "why" and "what" — captures intent, scope, and approach
specs/	Delta specs showing ADDED/MODIFIED/REMOVED requirements
design.md	The "how" — technical approach and architecture decisions
tasks.md	Implementation checklist with checkboxes

How Delta Specs Work

Delta specs are the key concept in OpenSpec. They show what's changing relative to your current specs. When you archive a change:

1. ADDED requirements are appended to the main spec
2. MODIFIED requirements replace the existing version
3. REMOVED requirements are deleted from the main spec

Example: Your First Change

Let's walk through adding dark mode to an application.

1. Start the Change

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md
     ✓ specs/ui/spec.md
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

2. Implement

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties
     All tasks complete!

3. Archive

You: /opsx:archive

AI:  ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/
     Done!

Verifying and Reviewing

openspec list          # List active changes
openspec show <name>   # View change details
openspec validate      # Validate spec formatting
openspec view          # Interactive dashboard

Commands

This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface (e.g., Claude Code, Cursor, Windsurf).

Quick Reference

Default Quick Path (core profile)

Command	Purpose
/opsx:propose	Create a change and generate planning artifacts in one step
/opsx:explore	Think through ideas before committing to a change
/opsx:apply	Implement tasks from the change
/opsx:archive	Archive a completed change

Expanded Workflow Commands

Command	Purpose
/opsx:new	Start a new change scaffold
/opsx:continue	Create the next artifact based on dependencies
/opsx:ff	Fast-forward: create all planning artifacts at once
/opsx:verify	Validate implementation matches artifacts
/opsx:sync	Merge delta specs into main specs (optional)
/opsx:bulk-archive	Archive multiple changes at once
/opsx:onboard	Guided tutorial through the complete workflow

Command Reference

/opsx:propose

Create a new change and generate planning artifacts in one step. This is the default start command in the core profile.

Syntax: /opsx:propose [change-name-or-description]

What it does:

• Creates openspec/changes/<change-name>/
• Generates artifacts needed before implementation (for spec-driven: proposal, specs, design, tasks)
• Stops when the change is ready for /opsx:apply

/opsx:explore

Think through ideas, investigate problems, and clarify requirements before committing to a change. Opens an exploratory conversation with no structure required. Investigates the codebase to answer questions. Can transition to /opsx:propose or /opsx:new when insights crystallize.

/opsx:new

Start a new change scaffold. Creates the change folder and waits for you to generate artifacts with /opsx:continue or /opsx:ff. Part of the expanded workflow set (not in default core profile).

/opsx:continue

Create the next artifact in the dependency chain. Creates one artifact at a time for incremental progress. Queries the artifact dependency graph, shows which artifacts are ready vs blocked, reads dependency files for context.

/opsx:ff

Fast-forward through artifact creation. Creates all planning artifacts at once.

/opsx:apply

Implement tasks from the change. Works through the task list, writing code and checking off items. Reads tasks.md and identifies incomplete tasks, works through them one by one, marks tasks complete with checkboxes [x].

/opsx:verify

Validate that implementation matches your change artifacts. Checks three dimensions:

Dimension	What it validates
Completeness	All tasks done, all requirements implemented, scenarios covered
Correctness	Implementation matches spec intent, edge cases handled
Coherence	Design decisions reflected in code, patterns consistent

/opsx:archive

Archive a completed change. Finalizes the change and moves it to the archive folder. Checks artifact completion, checks task completion (warns if incomplete), offers to sync delta specs, moves change folder to openspec/changes/archive/YYYY-MM-DD-<name>/.

/opsx:onboard

Guided onboarding through the complete OpenSpec workflow. An interactive tutorial using your actual codebase. Walks through: Welcome → Find opportunity → Create change → Write proposal → Create specs → Write design → Create tasks → Implement → Verify → Archive → Summary.

Command Syntax by AI Tool

Tool	Syntax
Claude Code	/opsx:propose, /opsx:apply
Cursor	/opsx-propose, /opsx-apply
Windsurf	/opsx-propose, /opsx-apply
Trae	Skill-based (e.g., /openspec-propose)

CLI Reference

The OpenSpec CLI (openspec) provides terminal commands for project setup, validation, status inspection, and management.

Summary

Category	Commands	Purpose
Setup	init, update	Initialize and update OpenSpec in your project
Browsing	list, view, show	Explore changes and specs
Validation	validate	Check changes and specs for issues
Lifecycle	archive	Finalize completed changes
Workflow	status, instructions, templates, schemas	Artifact-driven workflow support
Schemas	schema init/fork/validate/which	Create and manage custom workflows
Config	config	View and modify settings
Utility	feedback, completion	Feedback and shell integration

Setup Commands

openspec init

openspec init [path] [options]

Options: --tools <list> (configure AI tools), --force (auto-cleanup legacy), --profile <profile> (override global profile)

Supported tool IDs: claude, cursor, windsurf, github-copilot, amazon-q, trae, gemini, codex, continue, kiro, and many more.

openspec update

Update OpenSpec instruction files after upgrading the CLI.

Browsing Commands

openspec list

Options: --specs, --changes, --sort <order>, --json

openspec view

Display an interactive dashboard for exploring specs and changes.

openspec show

Options: --type <type>, --json, --deltas-only

Validation Commands

openspec validate

Options: --all, --changes, --specs, --strict, --json, --concurrency <n>

Workflow Commands

openspec status

openspec status [options]

Options: --change <id>, --schema <name>, --json

Display artifact completion status for a change. JSON output is used by AI agents to determine next steps.

openspec instructions

Get enriched instructions for creating an artifact or applying tasks. Used by AI agents to understand what to create next.

openspec schemas

List available workflow schemas with their descriptions and artifact flows.

Schema Commands

openspec schema init <name>

Create a new project-local schema.

openspec schema fork <source> [name]

Copy an existing schema to your project for customization.

openspec schema validate [name]

Validate a schema's structure and templates.

openspec schema which [name]

Show where a schema resolves from (useful for debugging precedence).

Schema precedence: Project → User → Package (built-in)

Configuration Commands

openspec config

Subcommands: path, list, get <key>, set <key> <value>, unset <key>, reset, edit, profile [preset]

# Configure profile with action-based wizard
openspec config profile

# Fast preset: switch to core workflows
openspec config profile core

Utility Commands

openspec feedback <message>

Submit feedback about OpenSpec via GitHub issue.

openspec completion <subcommand> [shell]

Subcommands: generate, install, uninstall. Supported shells: bash, zsh, fish, powershell

Environment Variables

Variable	Description
OPENSPEC_TELEMETRY	Set to 0 to disable telemetry
DO_NOT_TRACK	Set to 1 to disable telemetry
OPENSPEC_CONCURRENCY	Default concurrency for bulk validation (default: 6)
NO_COLOR	Disable color output when set

OPSX Workflow

OPSX is now the standard workflow for OpenSpec. It's a fluid, iterative workflow for OpenSpec changes. No more rigid phases — just actions you can take anytime.

Why This Exists

The legacy OpenSpec workflow works, but it's locked down:

• Instructions are hardcoded — buried in TypeScript, you can't change them
• All-or-nothing — one big command creates everything, can't test individual pieces
• Fixed structure — same workflow for everyone, no customization
• Black box — when AI output is bad, you can't tweak the prompts

OPSX opens it up. Now anyone can:

1. Experiment with instructions — edit a template, see if the AI does better
2. Test granularly — validate each artifact's instructions independently
3. Customize workflows — define your own artifacts and dependencies
4. Iterate quickly — change a template, test immediately, no rebuild

The User Experience

The problem with linear workflows: You're "in planning phase", then "in implementation phase", then "done". But real work doesn't work that way.

OPSX approach:

• Actions, not phases — create, implement, update, archive — do any of them anytime
• Dependencies are enablers — they show what's possible, not what's required next

  proposal ──→ specs ──→ design ──→ tasks ──→ implement

Commands

Command	What it does
/opsx:propose	Create a change and generate planning artifacts in one step (default quick path)
/opsx:explore	Think through ideas, investigate problems, clarify requirements
/opsx:new	Start a new change scaffold (expanded workflow)
/opsx:continue	Create the next artifact (expanded workflow)
/opsx:ff	Fast-forward planning artifacts (expanded workflow)
/opsx:apply	Implement tasks, updating artifacts as needed
/opsx:verify	Validate implementation against artifacts (expanded workflow)
/opsx:sync	Sync delta specs to main (expanded workflow, optional)
/opsx:archive	Archive when done
/opsx:bulk-archive	Archive multiple completed changes (expanded workflow)
/opsx:onboard	Guided walkthrough of an end-to-end change (expanded workflow)

When to Update vs. Start Fresh

Update the Existing Change When:

• Same intent, refined execution
• Scope narrows (MVP first approach)
• Learning-driven corrections (codebase isn't structured as expected)

Start a New Change When:

• Intent fundamentally changed
• Scope exploded (essentially different work)
• Original is completable and new work stands alone

The Principle

Update preserves context. New change provides clarity.

Choose update when the history of your thinking is valuable. Choose new when starting fresh would be clearer than patching.

What's Different?

	Legacy	OPSX
Structure	One big proposal document	Discrete artifacts with dependencies
Workflow	Linear phases: plan → implement → archive	Fluid actions — do anything anytime
Iteration	Awkward to go back	Update artifacts as you learn
Customization	Fixed structure	Schema-driven (define your own artifacts)

Architecture Deep Dive

Dependency Graph Model

Artifacts form a directed acyclic graph (DAG). Dependencies are enablers, not gates:

                              proposal
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
                 specs                       design
              (requires:                  (requires:
               proposal)                   proposal)
                    │                           │
                    └─────────────┬─────────────┘
                                  ▼
                               tasks
                          (requires:
                          specs, design)
                                  │
                                  ▼
                          ┌──────────────┐
                          │  APPLY PHASE │
                          └──────────────┘

State Transitions

   BLOCKED ────────────────► READY ────────────────► DONE
      │                        │                       │
   Missing                  All deps               File exists
   dependencies             are DONE               on filesystem

Summary

Aspect	Legacy	OPSX
Templates	Hardcoded TypeScript	External YAML + Markdown
Dependencies	None (all at once)	DAG with topological sort
State	Phase-based mental model	Filesystem existence
Customization	Edit source, rebuild	Create schema.yaml
Iteration	Phase-locked	Fluid, edit anything
Editor Support	Tool-specific configurator/adapters	Single skills directory

Workflows

This guide covers common patterns and when to use each OpenSpec command.

Two Workflow Profiles

Core Profile (Default)

The fastest end-to-end path. Four commands cover the full lifecycle:

/opsx:propose ──► /opsx:apply ──► /opsx:archive

Use when: You know what you want to build. You want the fastest path from idea to implemented code.

Expanded Profile (Custom Workflow Selection)

Granular control over each artifact. More commands, more flexibility:

/opsx:new ──► /opsx:continue (or /opsx:ff) ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Use when: You want to review each artifact before creating the next. You're exploring or the scope is unclear.

Choosing the Right Path

Start with /opsx:explore when:

• Requirements are unclear
• You're evaluating multiple approaches
• You need to investigate the codebase first
• The change is large or complex

Use /opsx:propose or /opsx:ff when:

• You have a clear picture of what you're building
• Scope is well-defined
• You want the fastest path

Use /opsx:continue when:

• You want to review each artifact
• The change is complex and you want control
• You may need to adjust earlier artifacts

Multi-Change Management

You can work on multiple changes in parallel. Use change names to direct commands:

/opsx:apply add-auth      # Apply auth change
/opsx:apply fix-ui-bug     # Switch to different change

Use openspec list to see all active changes and their status.

Tips

• Use /opsx:explore before /opsx:propose for complex changes
• During /opsx:apply, if specs are wrong — update them and continue
• Run /opsx:verify before /opsx:archive to catch issues
• Use openspec status to check progress anytime

Concepts

This document explains the core concepts that power OpenSpec.

Specs

Specs are the source of truth for how your system works. They're organized by domain and written in a structured format.

Structure

Each spec file covers a domain and contains:

• Requirements — What the system must do (using MUST/SHALL keywords)
• Scenarios — Concrete examples using Given/When/Then format

Requirements Keywords

• MUST — Absolute requirement (system failure if not met)
• SHALL — Important requirement (should work but not fatal)
• Should — Recommendation (nice to have)
• May — Optional feature

Scenario Format

#### Scenario: [name]
- GIVEN [precondition]
- WHEN [action]
- THEN [expected outcome]
- AND [additional outcome]

Changes

A change is a proposed modification to your system. It's a self-contained folder that contains everything about that change:

• What you're doing (proposal)
• What you're adding/changing (delta specs)
• How you'll do it (design)
• What needs to be done (tasks)

Change Lifecycle

  created ──► in-progress ──► completed ──► archived
      │            │              │             │
  /opsx:new    /opsx:apply   /opsx:verify  /opsx:archive

Delta Specs

Changes don't modify main specs directly. Instead, they use delta specs that show:

• ADDED — New requirements being introduced
• MODIFIED — Existing requirements being changed
• REMOVED — Requirements being deleted

When archived, delta specs are merged into the main specs.

Schemas

Schemas define the structure of a change — what artifacts exist and how they depend on each other.

The default schema is spec-driven: proposal → specs → design → tasks → implement

You can create custom schemas for different workflows.

Artifacts

Artifact	File	Purpose
Proposal	proposal.md	Why — intent, scope, approach
Specs	specs/**/*.md	What — delta requirements
Design	design.md	How — technical approach
Tasks	tasks.md	Do — implementation checklist

Project Configuration

Project config (openspec/config.yaml) lets you customize how artifacts are generated:

• Schema — Default schema for new changes
• Context — Project-specific info injected into all artifacts
• Rules — Per-artifact instructions (e.g., "use Given/When/Then for specs")

Customization

OpenSpec is designed to be customized. You can modify templates, create custom schemas, and configure project-specific rules.

Project Configuration

Create or edit openspec/config.yaml in your project root:

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
    - Cover happy path and edge cases
  design:
    - Include sequence diagrams for complex flows
    - Document error handling approach

Custom Schemas

Schemas define what artifacts exist and their dependencies. You can create custom schemas for different workflows.

Create a Schema

# Interactive creation
openspec schema init my-workflow

# Or fork an existing one
openspec schema fork spec-driven my-workflow

Schema Structure

openspec/schemas/my-workflow/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── specs.md
    ├── design.md
    └── tasks.md

schema.yaml Format

name: my-workflow
description: Custom workflow for rapid iteration
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []
  - id: tasks
    generates: tasks.md
    requires: [proposal]

Template Variables

Templates can use these variables that get replaced at generation time:

• {{changeName}} — Name of the change
• {{date}} — Current date
• {{author}} — User running the command
• {{schema}} — Schema name

Context Injection

Context from config.yaml is prepended to every artifact's instructions, wrapped in <context>...</context> tags. This helps AI understand your project's conventions.

Per-Artifact Rules

Rules in config.yaml are injected per-artifact, wrapped in <rules>...</rules> tags. They appear after context, before the template.

Multi-Language Support

OpenSpec supports multiple natural languages for specs, commands, and documentation.

Spec Languages

Specs can be written in any language. The AI coding assistant will work with your specs in whatever language they're written.

Supported Languages

• English (default)
• Chinese (中文)
• Japanese (日本語)
• Korean (한국어)
• And any other language your AI tool supports

Configuration

Set your preferred language in openspec/config.yaml:

specLanguage: zh-CN  # or en, ja, ko, etc.

When set, artifact templates and validation messages will use the specified language.

Command Localization

Slash commands are currently English-only (/opsx:propose, /opsx:apply, etc.), regardless of spec language. This is intentional to maintain consistency across teams using different languages.

Best Practices

• Be consistent — pick one language per project
• Consider your team — choose a language everyone reads
• Spec language is independent of code language

Supported Tools

OpenSpec works with a growing list of AI coding assistants and tools.

Full Support (Skills + Commands)

Tool	Skills	Commands	Notes
Claude Code	✓	✓	Recommended. Full integration.
Cursor	✓	✓	Full support via skills + commands
Windsurf	✓	✓	Full support via skills + commands

Skills Support

Tool	Skills	Notes
GitHub Copilot	✓	IDE only (VS Code, JetBrains, Visual Studio). CLI not supported.
Amazon Q	✓	Skills support
Trae	✓	Skill-based invocations (e.g., /openspec-propose)
Continue	✓	OpenAI, Claude, Gemini, local models
Kiro	✓	AI coding assistant
Codex	✓	OpenAI's coding assistant
Gemini	✓	Google's AI assistant

Installation

When you run openspec init, it auto-detects your installed tools and generates the appropriate configuration files.

# Or specify tools explicitly
openspec init --tools claude,cursor,windsurf

Command Syntax by Tool

Tool	Syntax
Claude Code	/opsx:propose, /opsx:apply
Cursor	/opsx-propose, /opsx-apply
Windsurf	/opsx-propose, /opsx-apply
Trae	Skill-based invocations