OpenSpec Quickstart: Install, Workflow, and Common Pitfalls

Specs as deltas, not a 40-page PRD.

Page content

OpenSpec is a free, open-source CLI from Fission AI that gets you and your coding agent to agree on a change in plain Markdown before any code gets written, without the phase-gated ceremony of heavier spec-driven frameworks.

Most teams who try Spec-Driven Development stall on the same trade-off: enough process to stop an agent from guessing, without so much scaffolding that a fifty-line bugfix needs a proposal document. OpenSpec’s answer is to skip the “document the whole system first” instinct entirely and write specs only for what a change actually touches, using ADDED, MODIFIED, and REMOVED deltas instead of a full rewrite every time.

OpenSpec spec-driven development workflow with an AI coding assistant

That change-centric design is also why OpenSpec keeps coming up next to GitHub Spec Kit, Kiro, and Superpowers in the comparison of SDD tool categories – it is usually the pick when a team wants reviewable specs without an 800-line planning phase. This guide covers installing the CLI, the four-command workflow you actually use day to day, what a change looks like on disk, and the questions and complaints that show up most often on Reddit and in OpenSpec’s own issue tracker.

What Is OpenSpec?

OpenSpec describes its own philosophy in four lines: fluid not rigid, iterative not waterfall, easy not complex, built for brownfield not just greenfield. In practice that means there are no locked phases – you can edit a proposal, a spec, or a task list at any point in a change, rather than being forced through specify-then-plan-then-implement in strict order the way the tool-neutral SDD workflow describes it.

A change in OpenSpec produces up to four Markdown artifacts in its own folder:

Artifact Purpose
proposal.md Why the change exists and what it changes, in plain language
specs/ Delta requirements and scenarios – the testable spec for this change
design.md Optional technical approach, for changes that need one
tasks.md The implementation checklist the agent works through

Once a change is implemented and archived, its delta specs merge into openspec/specs/, which becomes the durable, current-state description of your system – the same “spec as source of truth” idea covered in What Is Spec-Driven Development?, just scoped one change at a time instead of written all at once.

Installing OpenSpec

OpenSpec is a Node.js CLI, so you need Node 20.19.0 or newer on your machine.

node --version

Install the CLI globally with npm, then verify it landed on your PATH:

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

Deno, pnpm, yarn, bun, and nix are also supported install paths if that fits your setup better than npm. Once installed, initialize it inside a project:

cd your-project
openspec init

openspec init asks which AI tools you use and writes the matching skill and command files – OpenSpec supports 30+ assistants, including Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro, and OpenCode. For CI or scripted setup, skip the picker entirely:

openspec init --tools claude,cursor   # set up specific tools
openspec init --tools all             # every supported tool
openspec init --tools none            # openspec/ structure only, no tool files

Restart your IDE afterward so it picks up the newly written skills and commands. If you would rather have your assistant do the whole install for you, OpenSpec ships a setup prompt you can paste into Claude Code or another agent, which runs the install, executes openspec init, and reports back what it configured.

The Core Workflow: Explore, Propose, Apply, Archive

This is the one thing that trips up almost everyone on their first day: openspec commands run in your terminal, but /opsx: commands run in your AI assistant’s chat window. There is no separate “interactive mode” to enter – typing the slash command in chat is how you start.

flowchart LR A["/opsx:explore (optional)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs merged| E["openspec/specs/"]
  • /opsx:explore is a no-stakes thinking partner. It reads the relevant part of your codebase, lays out options, and shapes a plan before anything is written to disk – worth forming as a habit specifically because it stops an eager agent from confidently building the wrong thing.
  • /opsx:propose <name> creates openspec/changes/<name>/ and drafts the proposal, delta specs, optional design, and task list in one step. You review the plan here, before implementation starts.
  • /opsx:apply works through the task list, checking items off as it goes. Because progress lives in files rather than only in chat history, you can clear your context window or start a fresh session and pick up exactly where /opsx:apply left off.
  • /opsx:archive files the completed change to openspec/changes/archive/YYYY-MM-DD-<name>/ and merges its delta specs into the canonical openspec/specs/ tree.

The default core profile installs exactly those four commands plus update and sync. An expanded profile adds new, continue, ff, verify, bulk-archive, and onboard for teams who want to create one artifact at a time instead of all at once – switch to it with openspec config profile followed by openspec update.

Each tool spells the same command differently depending on how it loads custom instructions: /opsx:propose in Claude Code, /opsx-propose in Cursor and GitHub Copilot, @opsx-propose in Amazon Q, or $openspec-propose in Codex. openspec init prints the exact form for the tools you picked, so the fastest fix for “nothing happened when I typed the command” is usually to re-read that printed hint rather than guess.

What a Change Looks Like on Disk

A change folder under openspec/changes/add-dark-mode/ typically contains a proposal, a delta spec, and a task list like this:

## 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

That ADDED/MODIFIED/REMOVED delta format is the mechanism that lets OpenSpec avoid rewriting an entire spec file for a one-field change. It is also why OpenSpec is explicitly brownfield-first rather than greenfield-first: you never document your whole application before getting value, you just document the slice each real change touches, and openspec/specs/ fills in naturally over months of normal work.

Useful CLI commands for checking on that state without leaving the terminal:

openspec list                 # active changes
openspec show add-dark-mode   # view a change's artifacts
openspec validate --all       # check spec formatting across the project
openspec view                 # interactive dashboard

Commit the whole openspec/ folder to git. The active changes and the archive are meant to become a durable, versioned record of what your system does and why it changed – not a scratch pad you delete after merging.

Adopting OpenSpec on an Existing Codebase

The most common worry from teams evaluating OpenSpec on a real project is some version of “my app is 80,000 lines old, do I have to spec all of it first?” You do not. OpenSpec’s own guidance is blunt about this: pick something small and real that you were already going to build this week, run /opsx:explore on the area you are about to touch so the agent maps how things actually work first, then /opsx:propose a change scoped to just that slice.

If you already have PRDs, SRS documents, or design docs sitting in Notion or Confluence, treat them as source material for exploration rather than something to bulk-convert into specs. Paste the relevant section into an /opsx:explore session and let the agent shape a focused delta from it; a one-time mechanical conversion of a forty-page PRD tends to produce a spec nobody trusts six months later. For teams that want a guided, narrated first run instead of jumping straight into a real change, the expanded /opsx:onboard command scans your codebase for a small, safe improvement and walks through the full loop on it.

Common Questions and Problems

These are the issues that show up repeatedly across OpenSpec’s Discord, GitHub issues, and Reddit threads in subreddits like r/cursor, r/RooCode, and r/opencodeCLI.

“I typed the slash command and nothing happened.” Almost always one of: you typed it in the terminal instead of your assistant’s chat, your IDE has not restarted since openspec init ran, or the CLI version is old enough that openspec update reports everything current without ever writing the newer workflow files. Run openspec update, restart the IDE, and confirm the skill folders exist (.claude/skills/openspec-* for Claude Code, or your tool’s equivalent from the supported-tools list).

“The AI generates way more spec than I need.” This is the most-cited complaint in longer write-ups: an agent can turn a thirty-minute feature into an 800-line spec. OpenSpec caps the context: field injected into every request at 50KB specifically to force discipline, but the delta specs themselves have no hard limit, so trimming generated specs down to what is actually load-bearing is a habit you have to maintain yourself, not something the tool enforces for you.

“Two changes touched the same requirement and one silently dropped the other’s scenario.” This is a real, documented edge case: archiving applies a MODIFIED delta as a whole-block replace keyed by requirement name, so if two in-flight changes both modify the same requirement, archiving the second one used to overwrite the first’s scenarios without warning. Current versions add a drift check that aborts the archive and tells you to refresh the change’s spec first – but it is still worth knowing the failure mode exists if you run several changes on the same area in parallel.

“Which AI model should I actually use with it?” OpenSpec’s own docs recommend high-reasoning models for both planning and implementation – Opus-class and Codex-class models are called out specifically – and clearing your context window before implementation, since a clean context produces measurably better results than a long, accumulated session.

“How is this different from Spec Kit, Kiro, Superpowers, or BMAD?” This is the single most frequent Reddit question, and the honest answer is “process weight.” OpenSpec’s own README frames the comparison directly: Spec Kit is thorough but heavier, with more Markdown and rigid phase gates; Kiro is powerful but locks you into AWS’s IDE and Claude models; OpenSpec trades some of that upfront structure for the ability to iterate freely and work with whatever assistant you already have open. For the full breakdown against Spec Kit, Kiro, Claude Code skills, BMAD-METHOD, and Superpowers, see the dedicated SDD tool comparison.

“Does the AI actually follow the spec it just wrote?” Not always, and this is a documented problem across SDD tools generally, not unique to OpenSpec – a large context window does not mean the agent attends equally to every part of it. The /opsx:verify command exists specifically to catch generated code that contradicts its own spec, and it is worth running on anything non-trivial rather than trusting the implementation blindly.

“Do I need this for a one-line fix?” No. OpenSpec’s own FAQ says as much: use it where agreement matters, which is most non-trivial, multi-file work, and skip it for a typo fix or a throwaway prototype you will delete in a week.

When OpenSpec Fits and When It Doesn’t

Good fit:

  • Brownfield codebases where you want reviewable specs without documenting the entire system upfront.
  • Solo developers and small teams who want lighter ceremony than Spec Kit while still getting a written plan before code.
  • Work that spans several files, a schema change, or anything a junior engineer would reasonably want a short design doc for.
  • Teams already committed to reviewing plans in pull requests – delta specs diff cleanly since they only describe what changed.

Weaker fit:

  • One-line bug fixes and throwaway prototypes, where the proposal-review step costs more than it saves.
  • Teams that need the heavier, more prescriptive structure of Spec Kit or an AWS-native, IDE-integrated experience like Kiro – see the decision framework in the tool comparison for where each tool wins.
  • Cross-repo features today, unless you are willing to try OpenSpec’s beta stores feature, which moves planning into its own shared repository so multiple codebases and agents can read the same plan.
  • Anyone still deciding whether a given feature deserves a spec at all – read Spec-Driven Development vs Vibe Coding first, since OpenSpec only helps once you have already decided structure is worth the overhead.

Conclusion

OpenSpec’s bet is that most Spec-Driven Development pain comes from ceremony, not from the underlying idea of agreeing on a plan before code exists. Deltas instead of full rewrites, no locked phases, and a brownfield-first workflow make it noticeably lighter than Spec Kit or Kiro to adopt on a codebase you did not build from scratch. The trade-offs are real too – spec bloat is a genuine risk without discipline, the conflict handling around simultaneous changes to one requirement is still maturing, and the ecosystem is younger than GitHub’s own tooling. Install it on one real project, run a small change through explore-propose-apply-archive end to end, and decide from there whether the lighter ceremony earns its keep against your actual workload.

Subscribe

Get new posts on AI systems, Infrastructure, and AI engineering.