FAQ
Each question below is an objection raised in a real coaching session, answered the way it gets answered in the room. Four of the longer objections have their own pages now: is this waterfall?, is this a rigid conveyor?, what do I get over prompting directly?, and do I have to write the spec before I build anything?
Do I need all of this?
Section titled “Do I need all of this?”No. Use the smallest sufficient workflow. Direct execution through /flow-next:work <spec-id> --no-plan is the default for a ready spec. Plan is chosen only on a positive signal: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs. Risk, size, and file count never trigger plan on their own. Design risk routes to plan-review, which reviews a spec with zero tasks; unresolved product or authority choices route to refine. A small local change goes direct: no spec, changed, checked and handed back. For spec-backed execution, the strong spec and configured review, evidence, and completion gates remain in force on both routes.
The design intent is a composable pipeline: the stages are composable primitives, and every subset keeps the same execution, evidence, and review contracts. Start with /flow-next:flow; it picks the route and adds a stage only where the risk calls for it.
Isn’t this slower than just using my agent?
Section titled “Isn’t this slower than just using my agent?”No. On the actual work, Flow-Next is as fast or faster: across more than 170 full end-to-end runs, each case run several times, the change comes back in about the time plain Claude Code, or your harness, takes, often less. The result is better than the plain agent’s even before any review, and the optional stages, cross-model review and live QA, widen the gap to up to 25% better outcomes, especially on large and long-horizon work. /flow-next:flow picks the route and adds a stage only where the risk calls for it, and an attended run hands the result back before its review runs in the background. The numbers: the 7.0.0 release notes.
Won’t the spec balloon into the app? How big is a spec supposed to be?
Section titled “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 code and its commits; when a spec does get a plan, each task is sized to fit one implementation 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?
Section titled “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?
Section titled “Are Flow-Next’s guardrails a security control?”No, and the taxonomy matters. Flow-Next’s guardrails - review gates, receipts, the readiness gate, typed stop verdicts - 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.
Does autonomous mode lower the quality bar?
Section titled “Does autonomous mode lower the quality bar?”No. The same gates fire at every autonomy rung. flow —auto and Land run the same review and evidence contracts you run interactively, and flow --auto classifies every hop from the same routing references attended flow reads, so the route --explain shows is the route the unattended run takes. What changes is who is present. Autonomous runs are more thorough in one respect: with nobody there to decide what is left, review loops until SHIP, every decision the run made on your behalf is listed in the PR, and nothing merges without the gate tree passing.
Can’t I just tell the agent to write clean code?
Section titled “Can’t I just tell the agent to write clean code?”It has been tested. Quality-aware prompting lowered initial verbosity by about a third, changed the rate of decay not at all, left every pass-rate subtype statistically unchanged, and cost up to 48% more. A stricter instruction is an intervention on the starting point, not on the trend. The numbers, the benchmark they come from, and the boundary between what it shows and what we claim: Evidence & evals. What the pipeline does with that result, and the limit it states about itself: Does the pipeline keep the codebase maintainable?
Does the pipeline keep the codebase maintainable?
Section titled “Does the pipeline keep the codebase maintainable?”The pipeline proves the change does what was asked and records what it did; it does not prove the codebase stays maintainable. Two things follow. Structure is decided before code exists, so plan review asks two questions from the plan as written - does it make the same edit or decision in more than one place, and does it add a back-edge against the dependency direction or new branching to a module’s hottest function - and record a concrete answer or none identified, advisory, never a gate. And nothing here claims the pipeline prevents, stops, or fixes decay; measuring the delta is separate, later work, and a claim of benefit waits for a replay study. The mechanism and its place in the spine: How work gets proven.
What does it cost to try, and to leave?
Section titled “What does it cost to try, and to leave?”Flow-Next is MIT-licensed. You supply your agent access, Python 3.11+, the review and PR tools, and your project environment. Additional agent passes consume your provider usage. There is no Flow-Next account or hosted service. Install prerequisites list the tools.
Your specs and evidence remain readable files without Flow-Next. Keep them if you want the history. Uninstall explains plugin removal, project-state cleanup, and the instruction blocks. Deleting .flow/ deletes that local history; it is not required merely to stop using the plugin.
Where do I ask something this page missed?
Section titled “Where do I ask something this page missed?”GitHub Discussions for questions and show-and-tell, issues for bugs.