Flow-Next routes an agent from a bug report to a pull request

The route is chosen from what you ask, not from a fixed script

The plugin takes a bug, an idea, a ticket or a slow page and picks the route that kind of work needs. The README lays out the routes as a table of inputs and responses, and the interesting part is how differently a failure and a question are handled. Paste a stack trace and the failure becomes a failing test, the cause is fixed, and you see the test move from red to green. Ask for a feature, or refer to the conversation you just had about one, and a spec with numbered acceptance criteria is written first, then built, then reviewed, with a pull request that maps every change back to a criterion. For a slow page, the plugin measures the real page before touching anything, so the before and after numbers are the evidence rather than a claim. A refactor is pinned with a characterization test first, so the current behaviour has to survive the change. A question about why a parser rejects empty headers is answered from git history and the project decision memory, with citations, and writes nothing at all.

The spec lives in .flow/specs/<id>.md instead of a chat that scrolls away

The reasoning behind the design is stated in the README's own terms: writing the code got cheap, and everything around it did not. Pinning down what was asked, keeping the build aligned with it, checking the result and explaining the diff are the steps where agent-written code quietly goes wrong. The spec is therefore a file in the repository at .flow/specs/<id>.md, and the build reads it before it touches code. Alongside it sit decisions, task state and receipts, all under .flow/. The practical property of that layout is portability. The artefacts stay readable if you stop using Flow-Next, so a workflow tool cannot hold your team's knowledge hostage. That is a different bargain from tools that keep planning notes in a proprietary format, and it also means the directory is a thing you will see in every pull request the workflow opens, which is worth knowing before you let it write to a repository that other people review.

The model that wrote the diff never reviews it

Review is routed by risk, and the reviewer comes from another model family. The stated reason is short: a model reviewing its own work shares its own blind spots. In the measured runs, this stage earned its place. On a large feature, plain Claude Code shipped a data-integrity bug in every run and Flow-Next's reviewers caught it every time, before the pull request. On a held-out Rust feature, four real bugs were fixed, including a race condition, where plain Claude Code failed one run in three. The rule also appears in the unattended mode, where the workflow keeps fixing until the reviewer signs off. Two things follow from the design. The first is that review is not free: a second model has to be available to the plugin, so the cost and latency of a pull request depend on which agent family you point the review at. The second is that the guarantee stops at the review. The README is explicit that the plugin cannot promise the codebase stays easy to maintain, because that still takes people who care about it.

Every stage prints ran, skipped(reason) or failed(reason)

Observability is built into the output rather than bolted on. Every stage prints one of three lines, ran, skipped with a reason, or failed with a reason, so you can see what happened and what did not. A stage that does nothing is therefore visible, which matters more in an automated workflow than a stack trace would. The flags define how much supervision you want. The plain flow reports and stops. The auto mode, /flow-next:flow --auto, never stops to ask, keeps fixing until the reviewer signs off, and writes every call it made on your behalf into the pull request, which is the part that makes unattended runs auditable. Adding --until=merge takes it further: the workflow watches CI and review threads and merges the pull request when your checks allow it. For diagnosis, flow --explain <anything> shows the route the plugin would take and why, without running it, which is the fastest way to find out why a particular input was routed the way it was.

Installing the plugin on Claude Code, Codex and Factory Droid

Flow-Next runs on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, OpenCode and Meta Muse Code, and the installation differs per host. On Claude Code you add the marketplace and install from it.

/plugin marketplace add \
  https://github.com/gmickel/flow-next
/plugin install flow-next
/reload-plugins
/flow-next:setup

On Codex you clone the repository and run the install script, which takes the plugin name as its argument. The script also accepts a CODEX_HOME override for a second Codex home, and the setup step is triggered from a Codex conversation afterwards.

git clone https://github.com/gmickel/flow-next.git
cd flow-next
./scripts/install-codex.sh flow-next
# For another Codex home (any path you like):
# CODEX_HOME="$HOME/.codex-work" ./scripts/install-codex.sh
# Run once per home.
# then, in your project's Codex conversation: $flow-next-setup

Factory Droid uses its own marketplace command, after which flow-next is selected from the plugin list.

droid plugin marketplace add \
  https://github.com/gmickel/flow-next

The repository keeps the host-specific pieces under plugins/ and the installers under scripts/, and the documentation lives on flow-next.dev.

What the speed and quality numbers do and do not cover

The README reports measurements over more than 170 full end-to-end runs against plain Claude Code on the same model, with each case run several times, hidden tests the agent never sees checking every result, and a blind judge scoring the handoff. The reported figures are up to 1.9x faster and 25 percent better quality on a large feature, 1.2x and 48 percent on a held-out Rust feature, about 2x and 9 percent on a hard bug, 1.2x and 10 percent on a simple bug, and 1.1 to 1.3x and 8 percent on a small feature. Unattended with --until=merge, a large feature reportedly went from spec to merged pull request in about half the time plain Claude Code took to build it. Read the scope carefully, because it is narrower than the headline. Every number compares against one baseline, plain Claude Code on the same model, so the figures say little about Cursor, Codex or the other hosts the plugin supports. The quality percentages also come from a blind judge, which is a reasonable protocol but not the same as your own reviewers, and the README itself points to an evidence page for the method and the remaining numbers.

Version 9 releases, an MIT licence and a plugin layout you can read

The project moves quickly. The last push was on 2026-10-19, and three releases landed within two days: v9.1.1 and v9.1.0 on 2026-10-19, and v9.0.2 on 2026-10-18. A plugin that installs from a marketplace and rewrites your working tree is exactly the kind of tool where the release cadence is an upgrade cost, because a minor version can change a route or a stage output. The licence is the MIT License, with a LICENSE file at the repository root, so the redistribution terms are the permissive ones you would expect, though how that interacts with your own policies is a question for your legal review rather than for this article. Two structural choices reduce the risk of a bad upgrade. The first is that the workflow state lives in .flow/ in plain files you can read, diff and delete. The second is that the plugin directory is visible in the repository layout, with plugins/, scripts/, agent_docs/ and host-specific folders such as .claude-plugin/ and .cursor-plugin/, so what you install is inspectable before it runs.

Editorial conclusion

Adopt Flow-Next when your team already lives in one of the supported coding agents and needs the plan, the review and the evidence to live in the repository rather than in a chat log. Skip it if you need measured gains against an agent other than Claude Code, since the published numbers compare against plain Claude Code on the same model, or if a workflow that can merge pull requests unattended conflicts with your review policy. Before the first run, check that .flow/ is something you want committed, and decide in advance whether --auto or --until=merge is allowed to act on your behalf, because those flags keep the workflow moving without asking you anything.

Frequently asked questions

Official sources

1. gmickel/flow-next on GitHub
2. License: MIT
3. Project website
4. README
5. Releases