OpenSpec

https://openspec.dev/
Admin
A lightweight spec-driven framework for planning and documenting system requirements across coding...
Tokens:76,746
Snippets:576
Trust Score:7.3
Update:11 hours ago
Show doc for...
Tokens:
Raw
### openspec init output example

Source: https://openspec.dev/docs/cli

Example output after running openspec init with a selected tool. It shows the created structure, the setup completion message, and a getting-started hint. The summary reads 'Refreshed: Claude Code' with 'Config: openspec/config.yaml (exists)' when the project is already initialized.

```text
▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Restart your IDE for the new commands to take effect.
```

--------------------------------

### Example config.json

Source: https://openspec.dev/docs/configuration/config-json

A filled-in config.json example showing the profile, delivery, featureFlags, and telemetry settings.

```json
{
  "profile": "core",
  "delivery": "both",
  "featureFlags": {},
  "telemetry": {
    "anonymousId": "5f8a2c1e-4b6d-4f9a-9c3d-7e1b2a8d4c6f",
    "noticeSeen": true
  }
}
```

--------------------------------

### Install via CLI agent (Claude Code)

Source: https://openspec.dev/docs/installation

Pipe the install instructions into a CLI agent like Claude Code. This fetches install.md and runs it, which will guide the agent through the installation steps.

```bash
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md | claude
```

--------------------------------

### openspec completion install and generate usage

Source: https://openspec.dev/docs/cli

Shows the two main subcommands: install (detect shell, install, wire up config) and generate (print script to stdout). Each subcommand takes an optional shell argument; omitting it detects the shell from the environment.

```bash
openspec completion install        # detect your shell, install, wire up config
openspec completion generate zsh   # print the script to stdout
```

--------------------------------

### openspec store setup command

Source: https://openspec.dev/docs/cli

Creates a store folder and registers it. In an interactive terminal, setup prompts for a missing name and location and confirms before creating anything. Outside one, a missing name or --path exits 1 with the flag to pass. Rerunning setup for a registered store reports 'Registry: already registered'. Setup exits 1 with store_setup_inside_git_repo when --path is inside another Git repository; --no-init-git skips that check.

```shell
openspec store setup team-context --path ~/openspec/team-context
```

--------------------------------

### openspec store subcommands: setup, register, list

Source: https://openspec.dev/docs/cli

Shows the three main store subcommands: create and register a store with setup, register an existing checkout, and list registered stores. Registrations live in a per-machine registry at ~/.local/share/openspec/stores/registry.yaml (or $XDG_DATA_HOME/openspec/stores/registry.yaml when XDG_DATA_HOME is set). Every subcommand takes --json for structured output.

```shell
openspec store setup team-context --path ~/openspec/team-context   # create and register
openspec store register ~/stores/design-system                     # register an existing checkout
openspec store list                                                # see what's registered
```

--------------------------------

### Install via AI chat prompt

Source: https://openspec.dev/docs/installation

Paste this prompt into your AI chat to have the assistant fetch and follow the install instructions from the OpenSpec repository. The assistant will check Node version, skip if already installed, verify PATH, and run openspec init.

```bash
Fetch https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md and follow it.
```

--------------------------------

### Example openers configuration in config.json

Source: https://openspec.dev/docs/configuration/config-json

Shows how to add a custom tool (code-insiders) and override the built-in VS Code opener's args. The corresponding executable must be installed and on PATH.

```json
{
  "openers": {
    "code-insiders": {
      "style": "workspace-file",
      "label": "VS Code Insiders"
    },
    "code": {
      "args": ["--new-window"]
    }
  }
}
```

--------------------------------

### openspec version output for global npm install

Source: https://openspec.dev/docs/cli

Example output for a global npm install. The install scope can be global, project, temporary (for npx), or source (for a checkout). OpenSpec omits details it cannot identify instead of guessing.

```text
OpenSpec 1.13.2 (npm, global)
```

--------------------------------

### openspec show text output example

Source: https://openspec.dev/docs/cli

Example of text mode output for a change, showing the proposal.md content.

```markdown
# Add rate limiting

## Why
Unauthenticated clients can exhaust the API.

## What Changes
- Add per-client rate limiting to the public API.
```

--------------------------------

### openspec workset create, list, remove example

Source: https://openspec.dev/docs/cli

Example commands for creating, listing, and removing a workset. The create command uses --member flags to add folders, list shows saved worksets, and remove deletes a workset with --yes.

```bash
openspec workset create checkout --member ~/projects/checkout-api --member web=~/projects/checkout-web
openspec workset list
openspec workset remove checkout --yes
```

--------------------------------

### Install integrations in store-only repo

Source: https://openspec.dev/docs/stores

Run this command from the repository root to install AI tool integration files without moving planning back into the repo. Refuses to run from a subdirectory and refuses --language.

```bash
# inside web-app, at the repository root
openspec init --tools claude
```

--------------------------------

### Example .openspec.yaml

Source: https://openspec.dev/docs/configuration/change-metadata

A filled-in .openspec.yaml file showing the schema, created date, goal, and affected areas.

```yaml
schema: spec-driven
created: 2026-08-14
goal: Add magic-link login to the API
affected_areas:
  - auth
  - api

```

--------------------------------

### openspec store setup output

Source: https://openspec.dev/docs/cli

Text output from a successful `openspec store setup` run, showing the store location, OpenSpec root status, registry status, and a next-step hint. The output includes the store id and path, and suggests running normal OpenSpec commands against the store.

```text
Store ready: team-context
Location: /Users/you/stores/team-context
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-context
Share this store by committing and pushing it like any Git repo.
```

--------------------------------

### Push the store to a git host

Source: https://openspec.dev/docs/stores

Connect the store to an empty remote repository and publish it. Setup does not add a git remote.

```bash
# connect the store to the empty repo on your git host
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# publish it
git push -u origin main
```

--------------------------------

### openspec show change JSON output example

Source: https://openspec.dev/docs/cli

Example of `--json` output for a change, showing the delta-shaped structure with requirements and scenarios.

```json
{
  "id": "add-rate-limit",
  "title": "Add rate limiting",
  "deltaCount": 1,
  "deltas": [
    {
      "spec": "api",
      "operation": "ADDED",
      "description": "Add requirement: The API SHALL limit each client to 100 requests per minute.",
      "requirement": {
        "name": "Rate limit",
        "text": "The API SHALL limit each client to 100 requests per minute.",
        "scenarios": [
          {
            "name": "Client exceeds the limit",
            "rawText": "- **WHEN** a client sends its 101st request within a minute\n- **THEN** the API responds 429"
          }
        ]
      },
      ...
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}
```

--------------------------------

### openspec workset open examples

Source: https://openspec.dev/docs/cli

Examples of opening a workset with the saved tool or specifying a tool with --tool. Editor tools generate a .code-workspace file; CLI agent tools are temporarily disabled.

```bash
openspec workset open checkout                # saved tool, or a prompt
openspec workset open checkout --tool cursor  # this tool just this once
```

--------------------------------

### openspec store setup --json output

Source: https://openspec.dev/docs/cli

JSON report from `openspec store setup --json`, detailing the created store, registry entry, git state, and created files. The `already_registered` field indicates whether the store was already in the registry.

```json
{
  "store": {
    "id": "design-system",
    "root": "/Users/you/stores/design-system",
    "metadata_path": "/Users/you/stores/design-system/.openspec-store/store.yaml"
  },
  "registry": {
    "path": "/Users/you/.local/share/openspec/stores/registry.yaml",
    "registered": true,
    "already_registered": false
  },
  "git": {
    "is_repository": true,
    "initialized": true,
    "committed": true
  },
  "created_files": [
    "openspec/",
    "openspec/specs/",
    "openspec/changes/",
    "openspec/changes/archive/",
    "openspec/config.yaml",
    "openspec/specs/.gitkeep",
    "openspec/changes/archive/.gitkeep",
    ".openspec-store/store.yaml"
  ],
  "status": []
}
```

--------------------------------

### openspec schema init output

Source: https://openspec.dev/docs/cli

Example output from the init command, showing the created schema and its artifacts.

```text
✔ Created schema 'my-schema'

Schema created at: /Users/you/projects/my-app/openspec/schemas/my-schema

Artifacts: proposal, tasks
```

--------------------------------

### openspec new change examples

Source: https://openspec.dev/docs/cli

Shows two example invocations of openspec new change: one with metadata only and one with a --goal flag.

```bash
openspec new change add-caching                                # metadata only
openspec new change add-search --goal "Users can search docs"  # record a goal
```

--------------------------------

### openspec workset create output

Source: https://openspec.dev/docs/cli

Example output after successfully creating a workset, showing the saved message and the command to open it.

```text
Saved workset 'checkout' (2 members) to your machine.
Open it any time with: openspec workset open checkout
```

--------------------------------

### openspec instructions apply output

Source: https://openspec.dev/docs/cli

Example output of the apply form, showing context files, progress, tasks, and instruction.

```text
## Apply: add-rate-limit
Schema: spec-driven

### Context Files
- proposal: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
- specs: /Users/you/projects/my-app/openspec/changes/add-rate-limit/specs/api/spec.md
- tasks: /Users/you/projects/my-app/openspec/changes/add-rate-limit/tasks.md

### Progress
1/3 complete

### Tasks
- [x] 1.1 Add rate limit middleware
- [ ] 1.2 Return 429 with Retry-After header
- [ ] 1.3 Add tests for burst traffic

### Instruction
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.

No project context or operation guidance configured.
```

--------------------------------

### Confirm the store works with openspec status

Source: https://openspec.dev/docs/stores

Run any OpenSpec command by store name to verify the setup.

```bash
# any OpenSpec command reaches the store by name
openspec status --store team-plans
```

```text
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans
```

--------------------------------

### openspec init basic usage examples

Source: https://openspec.dev/docs/cli

Shows three ways to run openspec init: with no --tools flag for an interactive tool picker, with --tools to set up specific tools without prompts, and with --tools none to create only the openspec/ structure without tool files.

```bash
openspec init                        # current directory, interactive tool picker
openspec init --tools claude,cursor  # set up specific tools, no prompts
openspec init --tools none           # openspec/ structure only, no tool files
```

--------------------------------

### Start from scratch with openspec schema init

Source: https://openspec.dev/docs/customize-schemas

Command to scaffold a new schema named 'lite' with description and artifacts, including the output showing the created schema location and artifacts.

```bash
$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks
```

--------------------------------

### operations field example in config.yaml

Source: https://openspec.dev/docs/project-config

Use the operations field to guide how the agent carries out apply and archive workflows. The example instructs running the linter before marking tasks complete and summarizing shipped changes before archiving.

```yaml
operations:
  apply:
    guidance:
      - Run the linter before marking a task complete
  archive:
    guidance:
      - Summarize what shipped before archiving
```

--------------------------------

### Create the store with openspec store setup

Source: https://openspec.dev/docs/stores

Run from anywhere; it prompts for store name, location, and confirmation. The default location is ~/openspec/<name>.

```bash
# run from anywhere; it asks what to create and where
openspec store setup
```

```text
Store ready: team-plans
Location: ~/openspec/team-plans
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share this store by committing and pushing it like any Git repo.
```

--------------------------------

### Install OpenSpec CLI globally with npm

Source: https://openspec.dev/docs/installation

Installs the OpenSpec CLI globally using npm. This is the primary installation method.

```bash
npm install -g @fission-ai/openspec@latest
```

--------------------------------

### Install OpenSpec globally via npm

Source: https://openspec.dev/

Install the OpenSpec CLI globally using npm. The command installs the latest version of the @fission-ai/openspec package.

```bash
$ npm install -g @fission-ai/openspec@latest
```

--------------------------------

### Check OpenSpec CLI installation

Source: https://openspec.dev/docs/installation

Verifies that the OpenSpec CLI is installed and on your PATH by printing its version.

```bash
openspec --version
```

--------------------------------

### OpenSpec init output

Source: https://openspec.dev/docs/setup

Example output from running openspec init, showing the created tool files and configuration. Restart your IDE for the new commands to take effect.

```text
OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)
```

--------------------------------

### openspec instructions command examples

Source: https://openspec.dev/docs/cli

Shows how to use the openspec instructions command for proposal, apply, and archive artifacts with the --change option.

```bash
openspec instructions proposal --change add-rate-limit   # how to write one artifact
openspec instructions apply --change add-rate-limit      # how to implement the change
openspec instructions archive --change add-rate-limit    # inputs for archiving
```

--------------------------------

### openspec show spec JSON output example

Source: https://openspec.dev/docs/cli

Example of `--json` output for a spec, listing requirements with scenarios and metadata.

```json
{
  "id": "api",
  "title": "api",
  "overview": "Public HTTP API behavior.",
  "requirementCount": 1,
  "requirements": [
    {
      "name": "Health endpoint",
      "text": "The API SHALL expose a health endpoint.",
      "scenarios": [
        {
          "name": "Health check succeeds",
          "rawText": "- **WHEN** a client requests GET /health\n- **THEN** the API responds 200"
        }
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "format": "openspec"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}
```

--------------------------------

### Install OpenSpec CLI with Nix profile

Source: https://openspec.dev/docs/installation

Installs the OpenSpec CLI into your Nix profile using the flake from the OpenSpec repo. This leaves the CLI on your PATH.

```bash
nix profile install github:Fission-AI/OpenSpec
```

--------------------------------

### Install OpenSpec CLI with Homebrew

Source: https://openspec.dev/docs/installation

Installs OpenSpec and its Node.js dependency on macOS or Linux using Homebrew. The formula is published in homebrew-core, so no tap is needed.

```bash
brew install openspec
```

--------------------------------

### openspec context --store output

Source: https://openspec.dev/docs/cli

Example output when using `--store` to set a registered store as the root, showing that the store becomes the whole working set.

```text
Using OpenSpec root: team-context (/Users/you/stores/team-context)
Working context for team-context (/Users/you/stores/team-context)

OpenSpec root
  team-context  /Users/you/stores/team-context

No references declared; the working set is this root alone.
```

--------------------------------

### Example change folder structure

Source: https://openspec.dev/docs/schemas/spec-driven

Shows the directory layout for a change named 'add-user-auth' with all artifacts drafted, including .openspec.yaml, proposal.md, specs/, design.md, and tasks.md.

```text
openspec/changes/add-user-auth/
├── .openspec.yaml      change metadata, written when the change is created
├── proposal.md
├── specs/
│   └── user-auth/
│       └── spec.md     one delta spec per capability
├── design.md
└── tasks.md

```

--------------------------------

### Completion install success output

Source: https://openspec.dev/docs/cli

Output shown after a successful install, indicating the config file was configured and instructing to restart the shell or run 'exec zsh'.

```text
✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh
```

--------------------------------

### openspec schema init command

Source: https://openspec.dev/docs/cli

Creates a new project-local schema with starter templates. Use `--description` and `--artifacts` to specify details; without them in a terminal, it prompts.

```bash
openspec schema init my-schema --description "Lightweight flow" --artifacts proposal,tasks
```

--------------------------------

### Workflow skills installed in .agents/skills/

Source: https://openspec.dev/docs/setup

Lists the default OpenSpec workflow skills installed in the shared .agents/ folder, including two optional ones (openspec-verify-change and openspec-bulk-archive-change) that are not included by default.

```text
.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)
```

--------------------------------

### openspec feedback command examples

Source: https://openspec.dev/docs/cli

Shows two example invocations of the openspec feedback command. The first submits a simple message; the second includes a --body flag with a longer description.

```bash
openspec feedback "Validate output is hard to scan"
openspec feedback "Archive fails on Windows" --body "Steps: init, propose, archive. Error: EPERM."
```

--------------------------------

### Run openspec init in your project

Source: https://openspec.dev/docs/setup

Run this command at the root of your project to initialize OpenSpec. It asks which AI tools you use, writes workflow files for the selected tools, and reports what was created.

```text
cd <your-project>
openspec init
```

--------------------------------

### openspec validate --report findings examples

Source: https://openspec.dev/docs/cli

Shows two example invocations of the findings report mode: one with --all and one with --archived --json. Both are valid bulk validation scopes.

```bash
openspec validate --all --report findings
openspec validate --archived --report findings --json
```

--------------------------------

### rules field example in config.yaml

Source: https://openspec.dev/docs/project-config

Use the rules field to attach extra instructions to a specific artifact, keyed by artifact id. The example adds a word limit for proposals and requires Playwright tests for UI tasks.

```yaml
rules:
  proposal:
    - Keep proposals under 500 words
  tasks:
    - Every UI task includes a Playwright test
```
Tokens:
Raw