1. What OpenSpec Is

OpenSpec is an open-source Spec-Driven Development framework maintained by Fission-AI. It does not try to teach AI new coding tricks. Instead it adds a lightweight “agreement layer” between you and the AI — before any code is written, both sides settle on what to do, in writing.

The core design:

1. Specs — Markdown documents describing how the system currently behaves, organized by capability under openspec/specs/. This is the “single source of truth.”
2. Changes — each piece of work gets its own folder (openspec/changes/<name>/) containing four artifacts: proposal, design, tasks, and delta specs.
3. Delta — rather than rewriting the whole spec, a delta describes only what is ADDED / MODIFIED / REMOVED, which lets brownfield projects adopt it cheaply.

The project philosophy is stated plainly:

1
2
3
4

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield

• Repository: https://github.com/Fission-AI/OpenSpec
• Package: @fission-ai/openspec
• Current version: v1.7.0 (second half of 2026)

Rough version history: the 0.x era began with a Claude Code-first release; 1.0.0 stabilized the CLI, spec format, and archive flow; 1.6.x brought Stores (plans in a separate repository) in beta plus custom schemas; 1.7.0 added CodeArts/Hermes/ZCode support and made skills statically distributable.

It supports 30+ AI tools, including Claude Code, Cursor, Codex, Gemini CLI, Copilot, Amazon Q, Devin, Kilo Code, and Trae. OpenSpec is itself developed with OpenSpec — the main repository’s openspec/specs/ and openspec/changes/ are living examples, and a good place to see what specs look like at real scale.

2. Why You Need It

AI coding assistants are genuinely capable, but most developers have met the spec-less experience:

• You type “add dark mode” into the chat box, and the AI immediately runs npm create vite and picks an approach you did not want
• Requirements live only in context; close the window or switch the session and the design intent evaporates, leaving the AI to improvise again next time
• Changing behavior has no notion of a diff — the AI happily rewrites whole files, so review means reading everything
• In a brownfield project you only want to touch auth/, but the AI decides it should refactor all of user/ while it is at it

OpenSpec addresses an alignment problem: pull requirements out of ephemeral chat history and into version-controllable spec files in the repository, so the AI aligns before acting.

3. Core Concepts: Five Words Are Enough

The whole mental model compresses into five sentences:

1. Specs are the truth. Files under openspec/specs/ describe how the system works now, organized by domain (auth/, payments/, ui/). Each Requirement comes with Scenarios, using the RFC 2119 keywords SHALL / MUST / SHOULD / MAY.

2. A Change is a unit of work. Any behavior change — addition, modification, removal — goes into its own folder under openspec/changes/. One change, one folder, one feature.

3. A Delta spec describes the change, not the world. Inside a change folder you do not rewrite the whole spec, only the increment: this requirement ADDED, that one MODIFIED, this one REMOVED. This is the key trick that makes OpenSpec friendly to existing systems — you describe a diff, not a target state.

4. Artifacts are generated along a dependency chain. A change contains several documents, unfolding in natural order:

   1 2	proposal ──► specs ──► design ──► tasks ──► implement why what how steps do it

5. Archiving folds the change back into the truth. When work is done, the archive operation merges the delta spec into the main spec and moves the change folder into changes/archive/ with a date stamp. The spec now describes the new reality, and the loop closes.

Two directories: specs/ is the facts, changes/ is the proposals. Archiving turns a proposal into a fact.

OpenSpec repeatedly stresses one phrase: “enablers, not gates.” Traditional spec processes are waterfalls — you cannot enter implementation until planning ends, and going back is painful. OpenSpec rejects this. The order proposal → specs → design → tasks only means “what you could do next,” not “what you must do.” Halfway through implementation and the design turns out wrong? Edit design.md and keep going. Realized the scope should shrink? Go back and update the proposal. Nothing is locked. The dependency chain exists for one reason — to give the AI context (without specs you cannot write good tasks) — not to constrain you. The cost is stated honestly too: since nothing pushes you along, you need your own discipline to keep a change focused instead of letting it sprawl.

4. Core Workflow: From Idea to Archive

The new OPSX workflow (now the default) breaks a feature into the following path, with optional steps in parentheses:

1

(/opsx:explore) → /opsx:propose → /opsx:apply → /opsx:archive

4.1 Explore — A Thinking Partner Before You Act

When to trigger it: you want to do something, but have not worked out what it should look like.

What it does:

• Reads your code baseline to understand the existing structure
• Lays out several viable approaches with their trade-offs
• Turns a vague idea into a concrete plan sketch
• Produces no spec files at all — it is a “no-strings experiment”

Once you have clarity, you can move naturally to /opsx:propose.

4.2 Propose — AI Drafts, You Review

Run /opsx:propose add-dark-mode and the AI generates the whole set of planning artifacts at once:

1
2
3
4
5
6

openspec/changes/add-dark-mode/
├── proposal.md    # why, scope, non-goals
├── specs/         # delta requirements and scenarios for this change
│   └── ui/spec.md
├── design.md      # technical approach, trade-offs, rollback plan
└── tasks.md       # implementation checklist

You read it, change a few things, approve — and only then is the AI allowed to implement. The payoff of this step: catching “wrong direction” in a 200-word proposal costs almost nothing, whereas catching it after the AI has written 400 lines costs real money.

4.3 Apply — Work the Task List, Revise Anytime

• Implement item by item against the checkboxes in tasks.md
• If design.md no longer holds, edit it directly and continue
• Check off each finished item; progress stays visible
• Other supported commands: /opsx:update (revise artifacts), /opsx:continue (generate artifact by artifact), /opsx:ff (fast-forward through the full set)

4.4 Archive — Merge the Delta, Land It as Truth

1

/opsx:archive

• Merges the change’s ADDED / MODIFIED / REMOVED deltas into the main specs under openspec/specs/
• Moves the change folder to changes/archive/2025-01-23-add-dark-mode/ with a date stamp
• Removes from the main spec any scenarios that were never implemented (and if a delta conflicts, it stops and reports the difference rather than claiming everything is “in sync”)

After archiving, your spec says what the system looks like now, and you can start the next piece of work.

4.5 Directory Layout at a Glance

After initialization, the openspec/ directory in a repository usually looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

openspec/
├── config.yaml          # project config: schema, context, rules
├── specs/               # main specs: the truth of current behavior
│   ├── auth/spec.md
│   └── ui/spec.md
├── changes/             # changes in flight
│   ├── add-dark-mode/
│   │   ├── proposal.md
│   │   ├── specs/
│   │   ├── design.md
│   │   └── tasks.md
│   └── archive/         # archived changes
│       └── 2025-01-23-some-feature/
└── schemas/             # optional: custom templates
    └── your-schema/
        ├── schema.yaml
        └── templates/

SKILL.md files that the AI assistant can call directly are generated under .claude/skills/, exposed to the harness as commands like /opsx:propose and /opsx:apply.

4.6 OPSX vs the Legacy Workflow

The repository’s legacy workflow is driven by /openspec:proposal commands; OPSX is the refactored new standard. One table for the differences:

The key insight of OPSX: work is not linear. OPSX stops pretending it is.

For exploration-driven work, OPSX also offers the expanded profile: /opsx:new (scaffold only), /opsx:continue (one artifact at a time), /opsx:ff (generate everything at once), /opsx:verify (validate an implementation), /opsx:bulk-archive (archive in bulk), /opsx:onboard (a guided tour of the whole flow). Switch with openspec config profile, apply with openspec update.

5. Spec Format: Plain Markdown, No Special Syntax

This is the most appealing part of OpenSpec — a spec file is just Markdown with conventions, no DSL to learn:

1
2
3
4
5
6
7
8
9

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

Modifications use ## MODIFIED Requirements, removals use ## REMOVED Requirements. The AI writes these files, you review them, and any line you cannot understand is a problem with that spec — observable, testable, and handoff-ready are hard requirements.

Keyword strength matters too:

Write specs with MUST/SHALL by default; use SHOULD only when you really mean “unless there is a good reason not to.”

6. Project Configuration: Let the AI Understand Your Context

openspec/config.yaml is optional but strongly recommended. It injects project-specific context and constraints into everything the AI generates:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript  

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

context is wrapped in <context>...</context> tags and injected at the start of every artifact’s instructions; rules apply only to the matching artifact; the schema determines the set of artifact IDs. This way the AI does not have to guess your stack or testing style every time.

7. Comparison with Similar Tools

The official docs honestly provide a three-way comparison:

For users, the most meaningful comparison may be the relationship with Superpowers — both emphasize “align before writing code,” but along orthogonal paths:

They can be combined: OpenSpec governs “what to do,” Superpowers governs “how to do it.”

8. Installation and Supported Platforms

Requires Node.js 20.19.0 or later.

1
2
3
4
5
6

# global install
npm install -g @fission-ai/openspec@latest

# enter your project and initialize
cd your-project
openspec init

init asks which tools you use (claude, cursor, codex…), then writes the corresponding SKILL.md and command files into your project. After that, the /opsx:* family of commands appears in your AI tool. To upgrade:

1
2

npm install -g @fission-ai/openspec@latest
openspec update   # refresh the CLI-generated instruction files

The docs also offer a “let the AI do it” option: paste the installation prompt into your coding assistant, and it will install the CLI, run openspec init, and verify the result.

The shape of command files per tool (all 30+ are in Supported Tools):

Note: tools spell slash commands differently — Claude Code prefers opsx:propose, Cursor prefers opsx-propose, Amazon Q uses @opsx-propose — but the concept is the same. When openspec init finishes, it prints the exact usage hint for your tool.

9. Usage Advice

9.1 First Run

1
2
3

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init          # choose claude / cursor / codex / ...

Then tell your AI:

1

/opsx:propose add-rate-limiting

The point is not how fast the AI works, but that it first generates proposal.md, the spec additions and removals, the design trade-offs, and the task list — you read for two minutes, change three words, and only then approve it to write code. That one-time alignment cost cuts the rework rate of the whole project down sharply.

9.2 Context Hygiene

The OpenSpec docs call this out specifically: spec-driven development benefits from a clean context window. Clear unrelated chat out of the AI session before starting implementation, and keep good session discipline throughout — long context dilutes the clarity of planning just as much.

9.3 Model Choice

The official recommendation is a high-reasoning model for both planning and implementation: it matters most in the planning phase, where high-reasoning models differ noticeably on “recognizing synonymous requirements,” “surfacing trade-offs,” and “task granularity.” Implementation puts less pressure on the model, but it is best to stay in the same tier to avoid a discontinuity.

9.4 Telemetry

OpenSpec collects anonymous usage statistics (only command names and version numbers — no arguments, paths, content, or PII). It is disabled automatically in CI. To turn it off entirely:

1
2
3

export OPENSPEC_TELEMETRY=0
# or honor the Do Not Track convention
export DO_NOT_TRACK=1

10. FAQ

Q: Does OpenSpec slow the process down?

A: It does add one step — write a short plan before starting. But in most cases that 200-word proposal, which takes two minutes to read, saves you from reworking hundreds of lines of wrong code. For genuine one-line fixes, skip the process; OpenSpec does not force it.

Q: My project is brownfield with hundreds of thousands of lines. How do I use it?

A: This is exactly where OpenSpec shines. Delta specs mean you do not need to write a spec for the whole system first — writing ADDED/MODIFIED deltas for just the small piece of behavior you are changing (say auth/session-expiry) is enough. A 50,000-line legacy application can adopt specs one change at a time without stopping to write exhaustive documentation first.

Q: How is this different from something like AGENTS.md in a README that “tells the AI the repo rules”?

A: AGENTS.md is a repository-level static prompt — it tells the AI “this project uses Prettier.” OpenSpec’s specs are behavioral, currently valid, implemented, and maintained through the archive loop. One tells the AI the rules; the other tells the AI the reality. They are orthogonal and can be used together.

Q: How does a team work across repositories?

A: Since OpenSpec 1.6 there is Stores (beta): move planning into a separate planning repository and share it with all your members and all your agents via git push. The platform team owns the specs, product teams reference them read-only, and planning exists before the code. (See the Stores beta guide.)

Q: How do I contribute?

A: Small fixes go straight to a PR. For new features or structural changes, the project asks you to file an OpenSpec change proposal first, so intent and goals align before code is written — its own rule, applied to itself. AI-generated code is accepted, provided you note the coding agent and model version used.

11. Summary

The core insights of OpenSpec:

1. The AI being able to write code does not mean it knows what you want. Write the alignment down first, then act.
2. Markdown specs plus deltas are the lowest-friction way to introduce specs into a brownfield project. You describe the change, not the world.
3. A fluid, non-linear workflow is how real work happens. Phase gates are the past; dependencies should be enablers, not gates.

The complete work cycle:

1
2
3
4

1. (/opsx:explore)   thinking and options
2. /opsx:propose     AI drafts proposal/spec/design/tasks
3. /opsx:apply       implement against the task list, revise freely
4. /opsx:archive     merge deltas, archive the change

If you already use an AI coding assistant and have lived through the rework of “I explained for ages and the AI went the wrong way” or “the code runs but the design makes no sense,” OpenSpec is worth one try. Start with /opsx:propose add-dark-mode and see whether the AI plans before it acts.