OpenSpec: a lightweight open spec layer for AI coding agents

Why put a spec layer above the code

The five-step OpenSpec workflow

1. /opsx:explore — understand the problem and the existing code before writing anything
2. /opsx:propose — draft proposal.md, specs/, design.md and tasks.md
3. /opsx:apply — let the agent implement the tasks
4. /opsx:verify — check that the implementation matches the spec
5. /opsx:archive — archive the finished change

The five-step list above is the one the project's own homepage shows. The repository's getting-started page lists a slightly different set and moves /opsx:verify into an expanded profile — both are quoted in the commands section further down, with the dates I read them.

Install it

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

What OpenSpec puts on your disk

One directory at the root of your project. Knowing which folder is which is most of what you need.

openspec/
├── specs/                       source of truth, how the system behaves now
│   └── <domain>/spec.md         e.g. specs/auth/, specs/payments/
├── changes/                     one folder per proposed change
│   └── <change-name>/
│       ├── proposal.md          why and what
│       ├── design.md            how
│       ├── tasks.md             checkbox list
│       └── specs/
│           └── <domain>/spec.md delta: what this change moves
└── config.yaml                  optional project configuration

The four artifacts are the whole model: proposal.md carries intent and scope, the delta specs carry the requirements, design.md carries the technical decisions, and tasks.md is the checklist the agent ticks off as it implements.

A delta spec is a markdown file marked in sections rather than a rewrite. It says only what moves:

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- **GIVEN** a user with 2FA enabled
- **WHEN** the user submits valid credentials
- **THEN** an OTP challenge is presented

## MODIFIED Requirements
### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

On archive, ADDED requirements are appended to the main spec, MODIFIED ones replace what was there, REMOVED ones are deleted, and the change folder moves under openspec/changes/archive/.

Source: docs/getting-started.md in the Fission-AI/OpenSpec repository, read 2026-09-21 (file shown as 291 lines, 9.97 KB, last commit 2026-09-16). The same artifact roles are worded identically in the repo README and in the Jama Software guide.

What happened when we ran it

Everything in this section was produced on one Windows 11 Pro machine on 2026-09-21 by installing the package and running the commands. The commands are verbatim, the output under them is verbatim, and every block carries its exit code and elapsed time. Where something failed, the failure is left in.

The machine and the version

$ node --version
v22.22.2
$ npm --version
10.9.7
$ where node
C:\Users\Administrator\.workbuddy-ai\binaries\node\versions\22.22.2-2\node.exe

Node was already above the 20.19.0 floor, so nothing was installed before this run — v22.22.2 is what was already there. The OS is Windows 11 Pro, build 28000; systeminfo printed its own headers in Chinese because that is the machine's display language, which is also why two "command not found" checks below are reported as exit codes rather than quoted messages.

Installing it

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

added 80 packages in 1m

23 packages are looking for funding
  run `npm fund` for details
exit=0  elapsed_ms=70693

$ openspec --version
1.13.1

$ npm list -g @fission-ai/openspec --depth=0
C:\Users\Administrator\.workbuddy-ai\binaries\node\versions\22.22.2-2
└── @fission-ai/[email protected]

80 packages, about 71 seconds. A second confirmation of the version sits in a file the installer wrote: .claude/skills/openspec-propose/SKILL.md carries generatedBy: "1.13.1" in its frontmatter.

init, and the first thing that broke

This machine has no agent CLI installed, and bare openspec init refuses to guess:

$ openspec init
Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or openspec config set telemetry.enabled false
× Error: No tools detected and no --tools flag provided. Valid tools:
  amazon-q
  antigravity
  ... (39 tool ids listed, trimmed here)
  zcode
  agents

Use --tools all, --tools none, or --tools claude,cursor,...
Tool not listed? Use --tools agents: the vendor-neutral target that writes .agents/skills/ for any assistant.
exit=1  elapsed_ms=8306

$ ls -la
(empty - the directory was still empty, nothing was written)

Passing the tool explicitly got it through:

$ openspec init --tools claude --no-animation
- Creating OpenSpec structure...
▌ OpenSpec structure created
- Setting up Claude Code...
√ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Note: 6 more workflows are available (new, continue, ff, bulk-archive, verify, onboard).
Add them with `openspec config profile`.

Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues
exit=0  elapsed_ms=6007

The tree it actually wrote

.claude/commands/opsx/apply.md
.claude/commands/opsx/archive.md
.claude/commands/opsx/explore.md
.claude/commands/opsx/propose.md
.claude/commands/opsx/sync.md
.claude/commands/opsx/update.md
.claude/skills/openspec-apply-change/SKILL.md
.claude/skills/openspec-archive-change/SKILL.md
.claude/skills/openspec-explore/SKILL.md
.claude/skills/openspec-propose/SKILL.md
.claude/skills/openspec-sync-specs/SKILL.md
.claude/skills/openspec-update-change/SKILL.md
openspec/changes/archive/.gitkeep
openspec/config.yaml
openspec/specs/.gitkeep

15 files. Four differences against the tree drawn above, all of them measured:

• No spec is created by init. openspec/specs/ holds only a .gitkeep; specs appear at archive time.
• The folder init creates under changes/ is archive/, with a .gitkeep. A change folder only appears after openspec new change.
• 12 of the 15 files land outside openspec/, under .claude/ — six slash commands and six skills. The tree above only drew the openspec/ half.
• There is no project.md.

The six commands installed are apply, archive, explore, propose, sync and update — no verify. The CLI itself prints "6 more workflows are available (new, continue, ff, bulk-archive, verify, onboard)". That is the same discrepancy noted above, and the installed output lands on the repository's side of it.

Where the slash command got stuck, and what I did instead

$ where claude   -> not found, exit=1
$ where codex    -> not found, exit=1
$ where cursor   -> not found, exit=1

There is no agent on this machine to type /opsx:propose into. But the slash command is an ordinary markdown file at .claude/commands/opsx/propose.md, and its frontmatter says allowed-tools: Bash(openspec:*) — the slash command is not a program, it is a script that shells out to the CLI. So I ran the CLI calls it lists, by hand: openspec context --json, then openspec new change, then openspec status --change ... --json, then openspec instructions <artifact> --change ... --json for each artifact.

What I did not do, stated plainly: I never ran /opsx:propose inside a real agent session. The four artifacts below were written by me from the templates the CLI returned. They are not model-generated output.

One change, end to end

$ openspec new change add-health-endpoint
- Creating change 'add-health-endpoint' with schema 'spec-driven'...
Created change 'add-health-endpoint' at openspec\changes\add-health-endpoint\
Schema: spec-driven
Next: openspec status --change add-health-endpoint
exit=0  elapsed_ms=3691

$ openspec status --change add-health-endpoint
- Loading change status...
Change: add-health-endpoint
Schema: spec-driven
Change root: C:\Users\Administrator\WorkBuddy AI\Claw\_run\openspec\changes\add-health-endpoint
Progress: 0/4 artifacts complete

[ ] proposal
[-] specs (blocked by: proposal)
[-] design (blocked by: proposal)
[-] tasks (blocked by: specs, design)

Next: openspec instructions proposal --change "add-health-endpoint" --json
exit=0

The CLI hands back a template per artifact. For the delta spec it is this:

# Spec Delta

## Purpose

## ADDED Requirements

### Requirement: <!-- requirement name -->

#### Scenario: <!-- scenario name -->
- **WHEN** <!-- condition -->
- **THEN** <!-- expected outcome -->

Four artifacts later, and one more failure on the way: validate does not take --change.

Progress: 4/4 artifacts complete
[x] proposal
[x] specs
[x] design
[x] tasks

All planning artifacts complete!
Next: openspec instructions apply --change "add-health-endpoint" --json

$ openspec validate --change add-health-endpoint
error: unknown option '--change'
(Did you mean --changes?)
exit=1  elapsed_ms=1807

$ openspec validate --all
- Validating...
✓ change/add-health-endpoint
Totals: 1 passed, 0 failed (1 items)
exit=0

$ openspec change validate add-health-endpoint
Warning: The "openspec change ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec list", "openspec validate --changes").
Change "add-health-endpoint" is valid
exit=0  elapsed_ms=2998

$ openspec list
Changes:
  add-health-endpoint     0/7 tasks     just now

Archive, including the refusal

Archiving with the task list still empty does not go through:

$ openspec archive add-health-endpoint
Task status: 0/7 tasks
Warning: 7 incomplete task(s) found. Continue? (y/N) × Error: 7 incomplete task(s) found for change 'add-health-endpoint', and no answer could be read from stdin.
Fix: Complete the tasks or rerun with openspec archive add-health-endpoint --yes
exit=1  elapsed_ms=2496

After ticking all seven checkboxes in tasks.md:

$ openspec list
Changes:
  add-health-endpoint     ✓ Complete    just now

$ openspec archive add-health-endpoint --yes
Task status: ✓ Complete

Specs to update:
  health-check: create
Applying changes to openspec/specs/health-check/spec.md:
  + 3 added
Totals: + 3, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-health-endpoint' archived as '2026-09-21-add-health-endpoint'.
exit=0  elapsed_ms=6428

What the disk looks like after archive

openspec/changes/archive/.gitkeep
openspec/changes/archive/2026-09-21-add-health-endpoint/.openspec.yaml
openspec/changes/archive/2026-09-21-add-health-endpoint/design.md
openspec/changes/archive/2026-09-21-add-health-endpoint/proposal.md
openspec/changes/archive/2026-09-21-add-health-endpoint/specs/health-check/spec.md
openspec/changes/archive/2026-09-21-add-health-endpoint/tasks.md
openspec/config.yaml
openspec/specs/.gitkeep
openspec/specs/health-check/spec.md

Three things measured here:

• The archived folder is renamed with a date prefix: 2026-09-21-add-health-endpoint.
• Its .openspec.yaml holds schema: spec-driven and created: 2026-09-21.
• The main spec's first line changes from # Spec Delta to # health-check Specification, and ## ADDED Requirements becomes ## Requirements. ## Purpose is kept as written. The delta file inside the archive folder is left untouched.

$ openspec list --specs
Specs:
  health-check     requirements 3

$ openspec list
No active changes found.

Three things that bit us

1. init will not guess your agent. With none installed it exits 1 and writes nothing; --tools claude (or none, all, agents) is required.
2. Bare openspec validate and openspec show exit 1 in a non-interactive shell — that is a refusal, not a pass. And validate --change is not an option; it is --changes, with openspec change validate <name> for a single item, which now prints a deprecation warning.
3. archive reads tasks.md and refuses when items are open; with no interactive stdin it cannot read the y/N answer, so --yes is the only way past it.

Measured on 2026-09-21 on a Windows 11 Pro machine with Node v22.22.2 and @fission-ai/openspec 1.13.1. Every block above is a copy of what the terminal printed; the one trimmed line (the 39 tool ids) is marked as trimmed. Not run: the /opsx:* slash commands inside a real agent session, any implementation code, and any screenshots. The seven ticked checkboxes were edited by hand.

The commands, where to type them, and how each agent spells them

Two different places, and mixing them up is the most common early stumble.

One discrepancy I hit while checking, and I am not going to paper over it: the project's own homepage lists five commands — explore, propose, apply, verify, archive — while the repository's getting-started page lists explore → propose → apply → sync → archive and puts verify in the expanded profile instead. The README states the default core profile "includes propose, explore, apply, update, sync, and archive". The homepage footer showed v1.13.0 and the repo's latest release showed v1.13.1. Two official surfaces, two lists; I read both on 2026-09-21 and they did not match.

The same command is spelled differently depending on the agent, which is the other thing that trips people up:

Sources: the command table and the "run in your terminal / run in your AI assistant's chat" distinction come from docs/getting-started.md; the per-agent spellings are quoted from the README, which adds "openspec init prints the right form for the tools you picked". Both read 2026-09-21.

Hard requirements and what it collects

• Node.js 20.19.0 or higher. Stated in the README Quick Start. A floor, not a recommendation.
• No MCP dependency. "The framework needs a current Node.js runtime and no Model Context Protocol (MCP) dependency to run."
• Telemetry is on by default and narrow. The README says it collects "only command names and version", with "no arguments, paths, content, or PII", and that it is "Automatically disabled in CI". Three ways to turn it off, any one of which is enough:
• Stores, the cross-repo feature, is in beta. Both the README and the getting-started page mark it beta.

openspec config set telemetry.enabled false
export OPENSPEC_TELEMETRY=0
export DO_NOT_TRACK=1

Sources: Fission-AI/OpenSpec README (read 2026-09-21) for the Node floor and telemetry wording; Jama Software's OpenSpec guide, published 2026-07-30, for the no-MCP line.

The same number, reported on three dates

Nobody in the top ten put figures next to dates. This is the one comparison I can actually source: GitHub stars, as reported by three different people at three different times.

The first two rows are other people's recollection in a comment thread, not measurement, and the January figure is hedged by the speaker himself. I am reporting them as claims with dates, not as a growth curve.

Sources: news.ycombinator.com/item?id=49734264 (199 points, 99 comments; read 2026-09-17) for the first two rows; openspec.dev and github.com/Fission-AI/OpenSpec read 2026-09-21 for the third.

Three conversions, with the arithmetic shown

A rate, a monthly figure and a size limit, each turned into the unit you would actually reason in. Every input is named; every result is arithmetic on someone else's claim, not a measurement of mine.

How it compares, and who says so

That table is the Jama Software guide's, published 2026-07-30; I am reproducing its structure and its facts with attribution, not its wording. The comparison that matters for most people is narrower, and two independent sources land on the same split:

• Regulated or compliance-heavy work: the Medium author (2026-06-16) writes that if you are in a regulated industry and need rules like "every API endpoint requires OpenAPI documentation" enforced, Spec Kit's constitution model "might suit you better — and that's a legitimate tradeoff". Jama's guide (2026-07-30) says the same from the other side: OpenSpec's artifacts "aren't a governed requirements record on their own".
• Large, long-lived, multi-developer codebases: the sharpest criticism on the Hacker News thread is that "specs rot and end up being more pain than they are worth" there, while one-shot greenfield generation is where they work. A second commenter on the same thread, who had used it for a few months, said long-lived specs in the repo were useless to him but the change process was "super valuable" on a single complex feature.
• Brownfield: Thoughtworks put it in the Assess ring of its Technology Radar (published 2026-04-15) and singled out "its focus on spec deltas rather than defining a complete specification upfront, making it well-suited for existing systems".

Sources, in order: Jama Software guide 2026-07-30; Apurv Sheth on Medium 2026-06-16; Hacker News thread 49734264, read 2026-09-17; Thoughtworks Technology Radar, published 2026-04-15.

Who should not use this

Every item above is a claim someone else published on a date, not my own testing. That is the honest version of this section.

The source log, as a file you can keep

Every dated claim on this page, plus the ones that did not fit: date, where it came from, what it said, and whether I read it myself or am repeating someone else.

The file lives at https://specmatter.com/openspec-source-log.csv, served as text/csv. It opens in Excel, Numbers or any text editor.