OpenSpec Review: Spec-Driven Dev Without the Ceremony

Originally published on andrew.ooo — visit the original for any updates, code snippets that aged out, or follow-up posts.

TL;DR

OpenSpec is a CLI that gives your AI coding assistant a written contract to work against. Instead of a feature living in a chat window that you lose on the next /clear, each change gets a folder on disk: a proposal, requirement deltas, a design note, and a task checklist. Your agent writes them, you review them, and only then does anyone touch code.

It's from Fission AI, MIT-licensed, TypeScript, and — as of August 28, 2026 — sits at 66,514 GitHub stars with 1,630,659 npm downloads in the last 30 days. That download number is the more interesting one: stars measure interest, npm installs measure people actually running openspec init in a repo.

Key facts:

• 66,514 stars, 4,579 forks, 194 open issues; ~103 contributors
• v1.11.0 shipped August 26, 2026 — releases have landed roughly weekly since July
• MIT licensed, TypeScript, requires Node.js ≥ 20.19.0
• 30+ supported agents — Claude Code, Codex, Cursor, Copilot, Zed, Amazon Q, Kimi Code, MiniMax Code, Rovo Dev, TRAE, and a vendor-neutral agents target that writes to .agents/skills/
• Delta-based specs — you describe what changes, not the whole system
• Stores (beta) — cross-repo planning for teams whose features span three services
• Compare: GitHub's Spec Kit has 131,957 stars but needs Python and imposes phase gates

The short version: Spec Kit is the thorough one, OpenSpec is the one you'll still be using in week three.

The problem OpenSpec is actually solving

Everyone who has shipped real work with a coding agent has hit the same wall twice.

Wall one: the context window forgets. You spend forty minutes explaining that the legacy users_v1 table is read-only and the mobile client can't handle 409s. The agent nails the feature. Then you start a new session and it cheerfully writes a migration against users_v1.

Wall two: you can't review a diff you didn't design. When the plan lives only in a prompt, code review becomes archaeology. You end up approving things you don't fully understand, which is exactly how AI-assisted codebases rot.

OpenSpec's answer is unglamorous and correct: put the intent in the repo, in Markdown, next to the code, and make the agent read it before it writes anything. No DSL to learn:

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

SHALL and MUST are load-bearing — the validator checks for normative keywords — but that's the entire syntax budget.

The workflow: OPSX

OpenSpec rebuilt its workflow this year around OPSX, the part worth understanding before you install anything. The old design hardcoded prompt instructions inside the TypeScript package; if the AI produced bad specs, your only move was to wait for a release. OPSX moves that into schema.yaml and templates/*.md files you can edit, test, and version yourself.

The other change is philosophical. Most spec frameworks model development as phases: specify → plan → task → implement. OPSX models it as actions you can take at any time:

proposal ──→ specs ──→ design ──→ tasks ──→ implement

Those arrows are dependencies, not gates. Realize mid-implementation that the design was wrong? Run /opsx:update, revise the artifacts, keep going. The docs are blunt about why: "Linear phases fight against how work actually happens."

A full loop looks like this:

You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies. Scope it?

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist

You: /opsx:apply
AI:  ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2026-08-28-add-dark-mode/
     Specs updated. Ready for the next feature.

/opsx:explore is the underrated command. It's read-only by design — a thinking partner that reads your code and weighs options without creating artifacts. As of v1.11.0 it explicitly names any file it wants to create and waits for a separate "yes" first, because answering its own clarifying questions was previously being read as consent to write.

The default core profile ships propose, explore, apply, update, sync, and archive. Run openspec config profile if you want the expanded set (new, continue, ff, verify, bulk-archive, onboard).

Install and first run

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

cd your-project
openspec init

init asks which tools you use and generates the right command files for each — which matters, because every agent spells slash commands differently. The canonical name is /opsx:propose, but Cursor and Copilot want /opsx-propose, Amazon Q @opsx-propose, Codex $openspec-propose. init prints the correct form for the tools you picked instead of making you guess.

Then the config file, where OpenSpec earns its keep on an existing codebase:

# openspec/config.yaml
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 gets wrapped in <context> tags and prepended to every artifact's instructions (50KB limit); rules are injected only for the matching artifact. This is what stops your agent reinventing your conventions on every change — and it's plain YAML in the repo, reviewable and diffable like anything else.

The CLI side is small and CI-friendly:

openspec list                    # active changes
openspec show add-dark-mode --diff   # just the lines that actually change
openspec status --all            # every active change, one command
openspec validate --strict       # catch spec problems before archive
openspec validate --archived     # CI: fail if anything was archived unfinished
openspec archive add-dark-mode

show --diff (new in v1.11.0) fixes a genuine review problem: because a MODIFIED requirement must restate every scenario it keeps, the raw delta is mostly text identical to the main spec. --diff isolates only what changed, with --json for pipelines.

validate --archived (v1.9.0) is the one I'd wire into CI on day one. It walks changes/archive/ and exits non-zero if any tasks.md still has unticked boxes — precisely the failure mode of agent-driven work, where "done" gets declared while 2.3 and 2.4 are still open.

Delta specs are the actual differentiator

Spec Kit generates a full specification per feature — hands-on comparisons put it at 7+ files per feature, a complete description of the system as it should be. Coherent for greenfield. On a codebase with four years of history, it means the AI writes a lot of prose describing things that already exist, and review becomes auditing AI-generated documentation rather than designing software.

OpenSpec's changes are deltas against current behavior: ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED. When you archive, the deltas fold into the main specs and the change moves to archive/. Your openspec/specs/ folder becomes the accumulated current state; your archive becomes the changelog of intent.

That design choice is why the community verdict has converged on a fairly consistent split. Hidde de Smet's comparison puts it cleanly: "use Spec-Kit when you want a guided workflow, strong guardrails, and a big extension catalog. Use OpenSpec when you are working in an existing codebase and want changes to be written as deltas against current behavior." Hashrocket's team reached the same conclusion from a different angle — OpenSpec's onboarding was smoother because Spec Kit required installing a newer Python package manager first, and the team was already in Node.

The archive has a second benefit nobody advertises: a permanent, dated record of why each change happened, written before the code existed. Six months later that's worth more than the commit messages.

What the community actually says

This is not a universally loved category, and pretending otherwise would be dishonest.

The strongest critique is a widely-upvoted r/ChatGPTCoding thread arguing that spec-driven development for AI is "a form of technical masturbation" and that Spec-Kit, BMAD, and OpenSpec are all ceremony. The counterargument in the same thread is equally direct: "Different strokes for different folks, OpenSpec has been amazing for my work flow." Notably, people in that thread who dismissed SDD generally were still specific about which framework burned them — "tried spec-kit and yuck" appears more than the OpenSpec equivalent.

The most useful negative data point is a dev.to writeup titled "OpenSpec Failed My Experiment — Instructions.md Was Simpler and Faster." The author kept the OpenSpec workflow but tried to cut token costs, and concluded a single hand-written instructions file did the job for their project. That's a fair result for small, well-understood work, and it maps to the real cost model: generating a proposal, specs, design, and tasks is LLM usage on top of implementation. On a 30-minute bug fix, that overhead is the whole job.

Ry Walker's research notes land on the structural limitation: nothing in the format keeps specs synchronized with code automatically. Archive folds deltas into specs and validate checks internal consistency, but if someone bypasses the workflow and hand-edits a route, no tool notices the spec is now a lie. Specs drift. They always have.

The people getting real value are consistently working on multi-week features in codebases with existing conventions, often across more than one agent — exactly the audience the Stores beta targets.

Honest limitations

1. It costs tokens before it saves them. Four planning artifacts per change is real spend. Below roughly a day of work, a good AGENTS.md and a clear prompt is cheaper and faster.
2. Specs still drift from code. Nothing enforces that reality matches the spec. validate --archived catches unfinished work; it can't catch untruthful specs.
3. It wants a strong model. The README recommends high-reasoning models (it names Codex 5.5 and Opus 4.7) for planning and implementation. Cheap models generate specs that look right and read hollow.
4. Context hygiene is on you. The docs explicitly tell you to clear context before implementation. That's a manual discipline the tool can't enforce.
5. Stores are beta. The cross-repo story is the most compelling part for teams and the least battle-tested. Treat it accordingly.
6. 194 open issues at this velocity. Weekly releases and ~103 contributors mean things move fast; pin your version if you script around the CLI.

OpenSpec vs Spec Kit vs nothing

Greenfield project, maximum guardrails, big extension catalog? Spec Kit is the more complete toolkit. Adding features to something that already exists — which is most work? OpenSpec's delta model fits better. Small, self-contained changes? Honestly: keep your AGENTS.md and skip both.

FAQ

Is OpenSpec free?

Yes — MIT licensed, and the CLI is a free npm package. Your only cost is the LLM usage from generating planning artifacts, which is charged by whichever coding assistant you already use. There's no hosted tier or paid plan required to use it.

Does OpenSpec lock me into one AI coding assistant?

No, and this is its main advantage over IDE-bundled approaches like AWS Kiro. openspec init --tools <list> generates command files for 30+ assistants — Claude Code, Codex, Cursor, GitHub Copilot, Zed, Amazon Q, Kimi Code, MiniMax Code, Rovo Dev, TRAE — plus a vendor-neutral agents target for anything reading .agents/skills/. Specs are plain Markdown in your repo, so switching agents costs nothing.

How is OpenSpec different from GitHub's Spec Kit?

Three concrete differences: OpenSpec runs on Node instead of Python, writes deltas against existing behavior instead of full per-feature specifications (about 4 artifacts vs 7+), and has no phase gates — you can update any artifact at any point. Spec Kit is more thorough and has a bigger extension catalog; OpenSpec is built for brownfield codebases and iterates faster.

Does it work on an existing codebase, or only new projects?

Existing codebases are the explicit design target — "built for brownfield not just greenfield" is in the project's own philosophy statement. Run openspec init, fill in openspec/config.yaml with your stack and conventions, and use /opsx:onboard (expanded profile) to bootstrap initial specs from what's already there.

Can a team share specs across multiple repositories?

Yes, via Stores, currently in beta. A store is the same openspec/ shape — specs and changes — in its own git repo, shared by git push. A platform team owns requirements while product teams reference them read-only, so one feature spanning three repos gets one plan. Beta, so validate it on something non-critical first.

Does OpenSpec send my code anywhere?

The CLI collects anonymous telemetry — command names and version only, no arguments, paths, file content, or PII — and it's automatically disabled in CI. Opt out with openspec config set telemetry.enabled false, OPENSPEC_TELEMETRY=0, or the standard DO_NOT_TRACK=1. Your specs and code never leave your machine through OpenSpec; they only reach whichever LLM your coding assistant is already using.

Bottom line

OpenSpec is the least ceremonial way I've found to stop losing engineering intent to chat history: four Markdown files per change, a validator with real CI teeth, and a workflow that doesn't punish you for changing your mind mid-implementation.

It is not free — you pay in tokens and in the discipline of reviewing plans you'd rather skip. On a small fix, that trade is bad. On a multi-week feature in a codebase with conventions worth respecting, it's the difference between reviewing a design and reconstructing one.

The npm number is the honest signal: 1.63 million downloads in 30 days is not star-farming, it's people running openspec init in real repositories. Start with /opsx:explore on something you're genuinely unsure about — it's read-only, costs one conversation, and tells you within ten minutes whether this workflow fits your brain.

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

Sources

• Fission-AI/OpenSpec on GitHub — README, philosophy, comparison claims (66,514 stars, August 28, 2026)
• OpenSpec releases — v1.11.0 (Aug 26, 2026) spec diffs and batch status; v1.9.0 validate --archived
• OPSX workflow docs — actions-not-phases design, config.yaml schema
• @fission-ai/openspec on npm — 1,630,659 downloads, July 28 – August 26, 2026
• Spec-Kit vs OpenSpec — Hidde de Smet and hands-on comparison — ypyl — independent evaluations