OpenSpec User Guide

OpenSpec is an AI-native command-line tool for spec-driven development. It gives your AI coding assistant a structured, reviewable workflow: instead of letting the agent improvise a large change in one shot, you have it write a short proposal, capture the intended behavior as specs, optionally record a technical design, break the work into a tasks checklist, implement against that plan, and finally archive the change so your living specifications stay in sync with the code that actually shipped.

Everything OpenSpec manages is plain Markdown in an openspec/ directory inside your project. There is no database, no server, and no account. The CLI scaffolds files, validates them, tracks progress, and installs ready-made workflow instructions ("skills" and slash commands) for more than two dozen AI coding tools — Claude Code, Cursor, Windsurf, Codex, GitHub Copilot, Gemini CLI, and many others.

Note

OpenSpec is published on npm as @fission-ai/openspec and exposes a single executable: openspec. It requires Node.js 20.19.0 or newer.

Table of Contents

1. Quick Start
2. Installation
3. Core Concepts
4. The Change Workflow
5. Everyday Commands
6. Working With Your AI Assistant
7. Validating Changes and Specs
8. Customizing Workflows With Schemas
9. Coordinating Across Repos (Beta)
10. Shell Completions
11. Configuration & Privacy
12. Common Workflows (Recipes)
13. Troubleshooting
14. FAQ
15. Command Reference

1. Quick Start

Get OpenSpec running in an existing project in under two minutes.

# 1. Run the initializer from your project root
npx @fission-ai/openspec@latest init

# 2. Pick your AI tools when prompted (e.g. Claude Code, Cursor)
#    OpenSpec creates openspec/ and installs workflow skills/commands.

# 3. Ask your AI assistant to propose a change, e.g. in Claude Code:
#    "Use OpenSpec to propose adding password reset to user auth."

# 4. Inspect what the agent scaffolded
openspec list            # active change proposals
openspec status --change add-password-reset

# 5. After the work is implemented and merged, archive it
openspec archive add-password-reset

Created change 'add-password-reset' at openspec/changes/add-password-reset/
Schema: spec-driven

Tip

You don't drive the proposal/spec writing by hand — that's the AI assistant's job. OpenSpec's CLI exists to scaffold, validate, show status, and archive. The agent reads OpenSpec's installed instructions and fills in the Markdown.

2. Installation

Requirements

Important

A post-install script runs automatically when the package is installed (scripts/postinstall.js). This is expected behavior and prints setup hints; it does not phone home with project data.

Install methods

Run without installing (npx)

Best for trying OpenSpec or for CI:

npx @fission-ai/openspec@latest init

Global install (npm)

Best for daily use, gives you the openspec command everywhere:

npm install -g @fission-ai/openspec
openspec --version

Global install (pnpm)

pnpm add -g @fission-ai/openspec
openspec --version

Verify the install:

openspec --version

1.4.1

Initialize a project

Run init from the root of the project you want to manage:

openspec init

In interactive mode you'll see an animated welcome screen and a searchable multi-select of supported AI tools. OpenSpec pre-selects tools it detects (for example, if a .cursor/ or .claude/ directory already exists) and lets you add more. It then:

1. Creates openspec/ with specs/, changes/, and changes/archive/ subdirectories.
2. Writes a project config (openspec/config.yaml).
3. Generates workflow skills and slash commands into each selected tool's directory (e.g. .claude/, .cursor/).

To run non-interactively (CI, scripts, or when you already know your tools), pass --tools:

# Set up Claude Code and Cursor without prompts
openspec init --tools claude,cursor

# Set up every supported tool
openspec init --tools all

# Create the openspec/ structure but skip tool integration
openspec init --tools none

Note

Running init again on a project that already has openspec/ runs in extend mode: it preserves your existing specs and changes, ensures the directory structure is present, and refreshes tool integrations. It also detects and offers to clean up legacy files from older OpenSpec versions (use --force to clean up without prompting).

3. Core Concepts

OpenSpec is built on a small number of ideas. Understanding them makes every command obvious.

Specs : Markdown files under openspec/specs/<capability>/spec.md that describe what the system does today — the current, deployed behavior. Specs are the living source of truth. They are written with normative language (SHALL/MUST) and concrete scenarios.

Changes : Proposals for what should change, each living in its own directory under openspec/changes/<change-name>/. A change bundles a proposal, future-state spec deltas, an optional design doc, and a task checklist. Changes are proposed, reviewed, implemented, then archived.

Capabilities : The unit of organization for specs. Each capability is a single, focused responsibility named with a verb-noun pattern (user-auth, payment-capture, data-export). If you need the word "AND" to describe one, split it.

Artifacts : The individual documents that make up a change. In the default spec-driven workflow the artifacts are, in dependency order: proposal → specs → design → tasks. Each artifact has a template and instructions that your AI assistant follows.

Schema : A named workflow definition (a schema.yaml) that lists which artifacts a change needs and how they depend on each other. The built-in default is spec-driven. You can fork it or author your own.

Skills & slash commands : The instruction files OpenSpec installs into your AI tool. Skills (e.g. openspec-propose, openspec-apply-change) and /opsx-* slash commands tell the agent exactly how to drive the OpenSpec workflow.

Here is the directory layout init creates and your AI fills in:

openspec/
├── config.yaml             # Project config (default schema, etc.)
├── specs/                  # Current truth — what IS built
│   └── user-auth/
│       └── spec.md
└── changes/                # Proposals — what we're CHANGING
    ├── add-password-reset/
    │   ├── proposal.md     # Why + what + impact
    │   ├── design.md       # Technical decisions (optional)
    │   ├── tasks.md        # Implementation checklist
    │   └── specs/          # Future-state spec deltas
    │       └── user-auth/
    │           └── spec.md
    └── archive/            # Completed, dated changes
        └── 2026-06-01-add-login/

Tip

A clean mental model: specs answer "what and why," code answers "how," and changes are the reviewable bridge between them.

4. The Change Workflow

The heart of OpenSpec is the lifecycle a change moves through. You usually trigger each step by asking your AI assistant, and use the CLI to inspect and finalize.

  Propose  ──►  Review  ──►  Implement  ──►  Archive
 (scaffold)   (you read)   (agent codes)   (specs sync)

  proposal.md ─► specs/ ─► design.md ─► tasks.md ─► (code) ─► archive

Step 1 — Propose

Ask your assistant to create a change. Under the hood it runs openspec new change <name> (or uses the openspec-new-change skill) to scaffold the directory, then writes proposal.md. The proposal states Why the change is needed, What Changes, which Capabilities are affected, and the Impact.

# What the agent runs (you can run it too):
openspec new change add-password-reset --description "Let users reset a forgotten password"

Created change 'add-password-reset' at openspec/changes/add-password-reset/
Schema: spec-driven

Step 2 — Build out the artifacts

Guided by the schema, the agent fills in the remaining artifacts in dependency order: the specs (future-state behavior, written as delta operations), an optional design doc for non-trivial changes, and a tasks checklist. You can watch this progress at any time:

openspec status --change add-password-reset

Change: add-password-reset
Schema: spec-driven
Progress: 2/4 artifacts complete

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)

The indicators mean: [x] done, [ ] ready to write, [-] blocked by an unmet dependency.

Step 3 — Review

Read the proposal and specs yourself before any code is written. This is the whole point — you approve intent on a one-page proposal instead of a 2,000-line diff.

openspec show add-password-reset          # render the change
openspec validate add-password-reset --strict

Step 4 — Implement

Once you approve, the agent works through tasks.md, checking off items as it goes. Ask it to "apply the change" and it will read the apply instructions (openspec instructions apply --change ...) and the context files, then implement and tick boxes.

Step 5 — Archive

After the change is implemented, reviewed, and merged, archive it. Archiving folds the change's future-state spec deltas into your main specs/ (so the specs now describe the new reality) and moves the change into changes/archive/ with a date prefix.

openspec archive add-password-reset

Task status: 8/8 complete
Specs to update:
  user-auth: update
Totals: + 2, ~ 1, - 0, → 0
Specs updated successfully.
Change 'add-password-reset' archived as '2026-06-05-add-password-reset'.

Warning

Archiving validates the change and rebuilds the affected specs before writing anything. If validation fails, no files are changed. Fix the reported errors, or — only if you understand the risk — pass --no-validate to skip the checks (you'll be asked to confirm).

Tip

For changes that don't touch product behavior (tooling, CI, dependency bumps), use openspec archive <name> --skip-specs so OpenSpec archives the change without trying to update specs.

5. Everyday Commands

These are the commands you'll reach for most. All of them operate on the openspec/ directory in your current working directory.

List what's in flight

openspec list                 # active changes (default), most recent first
openspec list --specs         # list specs instead
openspec list --sort name     # alphabetical
openspec list --json          # machine-readable

add-password-reset      8/8 ✓
improve-search          3/12

Inspect a change or spec

show works for both changes and specs and prompts you to pick interactively if you omit the name:

openspec show                         # interactive picker
openspec show add-password-reset      # show a specific change
openspec show user-auth --type spec   # disambiguate when names collide
openspec show add-password-reset --json --deltas-only

Note

If a change and a spec share the same name, OpenSpec asks which you meant. Use --type change or --type spec to answer up front, which is also required in non-interactive contexts.

See the interactive dashboard

openspec view

view opens a scrollable, interactive overview of all your specs and changes in one place — handy for getting your bearings in a busy project.

Check artifact progress

openspec status --change improve-search
openspec status --change improve-search --json

If you run status with no --change and there are no active changes, OpenSpec tells you so calmly rather than erroring — "no changes" is a valid state.

6. Working With Your AI Assistant

OpenSpec's real value shows when your AI coding tool drives the workflow. During init (and openspec update), OpenSpec installs two kinds of integration into each selected tool:

• Skills — reusable instruction packs the agent can invoke, such as openspec-propose, openspec-new-change, openspec-continue-change, openspec-apply-change, openspec-archive-change, openspec-sync-specs, openspec-verify-change, and openspec-explore.
• Slash commands — quick /opsx-* entry points (for example /opsx-new, /opsx-apply, /opsx-archive) for tools that support slash commands.

The supported tools include: Amazon Q, Antigravity, Auggie, Bob, Claude Code, Cline, Codex, ForgeCode, CodeBuddy, Continue, CoStrict, Crush, Cursor, Factory Droid, Gemini CLI, GitHub Copilot, iFlow, Junie, Kilo Code, Kimi CLI, Kiro, Lingma, Mistral Vibe, OpenCode, Pi, Qoder, Qwen Code, RooCode, Trae, and Windsurf.

A typical agent session looks like this in plain language:

You: "Add rate limiting to the public API. Use OpenSpec." Agent: Reads existing specs, runs openspec new change add-api-rate-limiting, writes proposal.md, generates spec deltas, a design doc, and tasks.md. You: Review the proposal, request tweaks, approve. Agent: Works through tasks.md, implementing and checking off tasks. You: openspec archive add-api-rate-limiting after merge.

Keeping integrations current

When you upgrade the OpenSpec package, refresh the installed skills and commands so they match the new version:

openspec update

Updated OpenSpec instructions for: claude, cursor

update refreshes OpenSpec-managed instruction files in place. Use --force to rewrite them even if OpenSpec thinks they're already up to date.

Tip

The instruction files OpenSpec writes are 100% OpenSpec-managed. You don't need to hand-edit them — change behavior through schemas and config instead.

7. Validating Changes and Specs

Validation catches malformed specs before they're archived — missing scenarios, wrong heading depth, broken delta operations. Run it any time.

openspec validate add-password-reset        # validate one item
openspec validate --all                      # every change and spec
openspec validate --changes                  # all changes
openspec validate --specs                    # all specs
openspec validate add-password-reset --strict
openspec validate --all --json               # CI-friendly output

Bulk validation runs in parallel for speed. Tune the parallelism with --concurrency (defaults to the OPENSPEC_CONCURRENCY environment variable, or 6):

openspec validate --all --concurrency 12

Important

Specs use a strict structure. Each requirement is ### Requirement: <name>, must contain at least one scenario, and each scenario must use exactly four hashes (#### Scenario: ...). Using three hashes or a bullet makes the scenario invisible to OpenSpec and validation will flag it. Use SHALL/MUST for normative requirements.

Caution

When the AI writes spec deltas, MODIFIED Requirements must include the entire updated requirement block (description and all scenarios), not just the changed lines. Partial MODIFIED blocks lose detail when the change is archived. If you're only adding new behavior, use ADDED Requirements instead.

8. Customizing Workflows With Schemas

A schema defines the artifacts a change must produce and their dependencies. The built-in spec-driven schema produces proposal → specs → design → tasks. You can list, inspect, fork, and author schemas.

openspec schemas                       # list available schemas + their artifacts
openspec templates                     # show template files for the default schema
openspec templates --schema spec-driven --json
openspec schema which                  # show where a schema resolves from
openspec schema which --all            # all schemas and their sources
openspec schema validate spec-driven   # validate a schema's structure

Available schemas:

  spec-driven (project)
    Default OpenSpec workflow - proposal → specs → design → tasks
    Artifacts: proposal → specs → design → tasks

To customize, fork an existing schema into your project, then edit the copied schema.yaml and templates:

openspec schema fork spec-driven my-workflow

Or scaffold a brand-new project-local schema:

openspec schema init lightweight \
  --description "Proposal and tasks only" \
  --artifacts proposal,tasks \
  --default

Schemas resolve in priority order: project-local (in your repo) overrides a user override (in your home config dir) overrides the package default. The (project), (user override) labels in openspec schemas tell you which is winning.

Note

A change records which schema it uses in its metadata, so commands like status, instructions, and archive auto-detect the right schema. Pass --schema <name> only to override.

9. Coordinating Across Repos (Beta)

For teams planning work that spans multiple repositories, OpenSpec includes beta tooling for workspaces, context stores, and initiatives. These are optional — you can ignore them entirely for single-repo work.

Workspaces give you a local "view" that links several repos or folders together so an agent can plan a cross-repo change:

openspec workspace setup --name platform --link ./api --link ./web
openspec workspace list
openspec workspace open platform --agent claude
openspec workspace doctor              # check what resolves on this machine

Context stores are shared folders (optionally Git-backed) that hold durable, cross-repo coordination state:

openspec context-store setup my-store --init-git
openspec context-store list
openspec context-store doctor my-store

Initiatives coordinate a body of work across stores and let you link individual repo-local changes to a larger effort:

openspec initiative create migrate-billing --store my-store --title "Billing migration"
openspec initiative list
openspec new change add-invoice-export --initiative migrate-billing --store my-store

Warning

Workspaces, context stores, and initiatives are beta. The interfaces and behavior are still evolving, and some workspace lifecycle commands (apply, verify, archive) are intentionally deferred. Treat single-repo changes as the stable core.

10. Shell Completions

OpenSpec can install tab completion for your shell, including dynamic completion of change names, spec names, and schema names.

Supported shells: bash, zsh, fish, powershell.

# Install completions for your current shell (auto-detected)
openspec completion install

# Target a specific shell, with detailed output
openspec completion install zsh --verbose

# Print the script to stdout instead of installing (pipe it yourself)
openspec completion generate bash

# Remove completions
openspec completion uninstall zsh

Tip

After installing, open a new terminal (or source your shell rc file) for completions to take effect. Tab-completing openspec show <TAB> will then suggest your active change and spec names.

11. Configuration & Privacy

Global configuration

OpenSpec stores user-level settings in a global config.json. Inspect and edit it through the config command:

openspec config path           # show where the file lives
openspec config list           # show all current settings
openspec config get profile    # read one value
openspec config set profile custom
openspec config unset profile  # revert a key to default
openspec config edit           # open the file in $EDITOR
openspec config reset --all    # reset everything to defaults

The most useful settings:

The profile shortcut command opens an interactive picker (or accepts a preset):

openspec config profile          # interactive
openspec config profile custom   # set directly

Note

Config locations follow the XDG Base Directory spec: $XDG_CONFIG_HOME/openspec/ if set, otherwise ~/.config/openspec/ on macOS/Linux and %APPDATA%\openspec\ on Windows.

Telemetry and opting out

OpenSpec collects anonymous usage analytics: only the command name and OpenSpec version, tied to a random UUID. It never sends your arguments, file paths, file contents, or IP address. A one-time notice is shown on first run.

Opt out at any time with any of these:

export OPENSPEC_TELEMETRY=0     # OpenSpec-specific opt-out
export DO_NOT_TRACK=1           # honors the DO_NOT_TRACK standard

Telemetry is also automatically disabled in CI (CI=true).

Useful environment variables

12. Common Workflows (Recipes)

Start a small change end-to-end

openspec new change fix-empty-bio-crash --description "Handle empty bios safely"
openspec status --change fix-empty-bio-crash
# ...agent writes artifacts and implements...
openspec validate fix-empty-bio-crash --strict
openspec archive fix-empty-bio-crash

Archive a tooling-only change (no spec impact)

openspec archive bump-eslint --skip-specs --yes

Validate everything in CI

openspec validate --all --strict --json --concurrency 8

Exit code is non-zero if any item fails, so this gates your pipeline.

See only the machine-readable deltas of a change

openspec show add-password-reset --json --deltas-only

Inspect a single requirement of a spec

openspec show user-auth --type spec --json --requirement 2

Send feedback to the maintainers

openspec feedback "Loved the new schema fork flow" --body "Worked first try on a monorepo."

13. Troubleshooting

Error: No OpenSpec changes directory found. Run 'openspec init' first.

Cause: You ran a command (e.g. archive, list) in a directory that has no openspec/ folder. Solution: cd into your project root, or run openspec init to set up OpenSpec there. Prevention: Run OpenSpec commands from the project root where openspec/ lives.

Error: Change '<name>' not found.

Cause: The change directory doesn't exist under openspec/changes/, or the name is misspelled. Solution: Run openspec list to see valid change names, then retry. Omit the name to get an interactive picker. Prevention: Use tab completion (openspec completion install) to avoid typos.

Error: At least one tool must be selected

Cause: During interactive init you confirmed the tool picker without selecting anything. Solution: Re-run init and select at least one tool, or use --tools none to scaffold without tool integration, or --tools claude,cursor to pick explicitly.

Error: Invalid tool(s): <x>. Available values: all, none, claude, cursor, ...

Cause: --tools was given an unknown tool ID. Solution: Use a valid ID from the printed list, all, or none. IDs are lowercase (e.g. github-copilot, not GitHub Copilot).

Error: Cannot combine reserved values "all" or "none" with specific tool IDs.

Cause: You wrote something like --tools all,cursor. Solution: Use either a reserved value alone (--tools all) or a list of specific IDs (--tools claude,cursor).

Error: Insufficient permissions to write to <path>

Cause: init cannot write into the target directory. Solution: Check directory ownership/permissions, or run from a location you can write to. Avoid running against system-owned paths.

Validation fails on archive and nothing happens

Cause: A spec delta is malformed (missing scenario, wrong heading depth, partial MODIFIED block). Archive prepares and validates everything before writing, so it aborts cleanly. Solution: Run openspec validate <change> --strict to see the specific issues, fix the Markdown, and archive again. As a last resort, --no-validate skips checks (you'll be asked to confirm). Prevention: Ensure scenarios use exactly #### and MODIFIED requirements include full content.

Warning: The "openspec change ..." commands are deprecated.

Cause: You used a noun-first command like openspec change list or openspec change validate. Solution: Use the verb-first equivalents: openspec list, openspec validate --changes, openspec show <name>.

openspec update says to run openspec workspace update

Cause: You ran update inside an OpenSpec workspace rather than a repo-local project. Solution: Run openspec workspace update to refresh workspace-local guidance and skills instead.

update crashes when a non-OpenSpec workspace.yaml exists

Cause: A workspace.yaml belonging to another tool (e.g. Dagster) in your project root can collide with OpenSpec's workspace detection. (Reported in the community.) Solution: If you're not using OpenSpec workspaces, this is a known edge case — upgrade to the latest OpenSpec, which improves disambiguation, and report your scenario via openspec feedback.

Commands are slow or hang in a huge repo during validation

Cause: Too much parallelism (or too little) for your machine when validating everything. Solution: Tune openspec validate --all --concurrency <n> or set OPENSPEC_CONCURRENCY.

14. FAQ

Q: Do I write the proposals and specs myself? Usually no. OpenSpec is designed for your AI assistant to write the artifacts using the installed skills, while you review and approve. You can write them by hand — they're just Markdown — but the workflow shines with an agent.

Q: Does OpenSpec need an account, API key, or internet connection? No account or key. It works fully offline for the core workflow. The only network use is optional anonymous telemetry (which you can disable) and whatever your AI tool does separately.

Q: Where does OpenSpec store my data? Entirely in your project's openspec/ directory as plain Markdown, committed to your repo like any other source. User-level settings live in a global config.json under your config directory.

Q: What's the difference between a spec and a change? A spec describes what the system does now. A change is a proposal for what should change. When a change is archived, its future-state deltas are merged into the specs so the specs reflect the new reality.

Q: What does "archiving" actually do? It validates the change, applies its spec deltas to your main specs/, then moves the change directory into changes/archive/ with a YYYY-MM-DD- date prefix.

Q: Which AI tools are supported? Over two dozen, including Claude Code, Cursor, Windsurf, Codex, GitHub Copilot, Gemini CLI, Cline, RooCode, Kiro, Continue, OpenCode, and more. Select them during openspec init.

Q: Can I use OpenSpec with more than one AI tool at once? Yes. Select multiple tools during init; OpenSpec installs the right skills and commands into each tool's directory.

Q: How do I keep the installed skills up to date after upgrading OpenSpec? Run openspec update in your project (or openspec workspace update inside a workspace).

Q: Why did a scenario I wrote get ignored? Scenarios must use exactly four hash marks (#### Scenario:). Three hashes or a bullet are silently skipped. Run openspec validate --strict to catch this.

Q: How do I disable color (for logs or screen readers)? Use --no-color on any command, or set NO_COLOR=1.

Q: What's the difference between the change/spec commands and the top-level list/show/validate? The top-level verb-first commands are current. The openspec change ... noun-first commands are deprecated aliases kept for backward compatibility — prefer the verb-first forms.

Q: Do I need workspaces and initiatives? Only for coordinating work across multiple repos, and they're beta. Single-repo development uses just changes, specs, and schemas.

Q: Can I customize what artifacts a change requires? Yes — fork the default schema (openspec schema fork spec-driven my-workflow) or author a new one (openspec schema init), then edit the schema.yaml and templates.

15. Command Reference

Global flags available on every command: --no-color (disable color), --version, --help.

Project setup

Changes & specs

Artifact workflow

Schema management

Configuration

Cross-repo coordination (beta)

Utilities

Note

Deprecated noun-first commands (openspec change show\|list\|validate, openspec spec show\|list\|validate) still work but print a deprecation warning. Prefer the verb-first commands above.