OpenSpec: A Lightweight Spec Layer So You and Your Agent Agree Before Writing Code

AI coding assistants are fast, but they are unpredictable when the requirements live only in chat history. You describe a feature, the agent generates a lot of code, and three messages later it has quietly forgotten half of what you asked for. OpenSpec, from Fission-AI, is built to close that gap by adding a thin spec layer between the idea and the implementation.

The pitch is simple: agree on what to build before any code is written. Instead of one long prompt, OpenSpec turns a change into a small set of artifacts — a proposal, specs, a design note, and a task list — that both the human and the agent can read, review, and follow. It is an npm-installable CLI (@fission-ai/openspec), it is MIT-licensed, and it works with the AI tools you already use through generated slash commands.

This post covers what OpenSpec is, why the spec layer matters, how the propose → apply → archive workflow and its “delta specs” actually work, a concrete worked example, how it stacks up against GitHub’s Spec Kit, AWS’s Kiro, and the heavier Spec Kitty, plus its real tradeoffs. A note on honesty up front: the README’s tagline calls it “the most loved spec framework,” which is a self-description, not a measured fact — treat it as marketing, and judge the tool on the mechanism below.

What it is

OpenSpec is a spec-driven-development (SDD) tool aimed at AI coding assistants. Its job is to take the requirements that would otherwise be scattered across a chat log and pin them down as version-controlled Markdown artifacts, so the agent has an explicit, reviewable target instead of a vague prompt. The project’s own framing is that it “adds a lightweight spec layer so you agree on what to build before any code is written” (README).

The philosophy, taken straight from the README, is worth quoting because it sets expectations:

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

That “brownfield not just greenfield” line is the differentiator. Most real software work is not building from scratch; it is changing an existing system. OpenSpec is designed around that reality, which shows up most clearly in its delta-spec model below.

Why it matters

The case for a spec layer is really a case against relying on the context window as your source of truth.

• Requirements survive the conversation. When a context window fills up, agents tend to forget earlier requirement details — third-party write-ups describe noticeable degradation as context fills, which is exactly the failure spec-driven development is meant to prevent (Redreamality, “OpenSpec Deep Dive”). Pinning requirements into files keeps them stable across a long session.
• You catch logic errors before code. Because the agent produces a proposal and a task list first, you review the plan — the cheapest place to fix a mistake — before a single line is written.
• Each change stays organized. Every change gets its own folder with its proposal, specs, design, and tasks, so a feature reads like a self-contained mini-project rather than a diff with no context.
• It works fluidly. There are no rigid phase gates; you can update any artifact at any time, which fits the way requirements actually shift mid-implementation.
• It is tool-agnostic. OpenSpec generates slash commands and skills for the assistant you already use, supporting 25-plus tools and growing rather than locking you into one editor.

How it works

OpenSpec is filesystem-first. It rejects databases and SaaS dependencies in favor of plain Markdown that lives alongside your source in Git, which is what lets the specs act as living documentation. After openspec init, your project gains an openspec/ directory with two pillars: a specs/ folder that holds the current, accepted behavior of the system (the source of truth, organized by domain like auth/ or payments/), and a changes/ folder where in-progress work lives, one folder per change.

The change folder is the unit of work. Each one collects four artifacts that build on each other — a proposal.md explaining why and what is changing, a specs/ subfolder holding the delta, a design.md for the technical approach, and a tasks.md implementation checklist. The lifecycle is a loop: propose the change, apply it, then archive it back into the source of truth.

The mechanism is “fluid” because nothing forces you through those steps in a fixed order — the docs frame the model as actions you take rather than locked phases, so you can revise the proposal after starting implementation, or extend the tasks list mid-flight (Anton Gubarenko, “Spec-Driven Development with OpenSpec”). The newer artifact-guided commands live under the opsx namespace; an expanded profile adds commands like /opsx:new, /opsx:continue, /opsx:verify, and /opsx:bulk-archive if you opt into it.

Getting started

OpenSpec needs Node.js 20.19.0 or higher. You install the CLI globally, then initialize it inside your project, which generates the openspec/ structure and the slash commands for whichever assistant you picked.

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

From there you drive everything from your AI assistant. Tell it what you want and the propose command scaffolds the change folder:

/opsx:propose Add dark theme support to the iOS app

It also works with pnpm, yarn, bun, and nix, and openspec init walks you through selecting your primary tool (Claude Code, Cursor, Copilot, Windsurf, and many more), generating the right command files for each. When you upgrade the package later, run openspec update inside each project to regenerate the agent instructions.

In practice

OpenSpec earns its keep on changes that are bigger than a one-file edit but smaller than a full RFC — adding dark mode, reworking onboarding, instrumenting analytics, replacing a legacy flow. The delta-spec model is what makes those manageable: instead of rewriting the entire product spec, you describe only what is changing, in sections marked ADDED, MODIFIED, or REMOVED Requirements. As Anton Gubarenko puts it, “full spec = what the product is; delta spec = what this feature changes” (Gubarenko).

Here is the full loop on a concrete change. You propose dark-mode support and OpenSpec scaffolds the folder:

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
     Ready for implementation!

The delta that lands in changes/add-dark-mode/specs/ does not redescribe the whole app — only the new and changed behavior, written as testable Given/When/Then scenarios:

## ADDED Requirements

### Requirement: Manual Theme Override
The application MUST allow the user to choose Light, Dark, or System in Settings.

#### Scenario: Select dark theme manually
- GIVEN the user opens Settings
- WHEN the user selects Dark theme
- THEN the application immediately applies dark appearance
- AND the selection persists across app launches

## MODIFIED Requirements

### Requirement: Accessible Theme Colors
The application MUST use theme-aware colors that preserve readable contrast in both appearances.

You review those artifacts — the cheapest moment to catch a mistake — then implement against them:

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

The iterative part is where it beats a single big prompt. After the first pass you usually find gaps — charts still look wrong in dark mode, a legacy view ignores the theme. Rather than re-prompting from scratch, you extend the delta with a MODIFIED requirement and a few follow-up tasks, then apply again from a better source of truth (Gubarenko). When the change is done and tested, you archive it:

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

Archive is the step that keeps documentation honest: the CLI merges the delta into the main specs/ directory — appending what was added, overwriting what was modified — so specs/ always reflects the system’s current behavior before the next change begins. There is also an optional dashboard for viewing the state of your changes, surfaced via a collapsible preview in the README.

How it compares

OpenSpec positions itself explicitly against two alternatives, and it is worth adding a third.

Against GitHub Spec Kit, the README’s own framing is that Spec Kit is “thorough but heavyweight” — rigid phase gates, a lot of generated Markdown, and a Python setup — while OpenSpec is lighter and lets you iterate freely. That is a fair characterization of a real difference in philosophy rather than a put-down; Spec Kit’s structure is an asset for teams that want strong guardrails.

Against Kiro (AWS), the README’s argument is about lock-in: Kiro is a powerful, fully integrated IDE experience, but you are tied to its editor and, per the README, a narrower model selection, whereas OpenSpec runs inside whatever tools you already use. Kiro’s integrated, visual approach is genuinely nicer for people who want SDD without touching the filesystem; the trade is portability.

It is also worth contrasting Spec Kitty, which sits at the heavier, more governed end of the spectrum: multi-agent orchestration and stronger process enforcement rather than OpenSpec’s deliberately minimal, single-folder approach. If you want maximum structure and built-in governance, Spec Kitty leans that way; if you want the least ceremony that still gives you a spec, OpenSpec does. I dig into that head-to-head separately in Spec Kitty vs OpenSpec.

Dimension	OpenSpec	Spec Kit	Kiro	Spec Kitty
Weight	Light, CLI + Markdown	Heavier, more scaffolding	Full IDE	Heavier, governed
Best at	Brownfield iteration	Structured greenfield	Visual, integrated SDD	Multi-agent, enforced process
Change model	Isolated change folder + delta specs	Spec files, phase gates	UI-managed	Orchestrated workflow
Lock-in	Works with 25+ tools	Tool-agnostic, Python setup	Tied to its IDE/models	Heavier framework

One independent data point on where the wider field stands: the ThoughtWorks Technology Radar reportedly placed OpenSpec in its “Assess” ring, noting interest in the approach while flagging that SDD workflows generally remain elaborate and opinionated (via Redreamality). Treat that as one analyst’s positioning, not a verdict.

Performance

There are no published benchmarks here, and you should be suspicious of anyone who quotes a number — OpenSpec’s “performance” is qualitative, about predictability rather than throughput. The mechanism that’s supposed to pay off is context efficiency: because the agent reads a focused slice (the project overview, the current tasks.md, and the relevant delta spec) instead of the whole codebase or a sprawling chat log, the context it works from stays smaller and more on-target (Redreamality). The claimed wins are less context bloat, fewer hallucinated requirements, and output that drifts less from the original intent across a long session.

That is a plausible story and it matches the experience reports, but it is exactly that — a design rationale and practitioner observation, not a measured speedup. The README itself only offers usage guidance rather than figures: it recommends high-reasoning models for both planning and implementation, and stresses “context hygiene,” clearing your context before implementation. If predictability is the metric you care about, OpenSpec is making a credible bet; if you want hard numbers, they do not exist yet.

Tradeoffs

The honest cons follow directly from the “lightweight, fluid” design.

• Lighter means fewer guardrails. With no rigid phase gates, the discipline is on you and your team to actually write and review the specs rather than skip to /opsx:apply. Where Spec Kit enforces process, OpenSpec trusts you to keep it.
• Less opinionated structure can drift across a team. Because OpenSpec is relaxed about exactly how specs are shaped, larger teams can end up with inconsistent artifacts unless they agree on conventions — the flip side of flexibility.
• It still adds process. For a one-line fix, propose → apply → archive is more ceremony than the task deserves. The value shows up on real features, not typos.
• It leans on strong models and clean context. The README is explicit that it works best with high-reasoning models and benefits from good context hygiene; on weaker models, or with a cluttered context window, results will be less reliable.
• Opt-out telemetry is on by default. OpenSpec collects anonymous command names and version (no arguments, paths, content, or PII, and it is disabled in CI). It is easily disabled with OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1, but it is on until you turn it off.

Takeaway

OpenSpec is the answer to “my agent is capable but forgets what I asked for.” It adds the smallest spec layer that still works: a change folder, four artifacts, and a propose → apply → archive loop, with delta specs that describe only what’s changing so it fits the brownfield reality of modifying existing systems. Reach for it when a change is big enough to be worth aligning on first and you want the agent working from a reviewable target instead of a fading chat history.

Skip the ceremony for trivial edits, and don’t expect benchmarks — its payoff is predictability, which you’ll feel rather than measure. If you want heavier guardrails, look at Spec Kit or Spec Kitty; if you want a fully visual, integrated experience, look at Kiro. But if you want spec-driven development with the least ceremony that still keeps you and your agent honest, OpenSpec is a strong, free, MIT-licensed place to start.