A spec is the only source of truth you should trust

Most systems rot at the contract. The behavior everyone agreed to lives in a doc, a Slack thread, and three prompts — and none of them are checked against the code. Agent systems rot faster, because the prompt is the contract and the prompt is prose.

Make the contract executable

If the spec is the single source of truth, drift stops being an incident and becomes a build error. The spec generates the types. The types generate the bindings. A harness synthesizes property tests against those types. By the time you write a prompt, the shape of correct behavior is already pinned by things a machine can check.

Prompts are the soft layer, not the contract

This inverts the usual order. The hard guarantees — what an agent may touch, what it must return, what invariants hold — are types and tests derived from the spec. The prompt sits on top as the soft, persuadable layer. When an agent goes off the rails, it fails a property, not a vibe check.

Observability is part of the spec

You can’t operate what you can’t see, so everything an agent does is inspectable in real time. The dashboard I’m building alongside the framework is the front end of that idea: running projects, what each agent is working on, and a console to ask them directly. It’s a toy today and the architecture tomorrow.

Spec first, prompts last. The machine checks the contract; the language model fills in the judgment.

The payoff isn’t purity, it’s speed. When the spec is the truth, you can move fast precisely because the expensive mistakes are caught the moment they happen — at compile time, not in production.