FAQ
Each question below is an objection raised in a real coaching session, answered the way it gets answered in the room. Three 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. 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 composable pipeline: 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?
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 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?
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, 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.
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. 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.
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 does it cost to try, and to leave?
Section titled “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.
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.