OpenSpec Optimizes Chaos, Not Tokens

I had OpenSpec in the wrong category.

I was evaluating it like another component of an AI stack: does it reduce token usage, improve retrieval, or make the model smarter?

Those questions are useful for some tools. They are not the question OpenSpec answers.

OpenSpec addresses a more ordinary and more expensive problem: work that begins before its decisions are coherent.

Three things that get confused

An agent system normally needs at least three different kinds of support.

Knowledge answers: what does this library do, what are the current conventions, where is the relevant code?

Capability answers: what can the agent inspect, run, change, or verify?

Coherence answers: what are we actually building, which assumptions are intentional, and what counts as complete?

Retrieval can improve the first. Tools can expand the second. Neither automatically supplies the third.

That was my category error. I treated more available context as if it meant more coherent work.

The agent that starts too soon

The pressure was easy to reproduce. Give an agent a reasonable task: implement an endpoint, connect it to a service, add the auth checks.

The task is not absurdly vague. It has a legitimate goal. The agent can inspect the repository and find relevant examples.

Then it starts.

Halfway through, the API contract is implicit, the data model has been decided inside implementation, authorization has arrived as a patch, and two files have made slightly different assumptions. Each local edit looks defensible. Together they describe different systems.

The problem is not necessarily that the agent lacked information. The problem is that no one had externalized the decisions that information was supposed to support.

That is chaos in an agentic workflow: not noise, but multiple unexamined intentions becoming structure.

What the spec changes

OpenSpec introduces one forcing function: no implementation before a proposal exists.

The proposal does not need to be a novel. It needs to make the shape of the work inspectable:

• what is being built and why;
• what the interface promises;
• where data enters, moves, and persists;
• which boundaries and assumptions are relevant;
• what is explicitly out of scope;
• what evidence will be enough to stop.

This changes the object of review. Instead of reviewing a pile of implementation after the architecture has already become expensive to move, someone can review the intended shape while it is still cheap to change.

A ten-line correction in a proposal is not proof that the proposal was perfect. It is evidence that a decision was surfaced before it became residue.

Why this is not a token optimization

A shorter context window does not make an incoherent task coherent. More documentation does not resolve conflicting assumptions. A smarter model can still execute faster in the wrong direction.

The optimization happens elsewhere. OpenSpec moves waste from late rework to early disagreement.

That is especially important when implementation is cheap. As agents produce code faster, the scarce resource is not always typing or tokens. It is the human capacity to understand what has been built, what was assumed, and whether the next action still follows from the original intent.

A visible proposal gives the outer loop something to inspect before the inner loop accumulates momentum.

It also preserves learning. If every decision is made inside an opaque execution trace, the next session inherits output without necessarily inheriting the reasoning. A spec can be challenged, revised, and compared with the result. It is a small artifact of understanding, not just an instruction to a model.

The proportional rule

I do not write a formal spec for every variable rename. That would turn a useful constraint into ceremony.

For a simple, well-understood change, a sentence may be enough. For work that crosses services, touches authorization or tenant scope, changes a data model, or will be resumed by another session, the proposal should be real enough to expose the decisions.

The threshold is not task size measured in lines. It is the number and reversibility of the decisions being embedded.

A spec earns its overhead when it prevents the team from discovering the shape of the work only after the code has made it expensive.

The category's limit

OpenSpec does not make plans correct. A clear proposal can encode a wrong assumption. A reviewed design can meet a reality it did not model. The implementation can still drift from the document.

That limit matters because externalized intent is not a substitute for judgment. Someone still has to understand the proposal, accept its trade-offs, notice contradictory evidence, and revise it when the system teaches something new.

But this is a better failure mode. A wrong plan that is visible can be challenged. A wrong plan that exists only as generated code has already charged interest.

OpenSpec therefore does not optimize tokens. It optimizes the point at which a team is willing to discover that its work is incoherent.

The remaining question is not whether an agent can produce a plan. It is whether the people responsible for the outcome will look at the plan before execution makes looking optional.