Without a plan, the AI builds its own idea of what you meant
AI coding assistants are fast, but they work from whatever was said in the chat. You find out what they understood only once the code exists, which is the most expensive time to find out.
Without OpenSpec
A vague request leads to code that has to be reviewed and then reworked. Nothing records why it was built that way.
With OpenSpec
The request becomes a one-page plan that a person reads and agrees. The AI builds exactly that, and the plan is kept.
Four steps, with a person signing off the plan
The AI does the writing. The one step that needs a person is the sign-off.
Explore
The AI reads the existing code and talks through the options before anyone commits to anything.
AI · optionalPropose
The AI writes the plan: why, what will change, how, and a list of tasks.
A person reads it, then corrects or approves it. This is the step that counts.Apply
The AI builds the approved plan, ticking off the tasks as it goes.
AIArchive
The plan is filed away, and the description of how the system behaves is brought up to date.
AI
One folder for each change, filed into one master description
It's all ordinary text files kept with the code, so they're versioned and reviewed in the same way as the code.
Each new change starts from the master specs, so the AI always knows what's true now.
What the AI actually writes
Here are the four files from the change folder, for the "add dark mode" request. They're plain text that anyone can open and read. The symbols (#, -, [ ]) are only headings, bullet points and checkboxes.
# Proposal ## Why People use the app at night, and the bright screen is tiring. Several have asked for a dark option. ## What Changes - Add a light/dark switch to the settings menu - Start in whichever theme the device uses - Remember the choice between visits ## Capabilities ### New Capabilities - `theme-selection`: choosing and remembering a light or dark theme ## Impact Styles across the app, and the settings menu. No new dependencies.
Look forIs this the right problem, and is anything missing? This is the file to read most carefully.
## ADDED Requirements ### Requirement: Theme selection The app SHALL let people switch between light and dark themes, starting with the device's own setting. #### Scenario: Someone turns on dark mode - **WHEN** they press the theme switch - **THEN** the app turns dark and remembers the choice #### Scenario: First visit on a dark device - **WHEN** the device is set to dark - **THEN** the app opens in dark mode
Look forDoes each example match what we actually want? These are what the finished work is checked against.
# Design ## Context Colours are written into each screen's styles separately. ## Goals / Non-Goals **Goals:** one place to define colours; no flash of the wrong theme as a page loads. **Non-Goals:** custom colour themes. ## Decisions - Define each colour once as a theme setting, so switching theme swaps values rather than rewriting screens. - Keep the choice in the browser. No account is needed. ## Risks / Trade-offs - Charts and images may need dark versions. Check each one before release.
Look forThis one is mostly for engineers. Skim the Non-Goals, which say what has been left out on purpose.
# Tasks ## 1. Theme foundations - [x] 1.1 Move colours into theme settings - [x] 1.2 Add a dark value for each colour ## 2. The switch - [x] 2.1 Add the switch to the settings menu - [ ] 2.2 Remember the choice between visits - [ ] 2.3 Follow the device setting on a first visit ## 3. Checks - [ ] 3.1 Look over every screen in both themes
Look forThe ticks are progress. The AI ticks each task as it finishes it, so you can see how far it has got.
These are short examples written for this page, laid out the way OpenSpec lays out its files. Real ones are usually longer.
Worth doing even when a person writes the code
Requirements from the business are rarely complete. Drafting an OpenSpec plan makes the gaps visible before anyone starts building, whether a person or the AI then does the coding.
- 1 · Business
The request
"Add dark mode." A sentence or two, with plenty left unsaid.
- 2 · AI
A plan in minutes
Writing the examples ("when this happens, then that") forces decisions the request didn't make.
- 3 · AI
The gaps show up
- Should the choice follow people to their other devices?
- Do printed pages stay light?
- What happens if the device has no setting?
- 4 · Person
Back to the business
"Is this what you meant?" is far easier to answer than writing the full requirement in the first place.
- 5 · Either
Then build it
By handOr with AI
Treat every filled gap as a question
When the AI fills a gap, it fills it with a guess that reads just like a real requirement. Each guess needs confirming with the business. Otherwise we build things nobody asked for.
Two files do most of the work
For a change written by hand, the proposal and the spec matter most. The design and tasks matter less.
A clear finish line
A confirmed spec says what "done" looks like, and the master description records the result whoever wrote it.
What we get from it
Fewer surprises
Misunderstandings are caught in a one-page plan, not in finished code.
A written record
Every change says why it was made. A new starter, or a future AI, can read how the system is meant to behave.
Oversight
A person approves each plan before any code is written. Plans are reviewed alongside the code.
No lock-in
It's free and open source, and works with over 30 AI tools. The plans are text files that we own.
Independent reviewers see it as the light choice for existing systems
What people outside OpenSpec say about it and about the main alternatives, gathered from four independent sources.
Thoughtworks moved it up a ring this month
Thoughtworks' Technology Radar is a widely followed twice-yearly guide to which tools are worth using. Its teams reported success with OpenSpec, and they found its output more predictable, with fewer unintended changes, than prompting the AI directly.
OpenSpec
Our choice- Best for changes to systems that already exist. Thoughtworks, Levelop
- Works with any AI tool, and keeps an up-to-date master description. Thoughtworks
- The AI writes a lot of text, and keeping the master description current takes discipline. Thoughtworks
- Has fewer built-in quality checks than Spec Kit. Jama Software
Spec Kit
GitHub- Suits new projects, and is the easiest of these to customise. Levelop, Böckeler
- Has stronger checkpoints between stages. Jama Software
- Heavy: one reviewer spent about 90 minutes planning a single feature. Levelop
- Produces many repetitive files that are tedious to review. Böckeler
Kiro
AWS- Simple, with just three documents that are easy to review. Böckeler
- Has formal checks on requirements, which suit compliance-heavy work. Levelop
- Ties you to Amazon's own editor and its credit-based pricing. Levelop, Thoughtworks
- Overkill for small fixes: one small bug grew into 16 acceptance criteria. Böckeler
Nothing
Just chat with the AI- No extra steps, so it's the quickest way to start.
- Teams found its results less predictable than OpenSpec's, with more unintended changes. Thoughtworks
Cautions that reviewers apply to all of these tools
- Match the process to the job.A full plan for a one-line fix is wasted effort. Böckeler, Levelop
- Plans aren't guarantees.The AI doesn't always follow every instruction, so the code still needs checking. Böckeler
- Keep checking whether they're needed.As AI models improve, some of this may become unnecessary. Thoughtworks
Sources are listed at the foot of the page. None of them is connected to OpenSpec, GitHub or AWS, as far as their pages say.
What's new in version 2
Plans shared across projects
A "store" keeps plans in a repository of their own. A feature that touches several systems gets one plan, and a platform team can own requirements that others follow.
One set of instructions for every AI
They're kept in one shared place. Before, each tool had its own copy.
New command names
/opsx:propose becomes openspec-propose, and so on. People who are used to the old names will need telling.
Installs without Node.js
A standalone installer makes it simpler for people who don't write code.
What it asks of us
A quick refresh
Run one update command and commit the result. It takes minutes.
Real review time
Someone reads and approves the plan. That review is the whole point.
Save local edits
The update overwrites any edits made by hand to OpenSpec's own instructions.
Usage counts
It sends anonymous counts (command names only) unless one setting turns them off.