What Is OpenSpec? Installation and Workflows

OpenSpec is a lightweight Spec-Driven Development framework. It adds a layer of agreement between you and your AI coding assistant: write down what to build, review the plan, and only then write code, instead of letting requirements live only in chat history. It is MIT-licensed, supports more than 30 AI coding tools, and HagiCode’s own workflow is built on it. This page is the shortest path to installing it and running a first complete change; the full guides live on a dedicated site.

Core concepts

OpenSpec is built from five ideas:

1. Specs are the source of truth. They describe how the system behaves right now, live in openspec/specs/, are organized by domain, and are made of requirements and scenarios.
2. A change is one unit of work. To add, modify or remove behavior, you create a folder under openspec/changes/ that holds the proposal, design, task list and spec edits for that work.
3. Delta specs describe only what changes. Inside a change you do not rewrite the whole spec; you write ADDED, MODIFIED and REMOVED, which is what makes it good at editing existing systems.
4. Artifacts build on one another. proposal (why) → specs (what) → design (how) → tasks (steps) → implementation. They are enablers, not gates, and you can go back to any of them.
5. Archiving folds the change back into the truth. When the work is done, the delta specs merge into the main specs and the change folder moves to changes/archive/ with a date.

Install

You need Node.js 20.19.0 or higher (other HagiCode components recommend 24 or higher; see Install Node.js).

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

On macOS and Linux you can also use Homebrew: brew install openspec. pnpm, yarn (1.x) and bun can install it globally too, but OpenSpec still runs on Node.js.

Then go to your project directory and initialize:

cd your-project
openspec init

Initialization asks which AI tools you use and generates skill or command files for them. To skip the prompts, use openspec init --tools claude,cursor; the tool IDs are listed in Supported Tools.

Your first complete change

Slash commands go in your AI assistant’s chat, not the terminal:

/opsx:explore            # not sure yet? let the AI read the code and weigh options
/opsx:propose add-dark-mode   # create the change folder: proposal, specs, design, tasks
/opsx:apply              # implement the task list
/opsx:archive            # archive; delta specs merge into the main specs

/opsx:propose creates openspec/changes/add-dark-mode/ with proposal.md, specs/, design.md and tasks.md. Specs are plain Markdown with no special syntax:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

The AI writes these and you review the plan before any code is written. The default profile includes propose, explore, apply, update, sync and archive. For the expanded flow (new, continue, ff, verify, bulk-archive and more), choose it with openspec config profile and apply it with openspec update.

Command names differ slightly between assistants

/opsx:propose is the canonical spelling. It is /opsx-propose in Cursor and GitHub Copilot, @opsx-propose in Amazon Q and $openspec-propose in Codex. openspec init prints the right form for the tools you picked.

Upgrade

npm install -g @fission-ai/openspec@latest   # upgrade the package
openspec update                              # refresh AI instruction files in each project

If you installed with Homebrew, use brew upgrade openspec.

Common problems

• openspec: command not found: the global npm directory is not on your PATH. Run npm prefix -g; on macOS and Linux add that directory’s bin/ to PATH, and on Windows add the directory itself.
• “Requires Node.js 20.19.0 or higher”: check with node --version and upgrade.
• /opsx:propose does not show up in chat: make sure you typed it in the assistant and not the terminal, run openspec update to regenerate the files, then restart the assistant. Skills-only tools such as Codex need the $openspec-propose style instead.
• Init did not configure your tool: run openspec init again, or pass --tools.

Full documentation

Open the OpenSpec documentation in English

• Install OpenSpec
• Getting started
• Workflows
• Troubleshooting

Further reading

• To decide between it and GitHub’s Spec Kit, read Spec Kit vs OpenSpec.
• HagiCode’s practice on top of OpenSpec: Optimizing OpenSpec Phase Efficiency with Different Agents: HagiCode Practice Summary and What is MonoSpecs: Why It’s a Further Upgrade and Extension of OpenSpec.