What This Buys You

This page is the argument, stated once, for somebody deciding whether to fund this rather than how to build it.

12.1 The argument

You get a description of the system that is still true next year. Not a document written before the build and diverging from the first week, but a set of specifications that every completed change merges back into. That is the archive step, and it is the one thing on this page that is hard to buy any other way.

You get reviewable AI output. The scepticism about AI-written code is warranted. What changes it is not a promise about model quality — it is that the agent is working against numbered tasks that trace back to scenarios that trace back to requirements somebody agreed to in English. The output is not thereby correct; it is checkable, which is what was missing.

You get a decision record. design.md holds not just what was chosen but what was rejected and why, dated, in version control, alongside the code. Six months later "why does it de-duplicate on canonical URL?" has a written answer rather than an archaeology exercise.

You get to disagree cheaply. Every assumption in this proposal is one edit before the build. The eight in the register are listed with the cost of deciding each differently, precisely so that disagreement happens on the record and early.

You get no lock-in. MIT licence, no fee, no hosted service, no account, no API key held by the tool. Everything produced is plain Markdown in your own repository, and thirty-six different AI assistants can drive it.

12.2 What it does not buy you

It does not make specifications good. It enforces having one and it catches a specific list of malformed ones. A vague specification produces a vague plan faster than before.

It does not prevent the shortcut. Nothing stops somebody opening the code and editing it directly, and nothing errors when they do. Day two is explicit about this: the discipline is yours.

It does not remove engineering judgement. Somebody still decides what to build, what the approach should be, and whether the result is good.

It does not pay off on trivial work. For a one-line fix or a throwaway prototype, the ceremony costs more than it returns. That is fine, and the boundary is stated rather than glossed over.

12.3 The honest trade

Slower to the first working version. Faster to the tenth. Roughly ten extra minutes per change, spent writing the change down instead of editing the code directly.

On the first change that is pure cost. Somewhere between the third and the tenth it stops being cost, because re-deriving what the system does from the code starts taking longer than reading the specification. Nobody can tell you where that crossover lands for your team, and this document does not pretend to — but it can tell you which direction each line runs.

Appendix A — Every command at a glance

In your terminal:

Every one of them accepts --json and emits exactly one JSON document with a status array. Exit 0 success, 1 error, 130 on interrupt.

In your AI assistant's chat — the core profile, installed by default:

The expanded profile adds six more — /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard — via openspec config profile then openspec update.

Your tool may spell these /opsx-propose, @opsx-propose or $openspec-propose. openspec init prints the right form for the tools you picked.

Appendix B — The required headings, in one place

A scenario is exactly four hashes. Three fails silently, and it is the single most common mistake.

---