Why OpenSpec

Two things go wrong with AI-assisted development, and they are not the same thing. The first is having no written record at all. The second is having one that is too expensive to correct. This page is about both.

1.1 Why prompting for code ad-hoc stops working

Describe what you want, read the code, ask for a change, read it again. For a small change this is the fastest thing available and there is no reason to do anything else.

It stops working at a specific point, and the point is identifiable: when somebody who was not in the conversation has to understand, review, or change the result.

FIGURE 6 — The same work, done three ways. All three lanes end with working code. They differ in what is left behind, and in what it costs to change your mind.

The first lane fails because the reasoning is in a chat log. Not versioned, not reviewed, and gone when the tab closes. Six months later the question "why does this system do that?" has one answer — read the code and infer — and inference is not the same as a decision record.

The second lane is the one people reach for next, and it fails differently. Write the specification, lock it, write the plan, lock it, write the tasks, then build. Every artifact exists and every artifact is correct on the day it was written. The problem arrives when you discover at the last phase that the first phase was wrong, which is what happens on real work, because real work is how you find out what you actually needed. Going back is expensive, so it happens rarely, so the artifacts quietly stop matching the code.

1.2 The idea — dependencies as enablers, not gates

OpenSpec keeps the same four artifacts as the second lane and removes the locks.

The order — proposal, then specifications, then design, then tasks — describes what becomes possible next, not what you are forced to do next. You cannot write a good task list without specifications to base it on, so the graph says tasks depend on specs. It does not say you are forbidden from editing the proposal after the tasks exist.

"Enablers, not gates" is the phrase that recurs throughout OpenSpec's own documentation, and it is worth taking literally. Discover during implementation that the design was wrong? Edit design.md and keep going. Realise the scope should shrink? Update the proposal. Nothing locks behind you.

The strength here is honesty: real work is messy and iterative, and this lets it be. The trade-off is discipline — because nothing forces you forward, keeping a change focused rather than letting it sprawl is on you rather than on the tool. That is a real cost and it should be weighed, not waved away.

1.3 The second idea — deltas, not restatements

The other thing OpenSpec does differently is how a change is written down.

Inside a change you do not rewrite the specification. You write a delta: added this requirement, modified that one, removed a third. You describe the diff, not the destination.

This is what makes the tool workable on a system that already exists. You are rarely building from nothing — you are adding a field, fixing a redirect, tightening a timeout. A delta specifies that one change precisely without first writing forty pages about everything around it. It is also why openspec/specs/ does not start full: it starts nearly empty and accumulates, one archived change at a time.

1.4 How it compares

FIGURE 7 — Where each one is strongest, and where it is not. Read down a column for one option's whole shape. Read across a row to compare on one question.

Note — the three comparison columns in FIGURE 7 are OpenSpec's own claims about its rivals, restated from its README rather than independently tested. Treat them as a starting point for your own evaluation, not a verdict. spec-kit in particular is a serious tool, and this site carries a full section on it walking the same publishing pipeline through spec-kit's seven commands. Reading the two side by side is the point rather than a duplication: the same user stories and the same article contract, put through two different methods.

Two rows in that figure are worth pulling out.

Going back a step. This is the difference between OpenSpec and a phase-gated method, and it is the argument in §1.2 expressed as a cost. Under phase gates, discovering at implementation that the specification was wrong means walking the phases again. Under OpenSpec it means editing one file.

What you are left with. This is the difference nobody notices in month one and everybody notices in year two. spec-kit leaves you with a specification of the change — accurate when written, with no step that folds it back into a description of the system. OpenSpec's archive step is exactly that fold-back, which is why its specifications describe what is running rather than what was once proposed.

1.5 When it is not worth it

An honest boundary, because a method sold as universally applicable is being oversold.

For a genuinely trivial one-line fix, the ceremony does not pay off. For a weekend prototype you intend to throw away, it does not pay off either. OpenSpec is designed to be lightweight but it is not free, and a change that takes four minutes to make and will never be revisited does not need a proposal.

The place it does pay off — and this turns out to be most work once an AI is involved — is anything that has to be correct, has to be handed over, or has to be changed later by somebody who was not there. That is the test to apply, and it is a judgement about the change rather than a rule about the tool.

Avoid: adopting it for everything on day one. The advice in OpenSpec's own documentation is to keep the first few changes small, because they are as much about learning the rhythm as shipping. A tight first change makes the loop fast and the lessons cheap.