From prompt to spec: how a specification governs your agents

You tell an agent "build me the billing module" and it hands you something back. It half works, it invented a rule nobody asked for and it deleted another one that actually mattered. The model did not fail: the brief did. You gave it a wish, not a contract. That is the difference between a prompt and a specification, and it is the line that separates vibe coding from governed work.

At Qirava we stopped asking AI to "see what comes out". We do not write loose prompts and hope the model guesses well. First we write the spec: what will be built, on what criteria it is accepted, and what stays out of scope. Then, and only then, it runs. We call this method SDD, Spec-Driven Development: the specification rules, execution obeys.

01 · the problemA prompt asks, a spec governs

A prompt is a request in natural language. It is fast, flexible and ambiguous by design. It is good for exploring, for asking, for testing the waters. But the ambiguity that makes it comfortable is the same ambiguity that makes it dangerous when the result has to be correct: the model fills the gaps you left, and it fills them on its own judgment, not yours.

A spec is something else. It is a document that sets the contract: the scope (what is in and what is out), the expected inputs and outputs, the business rules, and above all the acceptance criteria, those verifiable conditions that decide whether the work is right or wrong. A prompt gets answered. A spec is either met or not met, and that can be checked.

The prompt gives you what the model thinks you wanted. The spec demands what you actually defined.

The difference is not one of format, it is one of power. When an agent receives a prompt, the source of truth lives in the head of whoever wrote it. When it receives a spec, the source of truth is a document both sides can cite, review and audit. That idea of "write the desired result first, then build backwards" is not ours to claim: it is the heart of Amazon's working backwards method, where a product begins with its press release and its frequently asked questions before a single line of code exists [1].

02 · governanceThe spec governs the agent, not the other way around

Here is the twist that changes everything: at Qirava, every agent is born under governance. It is not a generic assistant you toss a prompt at. On startup it loads two things: a universal skill, qirava-llm-governance, which sets the rules of the game for everyone, and its role skill, which gives it its craft.

Roles are assembled as skill packages with four layers: universal, primary, secondary and forbidden. That last layer matters as much as the others: it defines what that agent cannot do. A marketing role does not touch architecture; a QA role does not approve what it produced itself. Here is the cast:

The spec is what tells each of these agents what to build and on what criteria it is accepted. Without a spec, a governed agent knows how to behave but not what to achieve. With a spec, it has both: the craft and the brief, the frame and the goal. That is why it performs better: it stops spending capacity guessing the objective and invests it in meeting it. The industry is moving in the same direction; tools like GitHub Spec Kit exist precisely to put the specification, rather than the improvised prompt, at the center of AI development [2].

03 · the boundaryDeliberating is not executing: the line no draft crosses

There is a principle that holds the whole method together, and it is worth stating plainly: drafts deliberate, but they do not simulate execution. To deliberate is to propose, evaluate and decide. To execute is to make the real change. They are different things and they must not be mixed.

An agent in draft state can analyze a spec, discuss alternatives, flag risks and recommend a path. What it cannot do is pretend it already did the work, or touch the real system as if it were approved. That boundary is what keeps a proposal from slipping through as a fact, and it is the reason the maturity gates make sense: a draft lives at G1, deliberates as much as needed, but only crosses into G2 (operational) when the CEO approves. Only then does it execute.

And when it finally executes, it is not taken as good on the first pass. QA at Qirava is a loop with professional regression: it is tested against the spec's acceptance criteria until certified, no rigged retests just to "pass". If something broke elsewhere, the regression catches it. The spec closes the loop: it defined the criterion at the start and it is the yardstick used to measure at the end.

All of this rests on a real documentary source of truth, a DOCUMENT_INDEX that says which version of each thing is the valid one. The skills live in a toolkit; the governance, in a vault; they are consumed by symlink. There are no loose copies or parallel truths. An agent that needs to know "what the rule is" does not improvise it: it looks it up in the index.

A prompt trusts the memory of whoever wrote it. A spec trusts a document anyone can audit.

In the end, moving from prompt to spec is not bureaucracy: it is what turns a smart but loose agent into a smart and governed one. The prompt asks "what comes out?". The spec answers first: "this is what has to come out, and this is how we will know if it did". With that contract in hand, the agent stops guessing and starts delivering.