Specs for agents: discipline, not waterfall
Dennis Zaiser, technical founder
Spec-driven development is back, and so is the worry that comes with it: weeks of documents before any code, and a plan that is wrong by the time it is finished. With coding agents, that worry is aimed at the wrong thing.
Why specs came back
When a person writes the code, the spec can stay in their head. They hold the intent, notice when the work drifts from it and adjust as they go. A loose ticket is enough, because the person working on it carries the rest.
When an agent writes the code, the spec is the only place the intent exists. A vague request gets a confident implementation of a guess. The agent doesn't know which parts of the request were thought through and which were shorthand, so it fills the gaps with whatever is most plausible. The faster the agent, the faster a wrong guess becomes a large change.
The economics changed as well. When people wrote the code, the time spent on a spec competed with the time spent building, and building often won because one person kept both in mind. With agents, building is fast and cheap, and the cost that remains is deciding what to build. A spec is where that deciding happens.
What waterfall got wrong
Waterfall's problem was never that it wrote things down. It was that it wrote everything down up front, for months of work, and treated the document as fixed while the real learning happened in the code. Feedback arrived at the end, when changing course was most expensive.
None of that comes from writing a spec. It comes from the size of the batch. A spec for a quarter's worth of work is a waterfall document. A spec for one item, written the day before the work starts, is simply thinking clearly before acting.
The answer agile teams gave to waterfall was small batches and fast feedback, and it is still the right answer with agents. What changed is that a batch can now be built in hours, so the feedback loop is shorter than ever, and the place where a wrong idea is cheapest to fix has moved from the code to the page written before it.
Small specs, written just in time
A spec that suits agents is small. It covers one item rather than a project: what changes, why, what it must not break and how you will know it is done. Often a page is plenty, and sometimes a paragraph is.
It is written just before the work, when you know the most you are going to know without building. It names the open questions instead of hiding them, and it says which of them the agent may settle on its own.
It carries its own definition of done: conditions you can check, written when the goal is set rather than discovered during review. And it changes when you learn something. If the build finds a wrong assumption, the spec is updated, the change is visible, and the next step works from the corrected version.
A useful test: could someone who wasn't in the conversation tell from the spec alone whether the result is right? If not, the spec is missing exactly the part the agent will guess.
Discipline is the point
The value of a spec for agents is that it forces decisions before they are made by accident. Every open question left out of a spec is a question an agent will answer on its own, silently, in the code. Writing the spec turns those silent guesses into explicit choices, either made by you or handed to the agent on purpose.
A spec also gives the review something to measure against. Without one, a reviewer judges a change by taste. With one, the question is whether the change does what the spec says and nothing it doesn't, which is faster to answer and harder to argue with.
And it keeps the work steerable. When the spec is short and current, changing direction means changing a page, not untangling a week of agent output that followed an idea nobody wrote down.
Where specs should live
Not in the prompt. A spec written into a chat is gone when the session ends, and the next agent never sees it. Not in a folder of files that drift away from the work either, where nobody can tell which version a build followed.
A spec belongs next to the work it describes: linked to the item, the goal it serves and the runs that built it. Agents should be able to read the one section they need rather than the whole document, and people should be able to see which version of the spec a change was built from.
Kept that way, specs also make the history useful. When someone asks months later why a feature behaves as it does, the answer is the version of the spec it was built from, linked to the decisions that changed it along the way.
Where ctxflows fits
In ctxflows, goals on the roadmap carry what done means, written with the goal, and their order steers what is built next. Each item on a board links to its goal, and a record type can give an item the fields its spec needs, with the record type's statuses as the board's columns. Longer specs live in docs, as pages with drafts, versions and publishing, and an agent can be pointed to a single section.
A workflow makes the spec part of the work. The plan node reads the spec as its input, an approval puts the plan in front of you before the build starts, and the result is checked against the definition of done before it ships. Because the spec is a page or a record rather than a prompt, the next agent to touch the feature reads the same intent the first one built from. A person decides what is built and whether it was met.