Spec-first development with an agent fleet

Most of the code SOSW ships today is written by agents. When we tell people this, the first question is always some version of: how do you trust it? The honest answer is that we do not trust the code. We trust the process that produced it, and that process starts before a single line exists. We write the spec first, every time, and the spec is the thing that makes agent-written code reviewable, testable, and safe to run in production.

This is not a new idea. Engineers have argued for design docs for decades. What changed is the economics. When a human writes code, the spec competes with the implementation for the same scarce hours, so it gets skipped. When agents write code, implementation is cheap and intent is the bottleneck. The spec stops being overhead and becomes the actual work.

The spec is the contract

An agent will do exactly what you asked, which is rarely what you meant. A prompt is a conversation; a spec is a contract. It pins down what the system must do, what it must never do, and what done looks like, in terms a human can review before any code exists and an agent can execute without inventing requirements on the fly. Every ambiguity you resolve in the spec is a bug you never have to find in the diff.

The contract works in both directions. The human commits to stating intent precisely. The agent commits to building only what the spec covers, and to surfacing gaps instead of guessing. When a change request comes in, it goes through the spec first, not the code. The spec is the source of truth; the code is a derived artifact.

Requirements, design, tasks

In practice every feature moves through three documents, each one a gate that a human reviews before the next stage starts:

• Requirements — what the system must do, written as testable acceptance criteria. No architecture, no table names, just behavior.
• Design — how it will be built: data models, API contracts, failure modes, and the trade-offs that were considered and rejected.
• Tasks — the design broken into small, sequenced units of work, each one independently verifiable against the requirements it traces back to.

Only after all three are approved does an agent start writing code. By then there is very little left to decide, which is exactly the point. Agents are excellent at executing well-defined work and unreliable at making unstated judgment calls. The flow moves every judgment call in front of a human, and leaves the agents with execution.

Proof: fundshub.io

This is not a whiteboard theory. fundshub.io is a production serverless lead platform built spec-first by the SOSW agent swarm: 16 Lambda functions, 6 DynamoDB tables, and more than 15 APIs, driven by roughly 170 specs. Every function, every table, every endpoint traces back to a requirements document a human approved. When something misbehaves in production, we do not start by reading code. We start by reading the spec, and the question becomes either the spec was wrong or the implementation drifted from it. Both are fast to answer.

The model does not matter

People ask which model we use, as if that were the load-bearing decision. It is not. Models improve every quarter and we swap them freely. What does not change is the system around them: specs written before code, human review gates between requirements, design, and tasks, and an audit trail that records what was asked, what was approved, and what was built. The model does not matter. The system does. A weaker model inside this system produces trustworthy software; a frontier model without it produces plausible code nobody can vouch for.

The audit trail is what makes the whole thing durable. Six months later, nobody remembers why a Lambda retries three times or why a table has that particular sort key. The spec remembers. That is the difference between a codebase you maintain and one you excavate.

What breaks when you skip the spec

We know because we have skipped it, early on, for changes that looked too small to bother. The failure pattern is consistent:

• The agent fills gaps with plausible assumptions, and plausible is not the same as correct.
• Review degrades into reading diffs with no reference for what the code is supposed to do, so approval becomes a formality.
• Scope drifts silently, because without a written boundary there is nothing to drift from.
• Rework compounds: fixing a misunderstanding after implementation costs far more than one clarifying sentence in a requirements doc.

The lesson generalizes past agents. Spec-first was always the right way to build software; agents just removed the last excuse. Writing code is no longer the expensive part. Knowing what to build, precisely enough to hold anyone or anything accountable to it, is. So we write that down first.