Agree first.
Then build confidently.
OpenSpec is a tiny agreement layer between you and your AI. You write down what a change should do, the AI drafts the details, you both look at the same plan, and only then does code get written. No more discovering halfway through that it built the wrong thing.
/opsx:propose add-dark-mode
✓ proposal.md — why we are doing this, what changes
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
/opsx:apply
✓ working through tasks, checking each one off…
/opsx:archive
✓ specs updated · change filed away · ready for the next oneWorks with the tools you already use
The whole idea, in two folders
OpenSpec lives in one openspec/ directory in your repo. Two folders inside it carry the entire mental model.
specs/ — what is true
The source of truth. Plain-language requirements and scenarios that describe how your system behaves right now, organized by domain. This is the agreed-upon answer to “what does this software do?”
changes/ — what you are proposing
One folder per change. Each holds a proposal, a design, a task list, and a small spec delta. When the work is done, you archive it and the delta folds into the truth. The cycle closes.
What a change actually looks like
Plain Markdown files your AI drafts and you review. No new formats to learn, nothing you cannot read at a glance.
proposal.md# Proposal: Add Dark Mode
## Intent
Reduce eye strain at night and
match the user's system theme.
## Scope
- Theme toggle in settings
- System-preference detection
- Persist the choicespecs/ui/spec.md# Delta for UI
## ADDED Requirements
### Requirement: Theme Selection
The system SHALL let users choose
light or dark.
#### Scenario: Manual toggle
- WHEN the toggle is clicked
- THEN the theme switches at oncetasks.md# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 ThemeContext + state
- [ ] 1.2 CSS custom properties
- [ ] 1.3 localStorage persistence
## 2. UI
- [ ] 2.1 ThemeToggle componentLearn four ideas, and the rest is detail
Everything in OpenSpec is built from a handful of simple concepts.
Specs are the truth
Requirements and scenarios describe how your system behaves today. One agreed-upon answer, in your repo, readable by humans and AI alike.
A change is one unit of work
One feature, one folder. Proposal, design, tasks, and spec edits all live together. Easy to review, easy to reason about.
Deltas, not rewrites
You describe what is changing — ADDED, MODIFIED, REMOVED — not the whole world. That is the trick that makes OpenSpec great at brownfield code.
Enablers, not gates
Artifacts build on each other in a natural order, but nothing locks. Learn something mid-build? Edit the plan and keep going.
The loop you run
Two terminal commands to set up. After that, you live in your AI chat.
- optional
/opsx:exploreA no-stakes thinking partner. It reads your code, weighs options, and turns a fuzzy idea into a concrete plan.
- step 2
/opsx:proposeThe AI drafts the proposal, spec deltas, design, and a task list. You read it and adjust before any code is written.
- step 3
/opsx:applyThe AI builds it, working through the tasks and checking each one off as it goes.
- step 4
/opsx:archiveSpec deltas merge into the truth and the change is filed away with a date stamp. Ready for the next one.
For teams
Why teams adopt OpenSpec
Solo, OpenSpec keeps you and your AI honest on one repo. On a team, the hard part moves: work spans repos, requirements cross team lines, and planning starts before code exists. OpenSpec stores put planning in a repo of its own — one source of truth your whole team and every coding agent can read, shared by git push like anything else.
Cross-repo features
One change, one plan — even when the code lands in the API server, the web app, and a shared library. No more "whose openspec/ folder does this live in?"
Shared requirements
A platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No more drifting wiki.
Plan before code
Capture the plan in the store now, while it is just an idea. The code repos catch up later — the thinking is already recorded and reviewed.
Why bother with the extra step?
OpenSpec adds one small step — a short plan before building. Here is what you get for it.
Fixing a misunderstanding in a one-paragraph proposal is free. Fixing it after 400 lines of code is not.
Six months later, the spec tells you and the next AI session why the system works the way it does.
A change folder is a tidy package: read the proposal, skim the deltas, check the tasks. No chat archaeology.
Deltas mean you can specify a change to a 50,000-line app without first documenting the whole thing.
The honest middle
Heavier tools exist. So does doing nothing. OpenSpec aims for the spot where the value clearly beats the cost.
Ship your first change in five minutes
Works with 30+ AI assistants — Claude Code, Cursor, Codex, Windsurf, Gemini CLI, and more.