About

The Story of OneSpec

My name is Sasha Ovsankin. I am a software engineer by trade and a jazz musician at heart. Over the years, I have been grappling with the need to develop faster while staying in control of the direction and the final result. I even tried to build a product around this, but the technology wasn’t there yet.

With modern AI tools, the dream of spec-driven development became a reality, and OneSpec is the result of the last few months of experimenting in the space.

I have run this process on several of my own projects and feel it is now ready for other people to try. So put on your creative hat and head over to the documentation to start creating software the way jazz is played: spontaneously, but with a clear sense of where you want to go.

Where OneSpec sits

Most spec-driven tools write a spec for a task and leave it behind once the code moves on. OneSpec is spec-anchored by construction: change specs carry one change while it's built, and their durable content folds back into the specs you keep.

OneSpec doesn't generate code from specs, so it avoids what Böckeler calls the downside of spec-as-source: “inflexibility and non-determinism”.

spec-first

Written for a task, then discarded.

spec-anchored

Where OneSpec sits. Kept after the task and used to evolve and maintain the product.

spec-as-source

Humans edit only the spec; code is generated from it.

Levels from Birgitta Böckeler, Understanding Spec-Driven Development.

Two kinds of spec, one lifecycle

The specs say what the product should do. Code that disagrees with them is a defect.

Lives with the product

Durable spec

Describes the product as currently intended. States behavior only: no file paths, step order or build records.

Lives with one change

Change spec

One Markdown file that carries one change while it's built. When done, onewrap folds its durable rules into the parent spec as a diff you confirm, then retires it.

Who it's for

OneSpec is made first for one developer working with coding agents: the author who plans, approves and verifies. Which team shapes it scales to is left to be seen in use.

Words we use

durable spec: What the product should do, kept current as changes land.
change spec: One file for one change while it's built; folded back and retired when done.
build: One planned increment. It stops at your checkpoint and runs only after you approve.
patch: One verified change: its test fails before, passes after, and the whole suite stays green.
acceptance: The check a build declares before it runs, run once over the final tree.
evidence: The recorded proof, with its provenance, that a build delivered.