My early builds all followed the same shape: I’d describe what I wanted in chat, watch code appear, look at the result, and correct course in the same conversation. It worked, but it didn’t scale past a single page. The moment a project needed a design pass, a build pass, and a review pass, keeping all three in one thread turned into a game of “wait, which version of the plan are we on?”
The fix was embarrassingly simple in hindsight: stop treating the conversation as the source of truth, and start treating a written spec as the contract. One agent’s job is to produce that spec. A second agent’s job is to build against it — nothing more, nothing less. A third agent’s job is to check the build against the same document, not against its memory of what was discussed.
“The spec is the handoff. The conversation is just how you got there.”
Why the document has to be the contract
When the spec lives in a shared markdown file instead of a chat history, three things change. First, a builder agent with zero memory of the discovery conversation can still do correct work, because everything it needs is written down. Second, disagreements get resolved by editing the document, not by re-litigating a decision from three messages ago. Third — and this is the one that actually saved a project — a tester agent can catch drift between what was designed and what got built, because it’s checking two documents against each other, not vibes against memory.
design-spec.md → builder agent → working code
→ tester agent → pass / fail against design-spec.md
None of this requires exotic tooling — it requires discipline about where decisions live. The first time I ran this loop end to end, the build came back needing exactly one round of fixes instead of the five or six I’d gotten used to. That gap is the entire argument for spec-first work: it’s not slower to write the plan down first, it’s slower not to.