What is OpenSpec?
OpenSpec is a spec-driven development tool from Fission AI: a command-line program plus skills and slash commands that it installs into your AI coding tool. The OpenSpec README gives the reason in one line: "AI coding assistants are powerful but unpredictable when requirements live only in chat history." OpenSpec makes you and the agent agree on a written plan before any code exists. If the idea of writing specs for agents is new, start with our spec-driven development guide. This post is the hands-on part.
Two ideas set OpenSpec apart. Work happens in changes, one folder per change, and each change carries delta specs: only the requirements it adds, modifies, removes or renames. When the change ships, you archive it and the deltas merge into the main specs in openspec/specs/. The README lists its philosophy as "fluid not rigid", "iterative not waterfall" and "built for brownfield not just greenfield".
We ran every CLI step below on OpenSpec 1.16.1, published on npm on November 7, 2026 (UTC), in a small test repo on November 8, 2026. We wrote the change files by hand in the exact format OpenSpec tells the agent to use, so the outputs you see are real.
How do you install OpenSpec and set up a project?
Install the CLI once, then run openspec init in each project and pick your AI tools. There is a standalone install script, an npm package and a Homebrew formula (brew install openspec):
# macOS or Linux (standalone, no Node.js needed) curl -fsSL https://openspec.dev/cli/install.sh | sh # or with npm (needs Node.js 22.12.0 or later) npm install -g @fission-ai/openspec@latest cd your-project openspec init --tools claude
Plain openspec init asks which tools to set up. --tools skips the picker. With --tools claude, our run created six skills in .claude/skills/, six slash commands in .claude/commands/opsx/ (apply, archive, explore, propose, sync and update), and openspec/config.yaml with the default spec-driven schema. Six more workflows (new, continue, ff, verify, bulk-archive and onboard) are available through openspec config profile. If skills are new to you, our Claude Code skills guide explains how Claude loads them.
The README says OpenSpec works with more than 30 AI coding tools, and the command name depends on the tool:
| Tool | Propose a change |
|---|---|
| Claude Code | /opsx:propose |
| Cursor, GitHub Copilot | /opsx-propose |
| Codex | $openspec-propose (skills only, no command files) |
| Amazon Q | @opsx-propose |
The CLI sends anonymous usage stats (command names and version, per the README). To turn this off, set OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1.
What is in an OpenSpec change folder?
A change is a folder in openspec/changes/ with four artifacts, written in this order: proposal, specs and design, then tasks. openspec status shows which ones are done and which are blocked:
| File | What it holds |
|---|---|
proposal.md | Why the change is needed, what changes, which capabilities it adds or modifies |
specs/<capability>/spec.md | The delta: requirements and scenarios this change adds, modifies, removes or renames |
design.md | Technical decisions, alternatives considered, risks |
tasks.md | Numbered task groups with checkboxes |
.openspec.yaml | Metadata: schema, created date, optional goal |
Specs are plain Markdown with a few strict rules from OpenSpec's own instructions: requirements use SHALL or MUST, every requirement needs at least one scenario, and scenarios use exactly four hash marks. The instructions warn that three hash marks "will fail silently". Here is part of the delta from our test change, add-due-dates:
## Purpose Let users give a todo a due date and list the open todos that are overdue. ## ADDED Requirements ### Requirement: Due date on a todo The system SHALL store an optional due date in YYYY-MM-DD form on each todo. #### Scenario: Invalid date - **WHEN** a user adds a todo with due date "next week" - **THEN** the system rejects it with an error
Here is the task list. OpenSpec asks for small tasks, ordered by dependency, each one stating how to verify it:
# Tasks ## 1. Due dates - [ ] 1.1 Add an optional due argument to addTodo and verify a test saves 2026-11-20 - [ ] 1.2 Reject dates that are not YYYY-MM-DD and verify a test expects the error ## 2. Overdue list - [ ] 2.1 Add overdue(list, today) and verify a test lists only open past-due todos - [ ] 2.2 Document both functions in README.md and verify the example runs
A change with no delta at all fails validation unless its .openspec.yaml sets skip_specs: true, which is meant for refactors, tooling and docs. We hit that error when we validated a change before writing its specs.
How does the OpenSpec workflow go, step by step?
The OpenSpec quickstart describes five steps: explore, propose, review, apply and archive. In Claude Code it looks like this:
- Explore (optional).
/opsx:exploreis a thinking mode. The agent reads your code and weighs options, and the quickstart says "It never writes code." - Propose.
/opsx:propose add-due-datescreates the folder and writes all four artifacts. The propose command is strict about scope: "This workflow creates planning artifacts only." It stops before any implementation, even if you asked it to build. - Review. You read the proposal, then the specs (the quickstart calls them "the highest-value read"), then the tasks. Edit the files yourself or tell the agent what is wrong. Run
openspec validatebefore you move on. - Apply. Start a fresh session, as the quickstart suggests, and run
/opsx:apply. The agent works throughtasks.mdand ticks each box as the task lands. If it runs out of context, a new session resumes at the first unchecked box. - Archive.
/opsx:archivemerges the deltas intoopenspec/specs/and moves the folder toopenspec/changes/archive/with the date in front, such as2026-11-08-add-due-dates.
The CLI does the bookkeeping in between. These are real outputs from our test, after the first two tasks were ticked:
$ openspec validate add-due-dates --strict Change 'add-due-dates' is valid $ openspec list Changes: add-due-dates 2/4 tasks just now
What happens when you archive an OpenSpec change?
Archiving merges the change's delta specs into your main specs and moves the change folder to the archive. Take care with this step, because it rewrites your main specs. After archiving, our openspec/specs/todo-due-dates/spec.md held the purpose and both requirements from the delta, and openspec list --specs counted 2 requirements.
OpenSpec warns about unfinished work but does not stop you from archiving it. On our change with two of four tasks done, archive asked first:
$ openspec archive add-due-dates Task status: 2/4 tasks Warning: 2 incomplete task(s) found. Continue? (y/N)
With --yes it archived anyway and merged both requirements, even though the code for the overdue list did not exist yet. With --json and no --yes, it returned the error code archive_tasks_incomplete. The archive skill tells the agent to warn and ask for confirmation, not to refuse: "Don't block archive on warnings - just inform and confirm". The archived change keeps its count (openspec list --archived showed "2/4 tasks"), so you can find these later, but the main spec already claims behavior that was never built.
Decide who may say yes. The quickstart's own rule is to archive "when every box in tasks.md is checked". On a team, that check should come from a person who reviewed the code, not from the agent that wrote it.
How do you track OpenSpec changes on a task board?
Give each OpenSpec change one card, store the card ID in the change's .openspec.yaml, and use config.yaml to tell the agent when to move and comment on it. The quickstart is honest about where state lives: "Progress lives in the tasks.md checkboxes. There is no hidden state." That works for one agent on one branch. A teammate on another branch, or a lead with five changes in flight, sees nothing until someone pushes. OpenSpec's answer for sharing plans across repos is Stores, which the README marks as beta. Stores are git repos too, so they share the plan. A board shows who is working on what right now and what is waiting for review.
Use one card per change, not one per task. The change is what a person reviews and archives, and the agent already tracks tasks in the tasks.md checkboxes. A card per task would be a second checklist to keep in sync. If tasks need to go to different agents, that is usually a sign the work should be two changes. (For one card per task from a Spec Kit list, see the import in our spec-driven development guide.)
This setup uses two OpenSpec features we checked in the docs and in our test, plus the Flux MCP server's tools as they are defined in its code:
- Create the card after review. Propose won't touch anything outside the plan, so ask in a separate prompt, with Flux connected to Claude Code under the name
flux:Create a Flux card for the OpenSpec change add-due-dates. Call get_board with board k3J9xQ2a to get the board UUID and the Backlog column UUID. Call create_card with the title "add-due-dates: due dates and an overdue list" and a description that names openspec/changes/add-due-dates/ and the task groups in tasks.md. Then add x-flux with the board ID and the new card's UUID to openspec/changes/add-due-dates/.openspec.yaml.
get_boardaccepts the short ID from the board's URL and returns the board UUID, whichcreate_cardrequires. New cards go to the bottom of the column. Replacek3J9xQ2awith the short ID from your own board's URL. - Keep the card ID with the change. OpenSpec's change metadata docs say a top-level key that starts with a lowercase
x-"is yours, for data another tool or your team keeps beside the change, such as a tracker id or an owner". OpenSpec ignores it,validate --strictpassed with it in our test, and it moved into the archive folder unchanged. A key without the prefix, such asflux_card, triggered an "Unrecognized key" warning.schema: spec-driven created: 2026-11-08 goal: Due dates and an overdue list x-flux: board: k3J9xQ2a card: 3f1c2a9e-0000-4000-8000-000000000000
- Tell apply and archive what to do with it. In
openspec/config.yaml,contextreaches every artifact, apply and archive, andoperationsreaches only apply and archive. In our test, all three apply lines came back inopenspec instructions apply --jsonunderoperationGuidance, which is what the apply skill reads:schema: spec-driven context: | Work is tracked on a Flux board. Each change's .openspec.yaml has an x-flux key with the board ID and the UUID of the change's card. rules: tasks: - Every task names the test or command that proves it is done operations: apply: guidance: - Before the first task, move the x-flux card to In Progress with move_card (column UUIDs come from get_board) - After each task group, add_comment on the card starting with [claude] - which tasks are done and how you checked them - When every task is done, move the card to Needs review and stop. Never move it to Done archive: guidance: - Archive only if get_board shows the x-flux card in Done. Otherwise stop and say why
Use the four columns from our kanban board for AI agents guide: Backlog, In Progress, Needs review and Done. A new Flux account starts with Backlog, Planning, In Progress, Review and Complete, so rename Review and Complete, or change the names in config.yaml to match. The agent takes a card as far as Needs review. A person checks the code against the specs, moves the card to Done, and only then runs archive. Five things to know before you rely on it:
- It is guidance, not a lock. OpenSpec's apply skill calls this guidance "prompt-level behavior contracts, not enforceable checks". Flux does not enforce column order either:
move_cardcan move a card to any column on its board. Done and archive stay safe because people follow the rule, not because the tools refuse. - The key needs the Write scope. Without it,
move_card,create_cardandadd_commentanswer "Error: write scope required". The key's owner also needs at least the member role in the workspace; a viewer gets "You don't have permission to perform this action". - Use the card's UUID.
move_cardandadd_commenttake the UUID, which is why it goes inx-fluxrather than the PROJ-42 style ID. - Agents should sign their comments. Comments posted with an API key show under the key owner's name, and
get_cardreturns comments oldest first without author names. The[claude]prefix tells readers which agent wrote what. - The comments are the record. Changes made over MCP are not written to the Flux activity log, so the signed comments, the checked boxes in
tasks.mdand the pull request are what a reviewer reads.
With several changes running at once, give each agent its own git worktree and its own change, as described in how to coordinate multiple AI coding agents. The board then shows every change in flight on one screen, and the specs in each repo stay the record of what was built.