Skip to content
Get packs

Guide · Open source

How to use OpenSpec: install, init and your first change

Updated · written with AI from the project's own documentation and checked against our catalogue data

OpenSpec is a command-line tool that adds a lightweight specification layer to AI coding assistants. Before the assistant writes code, you and the AI create a proposal, requirement specs, a design and a task list in an openspec/ folder inside your project. This guide shows you how to install it, initialize it in a repo, and run one change from idea to archive.

OpenSpecFission-AI/OpenSpec · ★ 73.7k · MIT

Quick start

  1. 1Install the CLI. Run the install script, or use npm (Node.js 20.19.0 or higher) or Homebrew.
  2. 2Go to your project. Change into the repository you want OpenSpec to manage.
  3. 3Initialize. Run openspec init to set up OpenSpec in the project.
  4. 4Explore if unsure. Use /opsx:explore in your AI assistant to shape the idea before committing to a plan.
  5. 5Propose a change. Run /opsx:propose with a short name to create the proposal, specs, design and tasks.
  6. 6Review, apply and archive. Check the plan, run /opsx:apply so the AI implements the tasks, then run /opsx:archive.

Install OpenSpec on macOS, Linux or Windows

The quickest route on macOS and Linux is the install script from the README. On Windows, use the PowerShell script. OpenSpec is distributed as a single file, so Node.js is not needed for these routes.

If you prefer a package manager, you can install with npm (requires Node.js 20.19.0 or higher) or with Homebrew. On Alpine Linux, first install the libstdc++ and libgcc packages for the binary install.

  • npm: requires Node.js 20.19.0 or higher
  • Homebrew: use the official formula
  • Alpine Linux: install libstdc++ and libgcc before the binary install
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh npm install -g @fission-ai/openspec@latest brew install openspec

Initialize OpenSpec in your project

Move into your project folder and run the init command. It sets up OpenSpec for the project and prints the command form that matches the AI tools you chose.

The README notes that openspec init prints the right slash-command spelling for your tools, so check its output before you start.

cd your-project openspec init

Use /opsx:explore and /opsx:propose to plan a change

If you are not sure what to build, start with /opsx:explore. The README describes it as a no-stakes thinking partner that reads your code, weighs options and shapes a plan before any code is written.

If you already know what you want, go straight to /opsx:propose with a short name for the change. The proposal creates a folder under openspec/changes/ containing proposal.md, a specs/ folder, design.md and tasks.md.

  • proposal.md: why the change is needed and what is changing
  • specs/: requirements and scenarios
  • design.md: the technical approach
  • tasks.md: the implementation checklist
You: /opsx:propose add-dark-mode

Review the plan, then apply and archive

Read the generated plan before you let the AI write code. The README's workflow is: the AI implements the tasks with /opsx:apply, then /opsx:archive moves the finished change into the archive folder and updates the specs.

Specs are plain Markdown. Requirements use the SHALL wording and each has scenarios written as WHEN and THEN lines.

You: /opsx:apply You: /opsx:archive

Use the expanded workflow when you need more control

The default profile includes /opsx:explore and /opsx:propose. For the expanded workflow, which adds commands such as /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive and /opsx:onboard, select it with the profile command and then apply the change.

The README says you can update any artifact at any time, since the process is fluid rather than gated by phases.

  • Select a profile with openspec config profile
  • Apply the selected profile with openspec update
openspec config profile openspec update

Know when Stores fit and when they do not

Stores let a team keep planning in a separate repo and share the openspec/ folder across repositories with git push. The README describes Stores as beta, so treat them as unproven for critical cross-repo work.

For a single repo, the core workflow in your project is the main path.

  • Good fit: one repo, solo developer or small team using an AI assistant
  • Careful: Stores are in beta, so check the Stores guide before relying on them

What people use it for

  • Agree on requirements with an AI assistant before it edits a brownfield codebase
  • Keep an AI on a defined task list within a single repository
  • Explore a feature idea with the assistant before writing any code
  • Share requirement specs across several repos using Stores (beta)

Frequently asked questions

Is OpenSpec free?

OpenSpec is released under the MIT licence, according to the README. The source is open and the project is on GitHub under Fission-AI.

What do I need to install OpenSpec?

The npm route needs Node.js 20.19.0 or higher. The binary install needs no Node.js, but on Alpine Linux you first need the libstdc++ and libgcc packages.

How do I install OpenSpec?

Use the install script for macOS and Linux, the PowerShell script on Windows, npm install -g @fission-ai/openspec@latest, or brew install openspec. Then run openspec init inside your project.

Which AI tools does OpenSpec work with?

The README says it supports 30+ tools and the full list is in the Supported Tools docs. The slash command spelling varies by tool, for example /opsx-propose in Cursor and GitHub Copilot.

How does OpenSpec compare to Spec Kit and Kiro?

The README describes Spec Kit as thorough but heavyweight, with rigid phase gates and Python setup. OpenSpec is positioned as lighter and more iterative. Kiro, from AWS, is also named as a comparable project.

Why does my tool show a different command name?

Tools spell the commands differently, for example Cursor and GitHub Copilot use /opsx-propose, Amazon Q uses @opsx-propose and Codex uses $openspec-propose. Run openspec init to see the form for your tools.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OpenSpec suits developers and teams who use AI coding assistants and want requirements agreed before code is written, especially on existing codebases. If you do not use an AI assistant, or you want a strict phase-gated process, pick another tool such as Spec Kit, and avoid relying on Stores for critical work while they remain in beta.

Install options & downloads