The agent guesses what you meant.
With Empirical SDDA spec you agreed on, before any code.
Spec-driven development for coding agents
The engineering discipline your coding agent is missing.
Empirical SDD turns a request into a spec, checks, review, and a clean merge, all recorded in your repository. Every step has proof. Nothing ships without your sign-off. And any session can pick up exactly where the last one stopped.
npm install --global empirical-sdd
empirical installWhy
Fast is not the same as done.
Coding agents write code quickly. Empirical SDD adds the process that makes it safe to ship.
Done means it looked done.
With Empirical SDDDone means the checks ran, with receipts.
The agent reviews its own work.
With Empirical SDDAn independent review of the exact diff.
Merged wherever, whenever.
With Empirical SDDMerged into a clean target, only with your sign-off.
How it works
Install once. Then just ask.
- 01
Shell
Install
Run
npm install --global empirical-sdd, thenempirical installand pick your agents. - 02
In your agent
Initialize
Type
/empirical-initin Claude Code or$empirical-initin Codex. Review the proposed setup, then apply it. - 03
In your agent
Ask for a change
Ask like you always do. Empirical SDD takes it from there: spec, checks, proof, next step.
Coming back later?
Open the same checkout and say:
In your agent
Continue the active feature.Workflow
Process sized to the change.
Anything that changes behavior runs the full Complex loop. Small, reversible edits take the Fast route.
The Complex loop
- 01Specify
Agree what done means.
- 02Design
Pick the approach.
- 03Plan
Break it down.
- 04Implement
Write the code.
- 05 · if neededContext
Refresh repo knowledge if stale.
- 06Verify
Run the checks.
- 07Review
Judge the diff.
- 08Integrate
Merge into a clean target.
Verify failsBack to Implement. The failed attempt stays on record.
Review asks for changesBack to Implement, then verify and review again.
In words. Specify, Design, Plan, Implement. Refresh context only if the repo knowledge is stale. Verify, Review, Integrate. Any failure sends the work back to Implement. Deliver and Publish are separate, and each needs your sign-off.
Fast routeImplement Verify
Small, reversible edits skip the loop. The checks still run, and if a Fast attempt fails the work is promoted to Complex with the failed attempt on record.
01implementedthe code exists
02verifiedthe checks passed
03integratedreviewed and merged clean
04deliveredshipped where you allowed
05publishedreleased, for good
Guardrails
It runs the process. You keep the authority.
Empirical SDD does
Keep the work honest.
- Sorts every change by risk.
- Writes down what was agreed and where things stand.
- Runs the right checks and keeps every attempt on record.
- Reports only what it can prove.
Empirical SDD never
Decides for you.
- Replaces your model, Git, CI, or agent.
- Keeps running after your agent stops.
- Treats a confident answer as proof.
- Merges, releases, or publishes without your say-so.
Proof
Three questions. Three separate answers.
Did the checks run?
Every acceptance criterion points to a real run and a receipt tied to that exact code. Change the code and the receipt goes stale.
Who looked at the diff?
A fresh-context reviewer or your review bot judges the exact committed diff. A green test is never mistaken for a review.
Did it land clean?
Reviewed changes are replayed against a separate target before they count as shared behavior.
Under the hood
Everything it writes is a file you can read.
Setup adds a .empirical/ folder and a small entry in your agent instructions. Work adds specs, decisions, and receipts next to your code. No database, no background service.
Full treeBrowse every file it creates.
- Marker-ownedEmpirical SDD manages only its bounded entry or block, preserving surrounding user content.
- Agent/team-maintainedEmpirical SDD scaffolds it; repository evidence and maintainers refine it.
- ConditionalCreated only for a chosen agent, route, phase, or required policy.
- OptionalCreated only after explicit configuration or when that outcome exists.
Use Up and Down to move through paths, or Home and End to jump. Selecting a path updates the ownership detail beside the tree.
Written during Init
May appear as work advances
Not persisted: the dynamic packet returned to an isolated reviewer. Only a submitted canonical result, its human-readable rendering, pointer, and receipt belong in the committed tree.
Day to day
No commands to learn. Just ask.
Where am I?
In your agent
Where does the current feature stand?Keep going
In your agent
Continue the active feature.Something off?
In your agent
Run Empirical SDD Doctor and explain any findings.Stuck?Fix the cause. Keep the record.
| What you see | What to do |
|---|---|
| Changes don't go through Empirical SDD | Run Init again to repair the setup, then reopen your agent. |
| A new request resumed old work | On purpose: unfinished work comes first. Finish it, or approve a separate worktree for the new thing. |
| Proof went stale after an edit | Run the checks again. Old receipts can't be edited or reused. |
| It asks for credentials | Use OAuth or the secrets file. Never paste secrets into chat. |
Docs
Want the details? They are here.
Short site, long docs. Everything precise lives in these references.
01
Learn
DemoInstallation and representative lifecycle scenarios.→ProtocolState machine, artifacts, evidence, and completion rules.→ArchitectureOwnership, persistence, transactions, and trust boundaries.→02
Operate
MCP & trackingAgent operations, setup, tracker policy, and authentication.→SecurityCredentials, execution boundaries, review, and authority.→MigrationMove older repository state forward safely.→03
Evaluate & maintain
OpenSpec comparisonScope, overlap, and product fit.→VersioningCompatibility and schema policy.→ReleasingThe guarded playbook for Empirical SDD maintainers.→Free and open source
Try it on one repo.
Install, run Init, and ask for the change you were going to make anyway.