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 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.

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.8+. 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?

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