Drift: what if the spec were the source of truth, not the code

One-shot builds work. The systems still degrade.

Most new code is now written by agents, and a growing share of it is reviewed by agents too. The way teams use them is straightforward: an engineer writes an architecture document or a spec, hands it over, and the agent builds it. The first pass usually lands. You ask for a service and you get a working service, often the same afternoon.

The trouble shows up months later, in a system that has absorbed hundreds of those passes. A change that should take a day takes a week, because the code is organized around decisions no one remembers making. The agent made them, for reasons that were sound inside a context window that is long gone. Performance sags in a place nobody chose. Then someone in a planning meeting asks a plain question—does checkout do what we said it does?—and the room goes quiet. The intent lives in a document, the behavior lives in the code, and the two have been drifting apart one reasonable merge at a time.

Drift is a prototype from one of our design sprints that takes that failure seriously enough to redesign planning software around it. The tools we plan with today assume the scarce thing is coding time. It isn’t anymore. The scarce thing is a durable record of what the software is supposed to be, and why.

The spec is the desired state; the code is the actual state

The prototype rests on one sentence, printed under the board title: the spec is the desired state; the code is the actual state. The vocabulary comes from control systems. You declare the state you want, you measure the state you have, and the difference between them is the work. In the demo, the Code layer’s header reads 92% in sync, 2 gaps, 2 building (every number on these screens is demo data; what matters is that the distance between promise and behavior appears as a measured figure at all). When the spec promises something the code doesn’t do, the gap surfaces on its own. Nobody has to notice it, write a ticket, and groom it forever after.

The board holds three layers. Vision is direction that hasn’t been committed yet, a holding pen for ideas. Spec is the contract: in the demo, 6 capabilities and 17 shall-statements, one file per capability, each shall written to be testable.

WHEN the user submits an expired card, THE SYSTEM SHALL retry authorization once, then surface a decline message that names the reason.

Code is whatever main currently does, owned by the agents pulling it toward the spec. Ideas must be promoted from Vision into Spec before they bind anything, so aspiration and commitment stay separate. And the spec describes observable behavior and product-level constraints while staying out of implementation; every spec PR is linted for that leakage, so the code layer keeps the freedom to satisfy each promise however it can.

Between the target and main: a graph, with the reasoning attached

Here is where the sprint pushed past the obvious version. A backlog is a list, and a list carries almost none of the knowledge that makes a system buildable over time: what has to exist before what, which changes belong together, and why this is the next thing to build. In Drift, the work between the target and main is a graph. The unit is a spec PR, a reviewable change to the contract, and spec PRs stack: DR-208 (“Surface saved-card expiry before checkout”) depends on DR-207 (“Retry expired-card authorization once before declining”) and stays parked until its parent lands. The ordering is part of the plan, and it’s recorded rather than remembered.

Each node also carries its discussion, and this is the part we came to think matters most. A grilling agent opens DR-207 from the vision slice it traces to (“fewer false declines”), reads the current spec and the running behavior, and posts three genuinely different ways the retry could work, each with a trade-off and a recommendation. Then it splits the open questions into decision threads, each routed to the person who owns that capability. The discussion is where the why gets captured. That record is exactly the thing whose absence makes a year-old, agent-built system unexplainable.

The flow model (schematic). The product team tends the target and the ordering; agents execute the graph branch by branch; drift on main flows back in as new work.

Agents consume the graph branch by branch

An item becomes ready when its dependencies have merged and its decision threads are resolved. That readiness is enforced the way engineers already trust: as status checks. DR-207 shows 2 threads block merge; its decisions-resolved check reads 1 of 3, so the contract can’t change yet. Once it does, a coding agent picks the item up, opens a branch, builds against the shall-statements, and merges when the checks pass. Every branch traces to a spec PR, and every spec PR traces to a vision slice. Work done ties back to work expected, which is the property one-shot building never had.

The review surface earns its keep when owners disagree. On DR-207, the payments owner wants the retry to cover one-click checkout with a saved card, so customers see consistent behavior. The security owner objects: an expired saved card is a stale-credential signal, and silently retrying weakens it. Both positions are reasonable, and the design holds them on screen and waits for a human with authority to pick. It would be easy for an agent to average the two into something confident-sounding. The prototype treats that as the failure case.

The loop closes from the other side too. A Drift suggests panel reports what scheduled checks find on main: behavior the contract never promised (an order-shipped SMS with no matching shall, its reconciling PR already drafted), a regression against a shall in the cart spec, and a spec file 40 days quiet while vision moved on. Each gets its own verb—review the drafted PR, open a fix task, open planning—because those three failures deserve different responses, and a person chooses which way each one gets closed.

Aren’t architecture decisions engineering’s call?

There’s a fair objection to putting a product-owned contract at the center of software: architecture is engineering-driven. Schema design, queue choices, caching strategy—no product document should dictate those, and in this design none does. But every one of those decisions exists to serve a need the product side can name. The cache exists because checkout has a latency budget, and the latency budget exists because abandonment costs revenue. So Drift captures the need in the discussion and leaves the how to the code layer. When an architecture upgrade comes due, the agent’s instructions are that discussion: what must stay true, who it’s for, what it must not break.

Neither waterfall nor sprints

Step back and the prototype is arguing with both of the ways we’ve organized software work. Waterfall assumed you could define everything up front and be right. Sprints assumed the scarce resource was human coding time, so work had to be batched into a cadence a team could absorb. When agents write and review the code, both assumptions are gone. Work can flow continuously: the product team tends the target and the ordering, agents keep pulling main toward it, and drift flows back in as new work. That current is where the name comes from: drift is the force out ahead of an object in a moving stream, pulling it along. During the sprint we started calling the wider shape the flow model of building software. Humans methodically define the software to be built and the path to get there; agents do the code.

Drift is a design prototype, an exploration of a problem we kept hearing about rather than a shipped product. It belongs to the same argument as the rest of our gallery—that the useful move with agentic AI is to design software around what agents can do, which is the case we make in the bespoke SaaS post. The test of the paradigm is the planning-meeting question this piece opened with. Does the software do what we said it does? In a flow model, that question has a number for an answer.