OpenSpec (Part 1): Spec-Driven Development, One Change at a Time
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
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
Comments
No comments yet. Start the discussion.