Introduction
Flow-Next is a workflow plugin that runs inside your coding agent. Agents generate. Flow-Next proves. The checks establish what changed, which acceptance criteria the change covers, what an independent reviewer found, and which tests ran; whether the change is the right product decision stays with you. You describe what you have (an idea, a ticket, a bug report, a question about the code, a ready spec) and Flow picks the smallest sufficient route, runs it, and stops at the decision that is yours. The spec and its state live in your repository, so a new session or a different agent reads the same record.
Flow-Next is fast on the actual work: across more than 170 full end-to-end runs, the change came back in about the time plain Claude Code, or your harness, takes, often less. The result is already better than the plain agent’s before any review. The optional stages, review by another model and live QA in the running app, widen the gap to up to 25% better outcomes, especially on large and long-horizon work, and Flow adds a stage only where the risk calls for it.
What you say, what you get
Section titled “What you say, what you get”Type the request in ordinary language. On a host that needs the command, prefix it with /flow-next:flow ($flow-next-flow on Codex, /flow-next-flow on OpenCode).
| You say | What Flow does, and what appears |
|---|---|
| ”Lock down what we just discussed and build it” | Writes a spec from the conversation and shows you its summary, implements it on the route it picked, runs the configured review inside work, and commits the change on a local branch. Say “open the PR” and it opens one. On disk: the spec under .flow/specs/, task evidence, a review receipt, the branch. |
| ”Work ticket WOR-17” | Reads the issue through the access your session already has and routes on its content and current state: a clear request is captured as a spec and built, a defect report is checked for existing fixes and reproduced first, a question is answered, and an issue already linked to a spec resumes from that spec. On disk: whatever the route produces, as in the rows above and below. |
”This fails: <pasted stack trace>” | Checks for an existing fix, reproduces the failure, confirms its cause, and bisects to the introducing commit when a known-good revision exists. The failing reproduction becomes the requirement; the fix must make it fail on the base and pass on the head. Then it reviews the fix and commits it on a local branch, ready for a PR when you ask. On disk: the minimal spec, the failing-then-passing test, the record of each step, the receipt, the branch. |
| ”Why does the parser reject empty headers?” | Answers with citations from git history, the PRs behind the commits, and the project’s bug and decision memory, each finding tiered direct, supported, inferred, or unknown. Writes nothing under .flow/ and opens no PR. |
| ”Work fn-12” | Reads the spec’s state, records the route on the spec, runs work with the configured review, and stops with the change committed on a local branch. On disk: the recorded route, task evidence, the receipt, the branch. |
When you are at the keyboard, change-producing routes on a spec end with the change committed on a local branch and one line: say “open the PR” when you want it. The pull request then opens ready for review unless something is left open for a human, and the merge is yours. A small fix without a spec is changed directly and handed back; ask for a PR when you want one. flow --auto opens the pull request itself. The investigation route ends at the cited answer.
Inspect what supports the result
Section titled “Inspect what supports the result”- Independent review by risk. Review runs through the
review.backendyou set at setup: three reviewers for a risky change, one otherwise, and a small output, wording or display fix is skipped with the reason recorded. The verdict lands as a receipt on disk.review=noneis a recorded skip, never a verdict. - Test evidence. The work and review contracts require commits and test commands before a task closes;
flowctl donerecords what the worker supplies, and the reviewer reads that record. Worker narration never supplies a missing verdict. - Visible skips. Every stage Flow reaches prints one line:
ran,skipped(<reason>), orfailed(<reason>). Live QA defaults tooff;autoruns it only when the acceptance criteria describe a UI on a surface the QA driver can reach and start.
Follow one real change through review to see a finding become a correction commit and reach the PR.
You keep the controls
Section titled “You keep the controls”Flow asks a pick inline, at most one question per hop, when a stage produced options. It stops at a run-ending decision: merge, a review verdict that needs a person, a product question no stage framed as options. flow --explain <what you have> prints the route, its signal, and the safe skip, and writes nothing.
Every stage Flow runs is a skill you can invoke by name: capture, refine (interview), plan, plan-review, work, qa, make-pr, resolve-pr. For a ready spec, direct execution is the default; planning into tasks needs a positive signal. How Flow chooses lists the signals and shows how to read and override a route.
Choose how much to attend
Section titled “Choose how much to attend”By default, attended Flow ends with the change committed on a local branch and opens the pull request when you ask; it does not ask about landing a pull request it just opened. With --until=merge, it invokes land for the selected item. Plain attended flow on an existing PR asks once before landing unless that item is already authorized. /flow-next:flow --auto runs the same conductor unattended. One invocation carries a ready spec to a PR, hop after hop, without asking: it decides from evidence, writes every decision into the PR, and reports NEEDS_HUMAN only for a call a person has to make; land merges the result under your CI and review rules. Flow and the road ahead records how the one conductor came about and what comes next.
Run across your configured harnesses
Section titled “Run across your configured harnesses”First-class on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, and OpenCode. The entry is the same word on every host in that host’s spelling: /flow-next:flow, $flow-next-flow, /flow-next-flow. Install carries the prerequisites (Python 3.11+, jq and gh, a reachable reviewer) and the setup invocation per host; the platform matrix carries the differences in model routing and delivery.
Alone or with a team
Section titled “Alone or with a team”Alone, start with one change. Tell Flow what you have, read the spec summary it shows you, then say “open the PR” and inspect it. Add flow --auto and land when you want the same gates to keep working between your visits.
With a team, product reviews intent and acceptance criteria in the spec, engineering adds constraints and reviews the approach, agents implement, and the reviewer receives a PR that maps changes to requirements and evidence. Keep your existing board; the tracker bridge keeps it in step with the spec. For teams shows the handovers and a first-week trial.
Start one change
Section titled “Start one change”- Install for your coding agent.
- Run setup in the repository you want to change.
- Tell Flow one change and read what it decided.
The tutorial includes a two-file Python example if you have no small change ready. Keep your normal Git and CI workflow. For teams covers adoption.