Specs that stay true
Each change folds back into durable specs when it is done, so the specs describe the product as it is meant to be, not as it was planned months ago.
OneSpec
Specs that stay true.
OneSpec is a lightweight toolkit for spec-driven development with coding agents. Plan one small increment at a time, deliver it with recorded evidence that it works, and fold it back into the specs when done.
Plain Markdown in your repo. Runs in Claude Code, Codex and other models
How it works
A short loop: plan the next build, approve it, build it with evidence. When the change is done, its durable rules fold back into the specs.
Durable specs
what the product should do
what the product should do
oneplan
plan the next build only
plan the next build only
You approve
nothing runs before the checkpoint
nothing runs before the checkpoint
onebuild
test fails, then passes; evidence recorded
test fails, then passes; evidence recorded
Small fix?
no change spec needed
no change spec needed
onepatch
diagnose, fix, one verified patch
diagnose, fix, one verified patch
change done: onewrap folds it back
next build
Ceremony that fits the problem
A bug fix shouldn't turn into sixteen acceptance criteria. Three sizes of work, three paths. Start with the loop; grow into the spec graph when you want it.
Small
A fix or small change
onepatch diagnoses, asks only when the remedy isn't obvious, and delivers one verified patch.
Medium
A planned change
One change spec file and the build loop: oneplan, checkpoint, onebuild, onewrap.
Whole product
The spec graph
Durable specs linked to code and tests, with coverage review. Adopt it when you're ready.
Why OneSpec
Spec-driven development without the paperwork. Everything here earns its place.
Light by design
One prose file per change. A bug fix is one patch. No tool beyond the skills, and no Markdown pile-up to review.
One step at a time
Plan only the next increment in detail. Everything after it stays a one-line backlog item, and each plan starts from what the last build taught you.
Proof, not promises
Every build declares its acceptance check up front and records the evidence that it delivered. Tests fail before and pass after.
And a few more good reasons
You stay in control
Every build stops at your checkpoint. Checks only you can make are listed as author actions, and the build waits for them.
Traceable both ways
Code and tests point to the spec section they implement. Reviews show what's covered, what's a gap, and what the code does that no spec describes.
Less to review
One file per change, in ordinary prose and a fixed order. One build plan per checkpoint, one commit per patch.
No tool lock-in
Specs are plain Markdown in your repo. Install the skills with npx skills add or the Claude Code plugin marketplace.