OpenSpec (Part 1): Spec-Driven Development, One Change at a Time

At the end of the second BMAD article I asked you what to write next. One of the options was "other SDLC frameworks for agents, such as OpenSpec". I was still undecided, so before choosing I looked around, and one source settled it for me: the Thoughtworks Technology Radar.

This article is the first of a short series on OpenSpec. I stay on the theory: what problem it solves, the project context, the mental model, the loop and the commands. The practice, on a real codebase, comes in the next article. As in the previous series, what follows is a personal view, not a verdict.

Why OpenSpec: the Thoughtworks Radar

Before the Radar, a few words on who writes it, because this is why I trust the signal.

Thoughtworks is a global technology consultancy, founded in Chicago in 1993. I have a great esteem for this company. Whatever I read on its site, or on the blogs of its people, is for me something to study, not just to read. The reason is in the ideas that were born there, or were first written down by its people:

• Martin Fowler is its Chief Scientist. He wrote Refactoring, he is one of the signatories of the Agile Manifesto, and his site is still where many of these ideas are published first.
• Zhamak Dehghani introduced the Data Mesh in 2019, in an article on martinfowler.com, while she was a consultant at Thoughtworks.
• James Lewis and Martin Fowler wrote in 2014 the article that defined the microservices architectural style.
• Selenium was born there in 2004, as an internal tool by Jason Huggins. CruiseControl, one of the first continuous integration servers, was created by Thoughtworks people too.
• Birgitta Böckeler, Distinguished Engineer at Thoughtworks, wrote in 2025 the article that classifies spec-driven tools as spec-first, spec-anchored and spec-as-source. I use her terms later in this article, and I already used them in my first article on Spec Kit.

The Radar comes from the same place. It is written by the Thoughtworks Technology Advisory Board, a group of senior technologists who meet twice a year and discuss what they have seen on real projects. It is not a survey and not a vendor ranking: it is the opinion of people who build software for clients. This is the whole point for me. When a tool moves on the Radar, it is because someone used it.

The Technology Radar is published twice a year. Every entry (a "blip") sits in one of four rings: Adopt, Trial, Assess, Caution. The move from Assess to Trial is the signal I look at, because it means teams used the tool on real projects in the meantime.

Here is how a blip moves, and where the AI SDLC frameworks stand in the November 2026 edition:

The picture also shows the frameworks that are named in the Radar texts but have no blip of their own, BMAD among them. Let me go through the two I care about.

OpenSpec moved from Assess to Trial. In the April 2026 edition Thoughtworks placed it in Assess. The blip started from a problem I described in my first article on Spec Kit: predictability and maintainability suffer when requirements live only in ephemeral chat histories. It described OpenSpec as an open-source framework that adds a lightweight specification layer, with a workflow often reduced to three steps (propose, apply, archive). Its judgment was: "OpenSpec is a developer-friendly framework worth assessing." It ended with an invitation to keep watching the native capabilities of the agents and to re-evaluate the need for this kind of tooling.

In the November 2026 edition the blip moved to Trial. The new text calls OpenSpec "a lightweight spec-driven development framework that works with any coding agent", and it gives the reason for the move: several Thoughtworks teams have reported success with it since April. Two points of that text struck me:

• Brownfield. It works well on existing codebases. Teams report more predictable agent output and fewer unintended changes than with bare prompting.
• Spec-anchored. The key difference from GitHub Spec Kit and Kiro is that changes are deltas against a persistent source-of-truth spec.

The blip also has a caution, and I think it is fair to report it: spec files are Markdown that agents generate in large quantities. Archiving the change deltas helps, but keeping the persistent spec healthy still needs discipline.

GitHub Spec Kit was placed in Assess and has not moved. The Spec Kit blip is from April 2026 and is not on the current edition: a blip appears again only when it changes ring. It notes that "two broad camps are emerging": teams that use coding agents with minimal structure, and teams that prefer defined workflows and detailed specifications. Teams experimented with Spec Kit mostly on brownfield systems, with the constitution as a key concept. They also met a challenge, instruction bloat (the agent instruction set kept growing as context was added), and some rough edges: unnecessary defensive checks and verbose Markdown output that adds cognitive load.

I wrote three articles on Spec Kit (theory, building RoomBook, porting it to NestJS) and two on BMAD. A tool that moved forward while the one I know best did not was the signal I wanted. The choice was made.

Let's Start From the Problem

You ask an agent for a feature. It builds something close. You correct it, it fixes it, and three sessions later nobody remembers what was agreed, least of all the agent, whose context was wiped in the meantime. The code is the only record, and the code does not say why.

Spec Kit and BMAD answer this with documents written before the code. Both work, as I showed in the previous articles, but both tend to think in terms of a whole feature or a whole product: a constitution and a full specification in Spec Kit, a PRD, an architecture and epics in BMAD. On an existing codebase this raises a practical question: do I have to document everything that exists before I can change one thing?

OpenSpec answers no. This is the whole point of the tool.

What Is OpenSpec?

OpenSpec is an open-source framework by Fission AI. At the time of writing the current version is 2.0. It adds a lightweight specification layer between you and the agent: before any code is written, you and the agent agree on what will change, and the agreement is written as Markdown in your repository, next to the code. When the work is done, the agreement is folded into a permanent description of how the system behaves.

The project states its philosophy in five lines:

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

OpenSpec is made of two parts, and I think the split is the most interesting design choice:

• A CLI (openspec). It creates the folders, validates the documents, merges the specs and archives the changes. It does the deterministic bookkeeping.
• A set of skills installed into your agent (openspec-propose, openspec-apply-change, and so on). They tell the agent how to think and write at each step, and they call the CLI to get their instructions and to check their work.

The agent writes the content. The CLI owns the structure. This is why the output looks the same from one change to the next, and from one agent to another (Claude Code, GitHub Copilot, Cursor and many others).

Project Context: The Closest Thing to a Constitution

Before the mental model, there is one file that every change reads: openspec/config.yaml. openspec init creates it (Step 0 below), and it is the place for every customization. If you come from Spec Kit, its role will look familiar.

context holds the background facts: stack, architecture rules, test commands, the language of the artifacts. It reaches every artifact, and also apply and archive. rules adds instructions for one artifact, only when that artifact is written. A short example:

schema: spec-driven

context: |
  Angular 22 web app, Firebase Auth and Firestore, no server code.
  Tests: Vitest unit tests, Playwright e2e. `npm run check` must pass.
  Write all artifacts in English.

rules:
  design:
    - Any change to the data model needs a design.md with a migration note.
  tasks:
    - A task changing what the user sees includes a Playwright test.

Similar to the Spec Kit constitution, but not the same. I checked the sources of both tools, because the resemblance is strong. In Spec Kit, /speckit-constitution writes .specify/memory/constitution.md: in my first Spec Kit article I described it as "the guiding principles against which every later phase is evaluated". The Radar blip on Spec Kit says a useful constitution captures project scope, domain context, technology versions, coding standards and repository structure. This is almost the same list I would put in context. The goal is the same too: give the agent the shared context of the project once, so every step respects it.

The differences are in the form and in how the file is used:

	Spec Kit constitution	OpenSpec config.yaml
Form	A Markdown document of principles, with a Governance section	YAML: context, rules per artifact, guidance for apply and archive
Created by	A dedicated command, /speckit-constitution	openspec init, then edited by hand
Used by	The plan template, with a "Constitution Check" gate that must pass before research; violations must be justified	The prompt of every step: rules "add to the built-ins and never replace them"
Changes	Amendments are reviewed and recorded in the document	Edit the file; it takes effect on the next run
After the code	According to Spec Kit's methodology document, analyze can evaluate the artifacts against it	verify never receives the rules: it checks the code against the artifacts

For me the difference is this: the constitution is a set of principles with a gate, config.yaml is context with instructions. Neither is enforced by a program; both are text that the agent reads. Spec Kit writes an explicit check into its plan template, while OpenSpec relies on the artifacts and on your review. The OpenSpec documentation is honest about it: when the rules do not steer the agent consistently, it suggests forking the schema.

A historical note: before version 1.0, OpenSpec had an openspec/project.md, closer in spirit to a constitution. Version 1.0 replaced it with config.yaml. If a tutorial tells you to fill in project.md, it is an old one.

Two warnings from the documentation. Keep the file short, because everything in it lands in the agent's context. And never edit the skill files: openspec update overwrites them without a backup.

Profiles. The same configuration layer decides which skills you get. The default profile installs six core skills: explore, propose, apply-change, update-change, sync-specs, archive-change. An optional set adds new-change and continue-change (one artifact at a time, for delicate changes), ff-change, verify-change, bulk-archive-change and onboard (a guided first tour). I would add at least verify and onboard when learning.

openspec config profile
openspec update

One practical note before you read other tutorials: OpenSpec has had three generations of commands. /openspec:proposal is pre-1.0, /opsx:propose is 1.x, and the skills openspec-propose are 2.0. Many posts online describe the older ones.

The Mental Model: Specs, Changes, Deltas, Archive

Four ideas carry the whole system. The picture shows them on disk: what each command creates, changes or moves under openspec/, for one change called add-csv-export.

Specs. openspec/specs/ is the source of truth for what the system does today. It is organized by capability, one coherent area of behavior: user-auth, data-export. Each capability has one spec.md, made of requirements ("The system SHALL...") and scenarios (WHEN/THEN examples that could become tests). Specs describe behavior, not implementation: no component names, no queries, no libraries.

Changes. openspec/changes/<name>/ holds one unit of work: a bug fix, a feature, a behavior tweak. It is not a git commit. It is a folder with the planning documents of that work: proposal.md (why, and what changes), the delta specs (what "done" means), design.md (how, only when needed) and tasks.md (the steps, each with its own verification). Several changes can be in flight at the same time.

Deltas. A change does not rewrite the spec of a capability. It writes only the differences, under four headings: ADDED, MODIFIED, REMOVED and RENAMED Requirements. To fix one redirect, you describe that one redirect, without first writing forty pages about everything around it.

Archive. When a change is implemented, archive merges every delta into the main specs and moves the change folder to openspec/changes/archive/YYYY-MM-DD-<name>/. Nothing is deleted. The archive is the history of how the system got where it is.

Mental Model: specs/ is the truth, changes/ is the work in progress, archive/ is the history. A change is a proposal to move the truth; archive is the moment the truth moves.

Spec-First or Spec-Anchored

The Radar uses the word "spec-anchored", and it links it to the article by Birgitta Böckeler I mentioned at the beginning. I think it deserves a short explanation, because it is the real difference from the tools I covered before.

• Spec-first. You write a spec, the agent builds from it, and then the spec is mostly left behind. The next feature gets a new spec. This is how I used Spec Kit: one folder per feature, each one a snapshot of a moment.
• Spec-anchored. The spec outlives the change. Every change is written as a delta against it, and when the change is done the spec is updated. Over time the spec keeps describing the system as it is, not as it was planned.

BMAD sits in between: its PRD and architecture are long-lived, but they describe the product as planned. OpenSpec has no product plan at all. The specs grow from the changes you make.

The Loop, Step by Step

Before the steps, one thing I want to highlight. I did not find it written anywhere, but it became clear after my first experiments: there are two ways to walk the loop, and the commands you type depend on which one you choose.

One session, no /clear. You run every step in the same chat. The agent remembers what you explored, decided and corrected, so short commands are enough: "propose the change we just discussed", then /openspec-apply-change with no arguments. It is the simplest way, and for a small change it works well. The price is a context that keeps growing, while the documentation recommends a clean context for apply.

A fresh chat between steps, with the next command suggested by the harness. Before each /clear, you ask the agent for the next command:

I am going to run /clear. Give me the exact next command, with the change name
and everything it needs to work in a fresh chat.

Every skill already ends by naming the next step, so the agent knows where you are. Asking for the full command makes it write the change name and, before propose, the decisions that live only in the conversation. You copy the command, run /clear and paste it. The command carries the decisions across the /clear.

For me the second way is the safer one when the conversation was long or the change is delicate. The first is fine for a quick fix. In both cases, check the "Using change: <name>" line the skill prints before it continues.

Step 0: Install and initialize (once per machine, once per project):

npm install -g @fission-ai/openspec@latest
openspec init --tools claude

init creates openspec/ (with config.yaml, an empty specs/ and an empty changes/archive/) and installs the skills. In version 2.0 the skills are written once under .agents/skills/ and linked into each tool's folder (.claude/skills/ for Claude Code). The specs start empty, and this is intentional.

Step 1: Explore (optional; think before planning):

/openspec-explore
Users ask for a way to export their data. Look at how the data is stored
and tell me the options.

Explore is a thinking mode. The agent reads the code, asks questions, compares options and challenges assumptions. It never writes code, and it writes nothing at all unless you ask it to. On unfamiliar code, the documentation calls it the habit that saves the most pain.

Step 2: Propose (the plan, in one pass):

/openspec-propose add-csv-export

The agent asks what it needs, then writes the change folder with every artifact, in dependency order: proposal, delta specs, design if needed, tasks. Then it stops. No code yet.

Step 3: Review (the human, not a skill):

openspec validate add-csv-export --strict
openspec show add-csv-export --deltas-only
/openspec-update-change add-csv-export CSV only for now, no JSON

This is the step that matters most, and it is the only step in the loop that is not a skill: it is you. The documentation suggests reading the proposal first (the right problem, at the right size?), then the specs (would I accept them as the definition of done?), then the tasks (do they cover the specs, and nothing more?). validate catches what the eye misses. update-change applies a correction and carries it through to the dependent artifacts; with no request, it runs a coherence review of the artifacts against each other.

Step 4: Apply (a fresh chat is recommended, not required):

/clear
/openspec-apply-change add-csv-export

The agent works through tasks.md in order, writes the code each task needs and ticks each box (- [ ] to - [x]). If it is interrupted, a new session resumes at the first unchecked box: progress lives only in the checkboxes. If a task is unclear, or needs more than the spec says, apply stops and asks instead of guessing.

Step 5: Verify (optional; report only):

/openspec-verify-change add-csv-export

Verify reads the artifacts and the code, and changes nothing. It scores completeness, correctness and coherence, lists the issues as CRITICAL, WARNING or SUGGESTION, and says whether the change is ready to archive. Review checks the plan before the code. Verify checks the code against the plan.

Step 6: Archive (the truth moves):

/openspec-archive-change add-csv-export

Archive validates the change, warns about unchecked tasks, previews the spec updates and asks before merging. Then it moves the folder into the archive. OpenSpec never commits for you: git stays a separate concern.

The minimum path is three skills: propose, apply-change, archive-change. Everything else adds thinking (explore), control (update, verify) or convenience.

Files Are the Memory

There is one rule behind every step, and I found it the most useful idea in the documentation: until propose has written the artifacts, the conversation is the only record of what you decided; after that, the files are.

In practice:

• Before propose, do not clear blindly. If you explored for twenty minutes and then run /clear, the decisions are gone. Either propose in the same session, or ask for the next command first, so it carries the decisions in full.
• After propose, clear freely. The plan is on disk. Apply is even recommended in a fresh chat, so the implementation starts on a clean context.
• A decision made in chat during review must go into the artifacts. Otherwise it does not survive the next /clear.

This is the same principle as in BMAD, where I wrote that the files are the memory, not the conversation. OpenSpec makes it explicit at the level of a single change.

Built for Brownfield

The brownfield guide of OpenSpec has a sentence that I would put at the top of any adoption plan: you do not document your whole codebase to start; you write specs only for what you are about to change.

What follows from it:

• Specs accumulate. The first change documents the slice it touches, the next one its own slice. The spec of an area becomes thorough after several changes there, which is exactly when you want it thorough.
• Resist back-filling. In the words of the guide: "Writing specs for code you aren't changing feels productive and usually isn't." Those specs go stale, because nothing forces them to track reality.
• Existing documents are source material, not specs to convert. A PRD is a different artifact with a different job. You point the agent at the relevant section when a change needs it.
• Start small and real. The first change should be something you would do this week anyway: not a toy, not a rewrite.

There is no tool that reverse-engineers specs from existing code, and I think this is a deliberate choice, not a gap.

What OpenSpec Gives You

A truth that follows the code. The specs are updated at every archive, so they describe the system as it is, not as it was planned.

A small entry cost on existing code. No baseline to write. The first spec is born from the first change you needed anyway.

Proportionate documents. Four artifacts at most per change, and design.md only when it earns its place.

A history you can read. Every archived change keeps its proposal, design and tasks. "Why is it like this" has an answer in a folder.

What OpenSpec Does Not Give You

The other side, with the same sincerity as before:

There is no approval gate. Propose stops before code, and that pause is the review. But OpenSpec has no "approved" state and no approve command. openspec status tells you which artifacts exist, not whether anyone read them, and nothing stops you from applying a plan nobody reviewed. This fits "fluid, not rigid", but the discipline is entirely yours. In BMAD the checkpoints are built into the workflow.

There is no backlog. A change exists only once someone proposes it. Work you decide to postpone has to live somewhere else: a tracker, a note, a marker in the code.

There is no product view. OpenSpec does not help you decide what the product should be. No brainstorming, no PRD, no UX. If you start from a vague idea, you need something before it.

Specs can still sprawl. The Radar caution is real: agents write a lot of Markdown. Deltas and archiving help, but someone has to read the specs and keep them lean.

The format is strict in silent ways. A scenario must use exactly four hashes (####): with three it is silently ignored. A MODIFIED requirement must contain the whole requirement: what you leave out disappears at archive. validate --strict is not optional for me.

The Role of the Human

Moment	What the human decides
Explore	Which option to pursue
Propose	The name, the scope and the constraints of the change
Review	Whether the specs are the definition of done
Apply	What to do when the agent stops on a gap
Verify	Whether the findings block the archive
Archive	Whether the truth should move

Bounded autonomy, not full automation. I wrote this sentence for Spec Kit and for BMAD, and I think it applies to OpenSpec even more, because here no workflow forces the stop. The tool assumes you will stop anyway.

Takeaways

1. The Radar move is a signal worth following. OpenSpec went from Assess to Trial because teams used it, not because of a new feature.
2. OpenSpec is spec-anchored. Changes are deltas against a persistent spec, and archive moves the truth.
3. The unit of work is the change, not the product. Four artifacts at most, design only when needed.
4. Brownfield first. Specs grow from the changes you make; no back-filling.
5. One session, or ask for the next command before every /clear. After propose the files are the memory; before it, only the conversation is.
6. Review is the step that matters most, and nothing enforces it. The discipline is yours.

What Comes Next

In the next article I move from theory to practice. I will take an existing application, one that was not born with OpenSpec, and run real changes through the loop: explore, propose, review, apply, archive. I will look at how the specs read after a few changes, where the agent stopped to ask, and how it compares with the BMAD run on the same code. Stay tuned.

Have you tried OpenSpec, or another spec-anchored tool? Do you keep a living spec of your system, or does each feature get its own document and then age? I would love to read your experience in the comments.