The second-most damaging misreading of Flow-Next, after the rigid-conveyor one, goes like this: “Spec first means decide everything up front. That’s waterfall with a new coat of paint.”
It is the first objection in almost every room, it usually comes from the most experienced person present, and it deserves a real answer rather than a slogan.
Waterfall is not “thinking before building.” Three properties make it waterfall:
Flow-Next has none of the three, and the reason is structural rather than cultural.
The honest concession, because dodging it costs you the room: yes, this requires more thought earlier than a loose ticket does. That is real. What it does not require is more commitment earlier. The distinction is the whole doctrine.
The spec is a ratchet, not a gate. A gate decides what you are allowed to do next. A ratchet just stops you sliding back. You do not need the spec’s permission to read code, prototype, or research - the spec exists so that what you learned cannot be silently lost by the next stage, the next person, or the next agent.
The waterfall objection almost always compares Flow-Next against an idealized agile process nobody is running. Compare against what the team does today, one week after the AI coding tool was switched on:
A vague ticket goes into the agent. The agent produces something. Someone looks at it, does not like it, prompts again. Looks again, fixes by hand, prompts again. Round and round until it looks close enough to ship.
That loop is not agility. It is rework with no artifact - the requirement is being discovered, one prompt at a time, and then thrown away. Two things follow:
/loop or /goal drive them unattended, and what makes autonomous bug-fixing possible later (the defect traces back to a feature, its spec, and its evidence). The prompt-look-fix circle produces no such object, so a team stuck in it can never climb the autonomy dial, no matter how good the models get.Flow-Next pulls the knowledge dump from the POs, PMs, and lead devs slightly forward in the process, and writes it down. That is the change. It is a smaller change than it sounds like, and a larger one than it looks.
The stubborn assumption underneath the waterfall fear is that “spec-driven” means somebody sits down and writes a requirements document. Nothing in Flow-Next asks for that. Capture takes whatever carries the intent:
| Input | Typical source |
|---|---|
| A conversation with the agent | One person thinking out loud |
| A multi-person conversation with the agent | Refinement session, mob discovery |
| A briefing package (markdown, half-formed) | Cross-functional kickoff, domain expert dump |
| A business-language requirements doc | Customer-facing commitment, BRD, account team |
| A working prototype | PM, designer, or engineer who built the thing to find out |
| A generated interface image | Design exploration against your style guide |
| An eval or benchmark result | The evidence decided it, capture records why |
| A spike you are about to throw away | Revert the code, keep the understanding |
None of these is a requirements document. All of them are valid capture inputs, and the last four are the ones teams underuse most.
The pattern underneath the whole table: let something real answer the question, then capture the answer. Prototyping is the sharpest instance of it and gets the next two sections; the rest of the family - probes, evals, reproductions, research, spikes - follows the same shape.
The strongest version of the loop, and the one worth teaching first:
flowchart LR Q["Open question<br/>(how should it look / behave?)"] --> P["Prototype<br/>1-3 variants, throwaway"] P --> R["React & iterate<br/>at high fidelity"] R --> C["Capture spec<br/>from the prototype"] C --> I["Interview<br/>closes the gaps"] I --> PL["Plan<br/>rules on the code"] PL --> W["Work"]
Build the thing badly, on purpose, to find out what it should be. Then capture a spec from the prototype and tell the agent to ignore the code quality - what you want out of it is the ideation and the requirements it proved, not its implementation.
Vibe-code a prototype, then let it write the spec.
"capture a spec from this prototype - ignore the code quality, I want the product intent and the requirements it demonstrates" ✓ The prototype answered the design question at a fidelity a discussion could not reach. Capture harvests the answer; the plan stage decides separately what happens to the code.
Scale it up when the question is genuinely open: generate three radically different takes, react to all three, converge on a fourth. The variants do the work an argument cannot - it is much easier to say “the search box from A, the layout from C” than to specify either in prose.
Three takes, hill-climb, then spec the winner.
"build three radically different prototypes of this, let me react to each, then capture the winner as a spec with the rejected options and why they lost" ✓ The losing variants are evidence, not waste - recording why they lost stops the same idea coming back in three months. Only the decision and its rationale land in the spec.
More compose recipes →Not every question needs running code. The decision rule is fidelity: how concrete does the artifact have to be before the question can actually be answered?
| Question | Fidelity needed |
|---|---|
| ”Should the modal have cancel and confirm?” | Discussion. Just decide. |
| ”What are the acceptance criteria for this rule?” | Discussion, then interview. |
| ”How should this look?” / “How should this behave?” | Prototype. No amount of prose settles it. |
| ”Does this state model feel right in the awkward cases?” | Prototype. A logic prototype, not a UI one. |
| ”Which of these three approaches actually performs?” | Prototype, or a task-per-candidate bake-off. |
Two things follow from taking fidelity seriously.
Prototyping is not a front-end activity. The reflex is to reach for a prototype only when there is a screen involved, and that reflex leaves the hardest questions unanswered. A logic prototype - a tiny interactive harness that pushes a state machine through the cases that are hard to reason about on paper - answers “does this model survive the real world?” better than any design document. Backend work is where the expensive misunderstandings live.
Fidelity costs tokens, and that is a real budget. A discussion is cheap and gives cheap answers. A prototype costs real tokens and gives an answer you can trust. Buy fidelity where being wrong is expensive; stay in discussion where it is not. The cost of producing code has collapsed, which is exactly why prototyping is now the cheap option it never used to be - but it is not free, and pretending otherwise is how token budgets get burned on questions a two-minute conversation would have closed.
The payoff is a shorter final leap. Going from a spec to production-ready code is a big jump. Going from a working prototype to production is a small one, because the hard questions were answered against something real.
Prototyping is the flagship because it is the most underused, but it is one member of a family. The shared shape is what matters: let something real answer the question, then capture the answer. The agent does the finding-out before a spec exists, and the spec records what was found rather than what somebody guessed.
| Route | The question it answers | Say something like |
|---|---|---|
| Prototype | How should this look or behave? Does this model survive the awkward cases? | “build three prototypes of this, let me react, then capture the winner as a spec” |
| Probe / measure | What is actually wrong, and where? | “run the load test against staging, then lock down a spec for the fixes the numbers point to” |
| Reproduce | Does the bug behave the way the report claims? | “reproduce this as a failing test, then capture a spec where that test is R1” |
| Eval / benchmark | Which of these actually wins on our data? | “evaluate the two variants on our fixtures, iterate until one clearly wins, then capture a spec to adopt it” |
| Research | What do we not know yet about the outside world? | “research how they price their plans, then capture a spec for a tiered pricing page - business requirements, not implementation” |
| Spike | How does this subsystem actually work? | “revert those changes and capture our discussion as a spec” |
| Bake-off in-spec | Which approach wins, when you cannot judge without building it properly? | “plan this with one task per candidate approach, plus a final task that compares them and keeps the winner” |
| Red-team the spec | What did we miss before writing a line of code? | “attack this spec for gaps and unstated assumptions before we plan it” |
Two notes on choosing between them.
Match the route to the question, not to habit. A performance complaint wants a probe, not a prototype. A “which library” argument wants a bake-off. A bug report wants a reproduction, and the reproduction becomes acceptance criterion R1 - the strongest spec opening there is, because the criterion is executable from the first minute. Reaching for the same route every time is how teams end up prototyping questions a measurement would have closed in ten minutes.
The agent can run most of these unattended. Research, probes, evals, and reproductions do not need a human watching, which makes them cheap to run before anyone has committed to a shape. The expensive human time then goes to reacting to real findings instead of speculating in a refinement meeting. Prototyping is the exception that genuinely wants a person in the loop, because reacting to the artifact is the work.
Every one of these lands in the same place: a spec whose claims trace to something that actually happened. The full catalog lives in the cookbook.
“It’s throwaway” is the default, not a law. Prototype code has three possible fates, and the plan stage decides which - not the person who wrote it, and not by reflex:
This is the moment that resolves the oldest friction on the team - product hands over something that works, and engineering has to decide whether it is a gift or a liability. Making it an explicit planning decision, with the architecture docs in context, turns that argument into a step.
Encode the rule rather than re-litigating it every time. A line in your CLAUDE.md/AGENTS.md is enough:
When seeding a spec from a prototype: treat the prototype as requirementsevidence, not as an implementation. The plan stage must state, per module,whether prototype code is kept, re-based on our standards, or discarded -checked against docs/architecture.md and the design-library rules.The context pack that priming builds for your repository - product strategy, target user, domain constraints, architecture, standards, design library - is not repo-only. Copy it into whatever prototyping tool the team uses, and the prototypes come back in your world instead of a generic one.
This matters more than it sounds. Product, business, and domain context rank with technical context, and most harnesses only carry the technical half. There is a large difference between an app used by a builder on a tablet on a site and one used by an analyst at a desk with two monitors - and an agent that was never told which one it is building will produce a competent, generic, wrong interface. Give it the product context and the same prompt produces something tuned to the actual user.
The same pack, copied into three tools, makes all three better. That is the cheapest quality win available to most teams.
When the interview asks something that feels obvious or stupid, the useful reaction is not to dismiss the questions and not to patch the prompt locally. It is: something is missing from the context surface, go fix it once.
A question that should not have needed asking is a measurement. It says the strategy doc, the domain notes, the ADRs, or the product context did not carry something a competent newcomer would need. Fix the document, and every future run - and every future human - benefits. Argue with the question, and you will answer it again by hand every sprint.
This is the discipline the workflow actually asks for, and it is the one most teams skip. It is also why context tends to live in three or four people’s heads on a struggling team: nothing ever forced the tacit knowledge into a durable form. The interview does.
Everything from capture onwards is heavily exercised and deliberately opinionated. The stage before capture - ideation, product shaping, customer requirements - is intentionally left composable, because it is the most company-specific part of any delivery process and the part where human decision matters most.
So bring your own front door. A prototype, a BRD skill that talks to customers in business language, a discovery questionnaire, an intake form: build it to fit your organization, have it emit a briefing artifact, and start the pipeline from there. The menu, not a rail principle applies at the front of the pipeline exactly as it does inside it.
One caveat learned the expensive way: keep the customer-facing business document distinct from the technical execution detail. Collapsing product language, technical language, and contractual language into a single artifact serves none of the three audiences.
None of this flexibility is bought by loosening the guarantees. Whether the spec came from a two-hour refinement session, a prototype captured in ten minutes, or an overnight eval run:
flowctl done demands summary and evidence JSON. Evidence-seeded specs get no discount for having done their homework early.The spec is what makes verifiability, accuracy, and evidence possible at all: it is the thing acceptance criteria attach to, the thing review checks against, the thing a defect can later be traced back to. Take it away and there is nothing to verify against except somebody’s memory of what was wanted.
That is why the spec earns its place. It was never there to tell you what you are allowed to explore.