Six weeks ago I installed @fission-ai/openspec on a brownfield TypeScript codebase three engineers had been editing for two years. Yesterday I shipped a fourteen-file change in ninety minutes from a two-hundred-line spec. No merge conflicts. No review escalation. The PR description was the proposal and a sixty-line spec delta; the code diff was its consequence. The senior engineer who reviewed it didn’t read the code — he read the spec delta and approved.
That sentence would have sounded like a sales pitch two years ago. In May 2026 it’s the third week in a row I’ve shipped something that way, and I’ve started to think it’s not the OpenSpec that’s magic. It’s that the methodology finally has a tool that takes its own claims seriously.
This is the fourth post in an arc I’ve been writing. Context engineering was the runtime discipline. Spec-driven development was the design-time philosophy. Evals was the verification layer. Each of those posts pointed forward to a question I hadn’t answered yet: but how do you actually run this in a real codebase, with real humans, on a Tuesday? OpenSpec is the first tool I’ve used that answers that question honestly.
The thesis is sharper than people are comfortable with. OpenSpec is the first spec-driven framework that treats specs the way Git treats code: as a filesystem state machine with branches, isolation, and atomic merges. That isn’t a feature. It’s the entire reason it works.
What OpenSpec is, exactly
OpenSpec is an open-source CLI from Fission-AI, founded by Tabish Bidiwale, launched via Y Combinator earlier this year, and sitting at fifty thousand GitHub stars roughly six months after release. The NPM package is @fission-ai/openspec. It’s TypeScript, requires Node 20.19+, and the latest stable is v1.3.1 (April 21, 2026 — about a month old as I write this).
The founder’s framing is worth quoting because it cuts through three years of LLM hype with one sentence:
Generating code is now cheap. Correctness is still expensive.
That’s the entire diagnosis. The bottleneck for shipping AI features in 2026 isn’t model capability — Opus 4.7 and Codex 5.5 can produce a working implementation from almost any well-shaped spec. The bottleneck is getting to a well-shaped spec, holding it stable across sessions, isolating concurrent changes, and merging them back to a source of truth without contamination. That’s a systems problem, not a prompting problem.
OpenSpec solves it the way a backend engineer would — with the filesystem, no database, markdown everywhere, and a workflow that maps almost one-to-one to Git Flow. Here’s the canonical layout:
project_root/
└── openspec/
├── AGENTS.md # behavioral rules for any AI tool reading the repo
├── project.md # global context — stack, conventions, constraints
├── specs/ # Source of Truth — current system behavior
│ ├── auth-login/spec.md
│ ├── payment-checkout/spec.md
│ └── ...
└── changes/ # isolated workspace for in-flight proposals
├── add-oauth-login/
│ ├── proposal.md # the "why" and the "what"
│ ├── design.md # the technical approach
│ ├── tasks.md # implementation checklist
│ └── specs/ # spec deltas: ADDED / MODIFIED / REMOVED
└── archive/
└── 2026-04-12-add-rate-limiting/
└── ...Two directories carry the entire model. specs/ is the current state of the world — the system’s source of truth, organized by capability. changes/ is the in-flight workspace — every proposal is its own folder, fully isolated, with its own delta against the current specs. When a change is approved and applied, its deltas merge back into specs/, and the proposal folder moves to changes/archive/[date]-[name]/. The archive is immutable. That’s it. That’s the whole filesystem contract.
Everything else — the CLI, the slash commands, the AI-tool integrations — is interface over that contract. You can delete every JavaScript file in node_modules and you still have a coherent SDD codebase, because the methodology lives in the directory structure, not in the tool.
The four-phase state machine
The CLI exposes a small set of slash commands that move a change through four phases. Inside an AI tool like Claude Code or Cursor, you type the command and the AI does the work; you review.
| Phase | Command | Files produced / changed | What happens downstream |
|---|---|---|---|
| 1. Propose | /opsx:propose <feature> | openspec/changes/<feature>/ with proposal.md, design.md, tasks.md, specs/ deltas | A new isolated workspace exists; nothing in the source-of-truth has changed yet |
| 2. Define | openspec validate | No new files; reports spec syntax / scenario errors | Static analysis on the spec delta before any code is written |
| 3. Implement | /opsx:apply | Source code changes, task checkboxes flipped | AI executes tasks.md strictly against the agreed spec; you review code diffs and spec deltas together |
| 4. Archive | /opsx:archive | specs/ updated with merged deltas; proposal moves to changes/archive/[date]-<feature>/ | Source of truth reflects new system state; archived proposal is permanent history |
A concrete end-to-end:
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md (rationale, success criteria)
✓ design.md (theme context, CSS variables, persistence)
✓ tasks.md (8 tasks across 3 components)
✓ specs/theme/spec.md (ADDED: 4 scenarios)
You: openspec validate
✓ All scenarios well-formed
✓ No conflicts with existing specs
You: /opsx:apply
AI: ✓ 1.1 Add theme context provider
✓ 1.2 Create toggle component
✓ 2.1 Add CSS variables for dark palette
...
You: /opsx:archive add-dark-mode
✓ Specs merged into openspec/specs/theme/
✓ Proposal archived to openspec/changes/archive/2026-05-21-add-dark-mode/The whole loop, from “I want dark mode” to “dark mode is in main with a spec,” is one terminal session. The spec is the durable artifact; the code is its consequence. The archive is the history.
Why filesystem-as-state-machine is the right call
The cleverness here isn’t in the CLI. It’s that someone finally sat down and asked: what would Git look like, if Git versioned behavior instead of code? And then implemented it without a database, without a service, without a centralized server — just files in a directory and a four-command state machine.
The mapping is one-to-one with intuitions every backend engineer already has.
| Git concept | OpenSpec equivalent | Notes |
|---|---|---|
main branch | openspec/specs/ | The source of truth; current state of the world |
| Feature branch | openspec/changes/<feature>/ | Isolated workspace; doesn’t contaminate main until merged |
| Diff | Spec delta (ADDED / MODIFIED / REMOVED scenarios) | Reviewable as text, line-level history |
| Merge | /opsx:archive | Atomic; deltas applied, proposal moved to history |
| Git log | openspec/changes/archive/ | Append-only history of every change with its rationale intact |
| Pre-commit hook | openspec validate in CI | Catches malformed specs before they hit review |
Once you see the mapping, every other SDD tool looks under-architected. GitHub Spec Kit is heavyweight and rigid; it forces phase gates and inline-edits the source-of-truth specs as you go, which means concurrent proposals from two engineers will collide on the same file. AWS Kiro locks you to the Kiro IDE and to Claude models in particular — fine if you’re already an AWS shop, fatal if you aren’t. Tessl is a purist position (“code is reconstructed from spec”) that’s philosophically pure and operationally painful — most real codebases have hand-written code that has to coexist with generated code. BMAD, Google’s Antigravity, and the handful of other SDD frameworks shipping in 2026 each make a different bet, but almost all of them assume greenfield — a new project, an empty repo, a clean slate.
Brownfield is where the work actually is. Every team I respect is shipping into a codebase that’s been edited for years, by people who left, with conventions that don’t match the README, in directories named for products that were renamed twice. OpenSpec’s whole architecture is built for that reality. The specs/ directory can be retrofitted onto an existing project — there’s even a documented retrofitting mode where you prompt the AI to reverse-engineer specs from existing code, producing baseline documentation for systems that never had any. That’s the actual unlock. Not “spec-driven from day one” — spec-driven from year three.
A backend architect reading this should notice that what OpenSpec is actually shipping is a workflow engine over a content-addressed store, with the filesystem doing the addressing. The whole thing fits on a USB stick. There is no service to operate, no consensus protocol to debug, no API to version. It’s the leanest possible implementation of a real idea, and that’s why it’s already winning the SDD ecosystem.
The PR shape changes downstream of this. In the old world, a reviewer opens a PR, sees a 600-line diff, scrolls through it, hopes nothing important is hiding in the middle, and approves. In an OpenSpec-shaped PR, the body is proposal.md + design.md + the spec delta. The reviewer reads sixty lines of spec, asks one question about an ambiguous scenario, and approves. The 600-line code diff is glanced at as a sanity check — it’s the consequence of an agreed change, not the change itself. This is the workflow change Spec-Driven Development gestured at; OpenSpec is the first tool that actually delivers it on a brownfield team.
How this hits component design
OpenSpec is described and demoed primarily by backend-leaning engineers, which has obscured something worth saying: it’s a quietly excellent frontend tool.
The reason is the file layout. Each behavioral capability gets its own folder under openspec/specs/. For a component-heavy frontend, that maps to:
openspec/specs/
├── ui-button/spec.md
├── ui-form-field/spec.md
├── auth-login-form/spec.md
├── checkout-cart/spec.md
├── nav-language-switcher/spec.md
└── ...Each spec.md contains scenarios written in GIVEN / WHEN / THEN format — for example, for a login form:
SCENARIO: 2FA-enabled user submits valid credentials
GIVEN the user has 2FA enabled
AND the user has submitted a valid email and password
WHEN the form is submitted
THEN the server returns an OTP challenge
AND the form transitions to the OTP entry state
AND the email/password fields are disabled
SCENARIO: Form submission with invalid email format
GIVEN the email field contains "not-an-email"
WHEN the user blurs the field
THEN the field shows an inline validation error
AND the submit button remains disabledThat’s not a new format. It’s the same data shape your Playwright tests already use. It’s the same data shape Storybook play functions already use. It’s the same data shape your QA team already writes user stories in. The reason most frontend teams don’t write specs is not that the format is unfamiliar — it’s that the format had no canonical home. OpenSpec gives it one.
What this unlocks for the frontend:
- A11y, i18n, design tokens, and responsive constraints become first-class spec content instead of scattered comments. “The button must reach minimum touch-target 44×44 on mobile” stops being a Slack message and becomes a scenario that’s reviewed when the spec is reviewed.
- A designer can ship a UX proposal as a spec delta while an engineer ships a data-layer proposal as a separate spec delta. The two never touch the same file. They merge independently into
specs/. There is no merge conflict because there is no shared mutable state — every proposal is isolated by design. - Component refactors stop being “I rewrote the form” and start being “I MODIFIED two scenarios and ADDED one.” Reviewers can see what behavior changed. If a scenario didn’t change, the behavior didn’t change, and the reviewer can trust the implementation.
Where it strains — and I’d be selling you something if I didn’t say this — is on heavily visual work. Animation timing, layout-as-art, micro-interactions that depend on motion and color decisions: these don’t fit cleanly into GIVEN / WHEN / THEN. You still need visual-regression evals, screenshot diffs, design-system stories. OpenSpec doesn’t replace those. But it does mean that the behavioral layer — what does this component do, when, to whom, with what outcome — has a canonical home, which means it stops fighting for space with the visual layer.
The frontend architect’s tell here is that
GIVEN / WHEN / THENis byte-for-byte the same data shape your Playwright spec is already using. You’re not learning a new format. You’re learning where to put the one you have so it stops being orphaned in a folder nobody reads.
This is also where the evals discipline meets OpenSpec naturally. Every scenario in a spec is, mechanically, an eval input. A pipeline that reads openspec/specs/**/spec.md, extracts scenarios, and runs them as Playwright tests against a deployed preview is a weekend project. Once it exists, the spec stops being aspirational — it’s verified on every PR, and any divergence between spec and implementation is a CI failure, not a code-review escalation.
Context engineering by another name
The first time I read the OpenSpec docs, I had the specific sensation of recognizing an old idea wearing new clothes.
The docs are explicit about it: “When context usage exceeds 40%, AI performance significantly degrades, with previous requirement details forgotten.” That’s not an OpenSpec finding; it’s a known property of long-context LLMs in 2026, and it’s the entire reason context engineering is the discipline that matters. The interesting thing is what OpenSpec does about it.
The OpenSpec workflow is, at runtime, a load-on-demand context strategy. When the AI starts a session, it reads three files: openspec/project.md (global stack, conventions, ~200 lines), openspec/changes/<active>/tasks.md (the current focus, ~50 lines), and the specific openspec/specs/<capability>/spec.md files the task references (~100 lines each). That’s roughly 500–1,000 tokens of curated, high-density context — not 50,000 tokens of “here’s the entire repo, figure it out.”
Every problem context engineering identifies — context window dilution, hot/warm/cold tiering, token economics, eviction strategy, planning context vs execution context — is being solved here by a directory layout. The hot tier is tasks.md. The warm tier is the referenced spec.md files. The cold tier is the rest of specs/ and the entire archive/, available to load on demand but not paid for by default. You’re not configuring a context pipeline. You’re using a tool that has the right pipeline baked into its file structure.
There’s also a memory story. Plan mode disappears when the model is restarted; conversation history evaporates between sessions; even the best long-context model doesn’t remember what you decided last Tuesday. Specs solve this without ceremony: they’re files, they’re versioned, they’re durable, they’re trivially loadable. The “memory” of an OpenSpec project is the specs/ directory. The “thinking” of an OpenSpec project is the changes/ directory. Each is bounded, inspectable, and survives restarts. That’s what every agent framework I’ve used has been trying to build out of vector stores and KV caches, and OpenSpec ships it as .md files in a folder.
There’s a more subtle property here that took me a couple of weeks to appreciate. Because OpenSpec specs are written in GIVEN / WHEN / THEN, every scenario is naturally eval-shaped. You can scrape the entire specs/ tree, treat each scenario as a test case, and feed them to your eval harness as the canonical correctness criteria. You don’t write evals separately — they are the spec, in a structured-enough form to be machine-extractable. This is the unification I argued for at the end of the evals post, and OpenSpec is the first tool that gets there incidentally rather than through ceremony.
An AI architect already knows what’s going on here: this is load-on-demand context engineering wearing a CLI hat. The interesting thing is that it teaches the discipline to engineers who don’t know they need it. Six months from now, the engineer who uses OpenSpec daily and never reads a paper about context engineering will be a context engineer, by habit, without ever having heard the term.
A practical note on models. OpenSpec works with twenty-five-plus AI tools, but it does not work equally well with all of them. The specs are markdown that requires reasoning to produce well — naming capabilities, decomposing tasks, writing scenarios that cover the edge cases — and cheap models produce shallow specs. The community consensus, which matches what I’ve seen across two production codebases, is: Opus 4.7 or Codex 5.5 for proposing and applying. Smaller models can handle archive and validate. If you wire a Haiku-tier model up to /opsx:propose, you’ll get specs that look plausible and miss the third edge case, every time. Pay for reasoning where reasoning matters.
Five rules I’ve earned shipping with OpenSpec
Numbered because they’re earned in two production codebases over six weeks, not derived from a docs page.
1. openspec validate blocks CI from day one, not “later.” Validation is the spec equivalent of type-check. Without it, malformed scenarios sneak into specs/ and a week later you have a “spec” that’s actually unparseable prose, and your spec-to-eval pipeline silently skips half of them. Add openspec validate as a required step in your pre-commit hook and as a blocking CI check on the first day you adopt the tool. Not the second day. The first.
2. project.md is short and specific, not long and aspirational. It’s the global context every agent reads first, on every session. Cap it at two hundred lines. Name the stack (“Next.js 16, Tailwind 5, Postgres, Drizzle ORM”). Name the conventions (“we use Result types, not throw”). Name the negations (“no use of any in TypeScript; no eval; no direct DB access from handlers”). Skip the marketing. Skip the team mission statement. The agent is not your investor.
3. The archive is immutable. Never edit openspec/changes/archive/*. Treat it like Git history. If a past decision needs to be revisited, you write a new proposal that supersedes it — the new proposal references the old one, and the archive grows. The day someone edits an archived proposal “just to fix a typo” is the day your history becomes unreliable, and a few months later you’re debugging a regression and the archive lies to you. Don’t.
4. Review the spec delta, not the code diff. This is the highest-leverage workflow change I’ve made in 2026, and it took me three weeks to internalize. The PR body should be the proposal, the design summary, and the spec delta — that’s what humans read. The code diff is a sanity check at most. If the spec delta is right and the code passes the validator and the evals, the code is right; if the spec delta is wrong, the code is also wrong, but the code was wrong because the spec was wrong, and fixing the code without fixing the spec just defers the bug. Reviewers who read the spec delta first ship better code than reviewers who read the code first.
5. Don’t use OpenSpec for exploratory work. This is the same caveat I named in Spec-Driven Development, with twice the force. You cannot spec what you do not yet understand. If you’re in the research phase — figuring out whether an approach will work, sketching API shapes, learning the failure modes — write code by hand, read what comes out, then extract a spec from what worked. Spec-after, not spec-first. The mistake I see new adopters make is reaching for OpenSpec on day one of a research spike. That’s how you end up with a fifty-line spec for a thing that, two days later, you realize should be three different things. Use it for known work, not unknown work.
Where this still falls apart
Honest accounting. I would be selling you a tool, not a methodology, if I stopped at the rules.
- Highly visual / animation-heavy work doesn’t fit
GIVEN / WHEN / THENcleanly. Keep your visual regression suite. OpenSpec is for the behavioral layer, not the aesthetic layer. - Research-phase code is still better written by hand and spec-extracted later. Don’t fight this.
- Cheap-model setups produce shallow specs. If your AI budget is haiku-tier across the board, you’ll have to be the one writing scenarios that catch edge cases, and the tool becomes a productivity drag instead of a multiplier. Pay for the high-reasoning model where it matters — propose, apply, validate. Cheap out on archive if you must.
- Ecosystem fragmentation is real. SpecKit, Kiro, BMAD, Antigravity, Tessl, and OpenSpec all want to be the SDD framework you adopt, and they don’t interoperate cleanly. Pick one. Commit your team to it. Switching costs are higher than the docs admit; you’re not just learning a CLI, you’re encoding the team’s whole change discipline into the tool’s shape.
- Telemetry is opt-out, not off by default. OpenSpec collects anonymized command-name and version data unless you set
OPENSPEC_TELEMETRY=0orDO_NOT_TRACK=1. For most teams that’s fine. For teams in regulated environments or with strict data-handling policies, it’s a one-line config to add to your shell profile and your CI — but you have to know to add it. - Brownfield retrofitting works, but isn’t free. The advertised “ask the AI to reverse-engineer specs from your code” workflow does work — I’ve used it on a six-thousand-file codebase — but the first pass produces specs that are descriptive, not prescriptive. They tell you what the code does, not what it should do. You then have to do a second pass with a human in the loop to convert those descriptive specs into ones that encode actual intent. Plan for that. Don’t ship the first-pass specs as your source of truth.
Honest framing: OpenSpec is the right tool for ninety percent of work in a mature 2026 codebase, and the remaining ten percent matters. A senior engineer is the one who can tell which is which.
The career angle
“Show me your eval suite” was the question I started asking in AI-engineering interviews this year. “Show me your OpenSpec workflow” — or your SpecKit, or your Kiro, but some SDD operating model with real shape — is the question that’s joined it in the last two months. The quality of the answer tells me more about a candidate than any other single signal.
The market hasn’t priced this yet. Engineers who can articulate a coherent spec-driven operating model — what lives in project.md and what doesn’t, where the change boundaries are, how PR review shifts, how evals integrate — are still single-digit-percentages of the candidate pool I see. The premium will compress as the discipline becomes standard practice, the same way unit-testing standardized between 2005 and 2015. My estimate is eighteen months before fluency in some flavor of SDD becomes table stakes for senior AI-engineering roles.
The 80/20, if you read nothing else: pick the production AI feature you own. Adopt OpenSpec on it this week. Retrofit specs for the existing behavior in two passes — descriptive first, then a human-edited prescriptive pass. Run one full proposal-to-archive cycle on a real change. You will discover in about a week that your old workflow had three places where you were guessing — about intent, about scope, about who was supposed to verify what — and OpenSpec turned all three of them into files you can point at. That discovery is the entire skill.
The deeper point
The lesson isn’t “use OpenSpec.” It’s that when a methodology gets a tool this good, the people who already understood the methodology compound their leverage ten times over, and the people who didn’t get to learn the methodology by using the tool. That asymmetry is the engineering-career story of 2026.
Spec-driven development was a philosophy three years ago. It became a practice in 2025. In 2026 it’s becoming an operating system, with OpenSpec as the leanest implementation of that system shipped to date. The interesting question is no longer “is spec-driven development worth doing?” It’s “which SDD operating model am I going to commit my team to, and how fast can I retrofit the codebase I already have?”
If you want to go deeper, the courses below cover the parts of this discipline I teach most often: Claude Code Mastery: Agentic Coding for Engineers for the daily slash-command workflow inside the tool that pairs best with OpenSpec, Building Agents with the Claude Agent SDK for building agents that consume specs as first-class inputs and produce them as outputs, Building MCP Servers & AI Tool Integrations for extending the OpenSpec workflow through MCP-served capabilities, and Building LLM-Powered Apps: RAG & Agents for wiring GIVEN / WHEN / THEN scenarios from your specs into a working evals harness on production traffic.
