# 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](#1-quick-start) 2. [Installation](#2-installation) 3. [Core Concepts](#3-core-concepts) 4. [The Change Workflow](#4-the-change-workflow) 5. [Everyday Commands](#5-everyday-commands) 6. [Working With Your AI Assistant](#6-working-with-your-ai-assistant) 7. [Validating Changes and Specs](#7-validating-changes-and-specs) 8. [Customizing Workflows With Schemas](#8-customizing-workflows-with-schemas) 9. [Coordinating Across Repos (Beta)](#9-coordinating-across-repos-beta) 10. [Shell Completions](#10-shell-completions) 11. [Configuration & Privacy](#11-configuration--privacy) 12. [Common Workflows (Recipes)](#12-common-workflows-recipes) 13. [Troubleshooting](#13-troubleshooting) 14. [FAQ](#14-faq) 15. [Command Reference](#15-command-reference) --- ## 1. Quick Start Get OpenSpec running in an existing project in under two minutes. ```bash # 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 ``` ```text 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 | Requirement | Detail | |---|---| | Node.js | `>= 20.19.0` | | Package manager | npm, pnpm, or yarn (any can run `npx`/global install) | | OS | macOS, Linux, Windows (all first-class) | > [!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: ```bash npx @fission-ai/openspec@latest init ``` === "Global install (npm)" Best for daily use, gives you the `openspec` command everywhere: ```bash npm install -g @fission-ai/openspec openspec --version ``` === "Global install (pnpm)" ```bash pnpm add -g @fission-ai/openspec openspec --version ``` Verify the install: ```bash openspec --version ``` ```text 1.4.1 ``` ### Initialize a project Run `init` from the root of the project you want to manage: ```bash 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`: ```bash # 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//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//`. 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: ```text 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. ```text 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 ` (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**. ```bash # What the agent runs (you can run it too): openspec new change add-password-reset --description "Let users reset a forgotten password" ``` ```text 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: ```bash openspec status --change add-password-reset ``` ```text 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. ```bash 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. ```bash openspec archive add-password-reset ``` ```text 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 --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 ```bash openspec list # active changes (default), most recent first openspec list --specs # list specs instead openspec list --sort name # alphabetical openspec list --json # machine-readable ``` ```text 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: ```bash 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 ```bash 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 ```bash 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: ```bash openspec update ``` ```text 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. ```bash 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): ```bash openspec validate --all --concurrency 12 ``` > [!IMPORTANT] > Specs use a strict structure. Each requirement is `### Requirement: `, 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. ```bash 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 ``` ```text 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: ```bash openspec schema fork spec-driven my-workflow ``` Or scaffold a brand-new project-local schema: ```bash 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 ` 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: ```bash 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: ```bash 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: ```bash 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**. ```bash # 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 ` 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: ```bash 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: | Key | Values | Meaning | |---|---|---| | `profile` | `core`, `custom` | Which set of workflow skills to install | | `delivery` | `both`, `skills`, `commands` | Install skills, slash commands, or both | The `profile` shortcut command opens an interactive picker (or accepts a preset): ```bash 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: ```bash 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 | Variable | Effect | |---|---| | `OPENSPEC_TELEMETRY=0` | Disable anonymous usage analytics | | `DO_NOT_TRACK=1` | Disable analytics (cross-tool standard) | | `NO_COLOR=1` | Disable colored output (same as `--no-color`) | | `OPENSPEC_CONCURRENCY=` | Default parallelism for bulk validation | | `EDITOR` / `VISUAL` | Editor used by `openspec config edit` | | `XDG_CONFIG_HOME` | Override the global config directory location | --- ## 12. Common Workflows (Recipes) ### Start a small change end-to-end ```bash 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) ```bash openspec archive bump-eslint --skip-specs --yes ``` ### Validate everything in CI ```bash 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 ```bash openspec show add-password-reset --json --deltas-only ``` ### Inspect a single requirement of a spec ```bash openspec show user-auth --type spec --json --requirement 2 ``` ### Send feedback to the maintainers ```bash 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 '' 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): . 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 ` **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 --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 `. ### `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 ` 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 | Command | Purpose | Key options | |---|---|---| | `openspec init [path]` | Initialize OpenSpec and install tool integrations | `--tools `, `--force`, `--profile ` | | `openspec update [path]` | Refresh installed instruction files | `--force` | ### Changes & specs | Command | Purpose | Key options | |---|---|---| | `openspec list` | List changes (default) or specs | `--specs`, `--changes`, `--sort `, `--json` | | `openspec view` | Interactive dashboard of specs and changes | — | | `openspec show [item]` | Show a change or spec | `--json`, `--type `, `--no-interactive`, `--deltas-only`, `--requirements`, `--no-scenarios`, `-r ` | | `openspec validate [item]` | Validate changes and/or specs | `--all`, `--changes`, `--specs`, `--type`, `--strict`, `--json`, `--concurrency `, `--no-interactive` | | `openspec archive [change]` | Archive a completed change, sync specs | `-y, --yes`, `--skip-specs`, `--no-validate` | ### Artifact workflow | Command | Purpose | Key options | |---|---|---| | `openspec new change ` | Scaffold a new change directory | `--description`, `--goal`, `--areas`, `--initiative`, `--store`, `--store-path`, `--schema`, `--json` | | `openspec set change ` | Set checked-in change metadata | `--initiative`, `--store`, `--store-path`, `--json` | | `openspec status` | Show artifact completion status | `--change `, `--schema `, `--json` | | `openspec instructions [artifact]` | Output enriched instructions to create an artifact (or `instructions apply`) | `--change `, `--schema`, `--json` | | `openspec templates` | Show template paths for a schema's artifacts | `--schema`, `--json` | | `openspec schemas` | List available workflow schemas | `--json` | ### Schema management | Command | Purpose | Key options | |---|---|---| | `openspec schema which [name]` | Show where a schema resolves from | `--json`, `--all` | | `openspec schema validate [name]` | Validate a schema's structure/templates | `--json`, `--verbose` | | `openspec schema fork [name]` | Copy a schema into the project to customize | `--json`, `--force` | | `openspec schema init ` | Create a new project-local schema | `--description`, `--artifacts`, `--default`, `--no-default`, `--force`, `--json` | ### Configuration | Command | Purpose | Key options | |---|---|---| | `openspec config path` | Show config file location | — | | `openspec config list` | Show all settings | `--json` | | `openspec config get ` | Read one value (scriptable) | — | | `openspec config set ` | Set a value (auto-coerces type) | `--string`, `--allow-unknown` | | `openspec config unset ` | Remove a key (revert to default) | — | | `openspec config reset` | Reset configuration | `--all`, `-y, --yes` | | `openspec config edit` | Open config in `$EDITOR` | — | | `openspec config profile [preset]` | Configure the workflow profile | — | ### Cross-repo coordination (beta) | Command | Purpose | |---|---| | `openspec workspace setup\|list\|link\|relink\|doctor\|update\|open` | Manage coordination workspaces | | `openspec context-store setup\|register\|unregister\|remove\|list\|doctor` | Manage context stores | | `openspec initiative create\|show\|list` | Manage initiatives | ### Utilities | Command | Purpose | Key options | |---|---|---| | `openspec completion generate\|install\|uninstall [shell]` | Manage shell completions | `--verbose` (install), `-y` (uninstall) | | `openspec feedback ` | Submit feedback to maintainers | `--body ` | > [!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. --- _Generated June 2026 from Fission-AI/OpenSpec at 1b06fdd. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._