OpenSpec Quickstart: Install, Workflow, and Common Pitfalls

Fission AI released OpenSpec, a free open-source Node.js CLI that lets developers and coding agents agree on a change in plain Markdown before any code is written. The tool uses a change-centric workflow with ADDED, MODIFIED, and REMOVED spec deltas and supports 30+ AI assistants including Claude Code, Cursor, GitHub Copilot, and Gemini CLI. It positions itself as a lighter alternative to phase-gated spec-driven development frameworks such as GitHub Spec Kit and Kiro.

OpenSpec https://github.com/Fission-AI/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. 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 https://www.glukhov.org/ai-devtools/ai-coding-assistants/spec-kit-vs-kiro-vs-claude-code/ -- 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. 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 https://www.glukhov.org/app-architecture/documentation/spec-driven-development-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? https://www.glukhov.org/app-architecture/documentation/what-is-spec-driven-development/ , just scoped one change at a time instead of written all at once. 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 https://www.glukhov.org/ai-devtools/claude-code/ or another agent, which runs the install, executes openspec init , and reports back what it configured. 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. php 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 /opsx:propose <name 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 /opsx:archive 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. A change folder under openspec/changes/add-dark-mode/ typically contains a proposal, a delta spec, and a task list like this: js 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. 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. 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 https://www.glukhov.org/ai-devtools/superpowers/ , see the dedicated SDD tool comparison https://www.glukhov.org/ai-devtools/ai-coding-assistants/spec-kit-vs-kiro-vs-claude-code/ . "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. Good fit: Weaker fit: 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.