FAQ

These are not invented softballs. Each question below is an objection raised in real coaching sessions or real adoption conversations, answered the way it gets answered in the room.

Do I need all of this?

No. Use the smallest sufficient workflow. A one-line fix needs no spec at all - just fix it. A small, well-understood change might be /flow-next:plan + /flow-next:work and nothing else. The full pipeline - interview, spec, plan review, work, implementation review, QA, PR - is what a risky, ambiguous, or team-visible change deserves, not a tax on every keystroke.

The design intent is a menu, not a rail: the stages are composable primitives, and every subset keeps the same execution, evidence, and review contracts. Start with plan + work; add stages when a change is expensive to get wrong.

Won’t the spec balloon into the app? How big is a spec supposed to be?

This is the most common sizing fear, and it comes from imagining the spec as a requirements document in the waterfall sense. It is not. A Flow-Next spec captures intent, boundaries, and numbered acceptance criteria - what must be true when the work is done - not the implementation. Most specs are one to two screens. The implementation detail lives in the plan’s tasks, each sized to fit a single worker context.

If a spec is growing past a few screens, that is the signal to split it into multiple specs with dependencies, not to keep typing. The spec is the ratchet and the handover object - not a second codebase to maintain.

Am I building a spec library I’ll have to maintain forever?

No - this misconception inverts the model. A completed spec is immutable change history, like a merged PR: it records what was decided and built, it is never edited again, and it accrues value precisely because it does not change (the R-IDs in it mean the same thing forever). You do not “maintain” completed specs any more than you maintain your git log.

Living documentation - architecture notes, runbooks, READMEs - is a separate concern and stays wherever you keep it today. The spec directory is an audit trail, not a wiki.

Are Flow-Next’s guardrails a security control?

No, and the taxonomy matters. Flow-Next’s guardrails - review gates, receipts, Ralph’s hook-enforced rules, destructive-command blocking - are process controls for agent workflows: they constrain what an agent does inside your development process and leave evidence behind. They are not, and do not replace, security controls: authentication, authorization, secrets management, dependency scanning, branch protection, CI policy.

The two compose. Receipts and evidence trails make good inputs to a security review - an auditable record of what was generated, reviewed, and by which model - but your security posture is defined by your security controls, with or without Flow-Next.

Isn’t spec-first just waterfall with extra steps?

No, and it is worth being precise about why, because this is the objection the most experienced person in the room usually raises.

Waterfall has three properties: phases you cannot return to, a plan frozen before contact with reality, and handovers that discard what the next phase learns. Flow-Next has none of them. Stages are re-enterable (re-interview after planning exposes a hole, re-plan after a task proves the approach wrong). The spec is written at the moment of most knowledge, not least - capture runs after you explore, not before. And the handover is the opposite of lossy: evidence, review verdicts, and QA results are written back into the spec, so the spec at merge is not the spec at capture.

The concession worth making honestly: this does ask for more thought earlier than a loose ticket does. It does not ask for more commitment earlier. The spec is a ratchet, not a gate - it stops you sliding back, it does not decide what you are allowed to explore.

Also check what you are comparing against. The realistic alternative is not textbook agile; it is a vague ticket thrown at an agent, then prompt-look-fix in circles until it looks close enough. That loop discovers the requirement and then throws it away, and it forecloses autonomy permanently - you cannot automate a process whose only record is a chat scrollback. Full argument: Prototype-Driven Specs.

Do I have to write the spec before I’m allowed to build anything?

No. That inverts the model. The best specs are captured from exploration - a prototype, a spike, a bake-off, an eval run, a half-formed briefing doc from a cross-functional session. Build the thing badly on purpose to find out what it should be, then say “capture a spec from this prototype, ignore the code quality - I want the intent and the requirements it demonstrates.”

Some questions genuinely cannot be answered in prose. “How should this look?”, “how should this behave?”, “does this state model survive the awkward cases?” need a concrete artifact to react to. Prototyping is how you raise the fidelity of the discussion, and it is not a front-end-only tool - a small interactive harness that drives a state machine through hard cases is often the highest-value prototype on a backend change.

Prototyping is also just the sharpest instance of a general move: let something real answer the question, then capture the answer. Match the route to the question - a performance complaint wants a probe (“run the load test, then spec the fixes the numbers point to”), a “which library” argument wants a bake-off, a bug report wants a reproduction (the failing test becomes R1), a model or prompt choice wants an eval. Most of these run unattended, so the agent can do the finding-out before anyone commits to a shape.

What happens to the prototype code is a separate decision, made at the plan stage against your architecture and standards: keep it as throwaway evidence, keep the presentation layer and re-base what sits behind it, or (occasionally) build on it directly. See Prototype-Driven Specs.

Isn’t this just a rigid conveyor belt?

That is the most damaging misreading in the field, and it has a dedicated page: Menu, Not a Rail. Short version: skip stages, reorder them, prompt into any of them, one-shot chain the whole pipeline, parallelize disjoint tasks, route a different model to every step. The rails exist so newcomers and autonomous loops get a predictable result - they were never a prohibition on exploration.

What do I actually get over prompting an agent directly?

Proof. A bare agent session produces code and a confident narrative about it. The pipeline produces code plus artifacts: a spec with numbered criteria, a cross-model review verdict on disk, evidence JSON on every completed task, a PR body that maps criteria to commits. When the change ships, you can show that it does what was asked - not just believe it. The full argument is the verification spine.

Can’t I just tell the agent to write clean code?

It is the cheapest-sounding alternative to all of this, and it is the one objection that now has a measured answer rather than an argument.

SlopCodeBench (Orlanski et al., Mar 2026) chains an agent across 93 checkpoints of extending its own prior code, under specifications that fix only external behavior, with the tests hidden and no prior conversation carried over. Across 11 models no agent solved a single problem end-to-end: the best strict pass rate was 17.2%, and it collapsed to 0.5% by the final checkpoint. Quality degraded in 80-90% of trajectories, cost per checkpoint grew 2.9x without buying correctness, and against a panel of 48 maintained open-source repositories the agent code was 2.2x more verbose, with the gap widening every iteration while the human repositories stayed flat.

Then they tested the prompt fix directly. Anti-slop and plan-first prompts lowered initial verbosity by about a third, and did nothing to the rate of decay: per-checkpoint degradation slopes were statistically indistinguishable from baseline, no pass-rate subtype improved, and runs cost up to 48% more. On one problem the quality prompt spent nearly 3x and the pass rate went down.

So a stricter instruction is an intervention on the starting point, not on the trend. What the authors call untested is enforcing structural discipline across checkpoints, through training or through tooling, and that is what the pipeline is: a spec whose numbered criteria outlive the session, a plan reviewed before code exists, a cross-model review verdict on disk, evidence attached at every completed task. That is the bet, stated as a bet - nobody has published that tooling-side gates stop the decay either. What is settled is the cheaper claim: prompt hygiene alone will not, and a pipeline that refuses to advance without proof at least makes the drift visible while there is still time to act on it.

Does autonomous mode lower the quality bar?

No - the same gates fire at every autonomy rung. Pilot, Land, and Ralph run the identical review and evidence contracts you run interactively; what changes is who is present, not what is proven. Autonomous runs are more conservative in one respect: they always open PRs as drafts and never merge without the gate tree passing.

What does it cost to try, and to leave?

Trying: one plugin install, one /flow-next:setup in a repo - state lives repo-locally under .flow/, no server, no account, no runtime dependencies beyond Python 3.11+. Leaving: /flow-next:uninstall prints the two rm -rf commands and cleans up its doc blocks (see Troubleshooting). Your specs are markdown; they remain readable forever, with or without the tool.

Two of us created specs and both got fn-122 - is the repo broken?

No. The full id is the identity (fn-122-your-slug vs fn-122-other-slug). A shared ordinal is a warning from flowctl validate --all, not a break, and bare fn-122 lists the candidates instead of guessing. Do not renumber - ids never change, and those strings already live in commits, PRs, and tracker comments.

What happened is parallel allocation: two branches, worktrees, or agents that each saw the same local max both took the next number. That window is smaller now (allocation scans every worktree and every ref), but separate clones that have not fetched each other can still collide. If the team runs a tracker, set flowctl config set tracker.specIds tracker so new specs mint from the issue key (wor-17-…, gh-123-…, gl-N-…) and skip the race entirely. Recovery steps: Troubleshooting.

Where do I ask something this page missed?

GitHub Discussions for questions and show-and-tell, issues for bugs.