Flow-Next runs inside your coding agent. Give it anything you need to fix, improve, or build. It picks the pipeline for that kind of work, runs it with a different model family reviewing every handover, and stops at a pull request that carries its own evidence.

Every stage prints ran, skipped(<reason>), or failed(<reason>). The model that wrote the diff never reviews it. Specs, decisions, task state, and receipts live under .flow/ in your repository and stay readable if you stop using Flow-Next. flow --explain <anything> prints the route it would take and why, and writes nothing.

First-class on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, and OpenCode.

📖 Documentation: flow-next.dev · 💬 Discord

Why this exists

Generating a change is the cheap part. Someone still has to pin down the requirement, keep the implementation aligned with it, check the result, and explain the diff to a reviewer. Flow-Next makes that work repeatable. A spec at .flow/specs/<id>.md preserves intent beyond the chat, a fresh worker rereads it before touching code, a second model family reviews the result, and the PR maps every change to a criterion and its evidence. The pipeline proves the change does what was asked and records what it did; it does not prove the codebase stays maintainable.

Install

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

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

droid plugin marketplace add \
  https://github.com/gmickel/flow-next
# /plugins → install flow-next

Use installation commands in your terminal or the host's plugin interface as shown above. Workflow invocations belong in the agent conversation. Codex uses $flow-next-<name>; OpenCode uses /flow-next-<name>; the other hosts accept /flow-next:<name> (Cursor also accepts the hyphen form).

Cursor, Grok Build, or OpenCode? Install has the current steps per host, including the Cursor team-marketplace import and Claude Code managed settings for an organisation. Codex installs are per home; set CODEX_HOME when you use more than one.

Start one change

1. Install for your host with the block above, then run /flow-next:setup in a project (Codex: $flow-next-setup). Setup writes the agent instruction snippet and asks for a review backend once.
2. Say what you have in the agent conversation: /flow-next:flow <anything>. Flow reads a pasted error, an idea, a spec id, a branch, or a ticket, picks the smallest sufficient route, runs it, and stops at the next decision that is yours. /flow-next:flow --explain prints the route and writes nothing. The optional /flow-next:chart stage sits before capture for an idea too big to write down in one pass.
3. Read the PR it opens. Each stage line reads ran, skipped(<reason>), or failed(<reason>), and the PR body maps each change to the acceptance criterion it satisfies.

Your first 30 minutes walks the same three steps on a two-file Python example, including the review setup and the output to inspect. You need your agent access, Python 3.11+, and the project's own tools; review and PR plumbing also use jq and gh.

Land a pull request

/flow-next:land <PR> resolves feedback and CI for one named PR and squash merges when currently authorized. The completed spec and final task statuses are committed by make-pr before it composes the aid artifact and opens the PR; the merge carries them to the base. Land reads every matching spec at the PR head and requires all to be closed.

For several PRs, enumerate open PRs and inspect each head: select it only when at least one spec has branch_name equal to its head branch and every such spec is closed (status: done), then invoke land for each selected PR with current merge authorization. Re-read each PR before its invocation; land never discovers a repository-wide batch.

A repository can tighten the review gate in its instruction file, in branch protection, or with land.mergeVerdictCommand. See the runtime landing and manual rebase guidance and major-upgrade notes. Release preparation follows the repository's release documentation as a separate step.

Where to read more

The documentation lives at flow-next.dev. The repository keeps this page and the reference files the skills read at runtime under plugins/flow-next/docs/.

• Introduction: what the pipeline does, stage by stage, and what it refuses to claim.
• Choosing your route: which stages a bug, a feature, a refactor, or a performance request takes, and why the direct route is the default.
• Going autonomous: flow --auto, --until=merge, the strikes ledger, and the stop conditions.
• For teams: the spec as the handover object between product, engineering, and the agent, plus the tracker bridge to Linear, GitHub, GitLab, and Jira.
• Model routing: four tiers, the routing block in your instruction file, and what each harness can reach.
• Review backends: RepoPrompt, Codex, Copilot, Cursor, Claude, and host review, with the cross-family rule.
• Configuration: every .flow/config.json key, generated from the schema.
• Skills: all 31 skills and their invocation forms, and the CLI reference for flowctl.
• Changelog: release highlights; CHANGELOG.md in this repository is the full record.
• Discord for questions, and CONTRIBUTING.md for local development and the docs-only rule.

Where it already runs

Flow-Next's ways of working are coached and run in enterprise engineering organisations worldwide, from CAD and construction software to proptech and education, across modern monorepos, hundred-repo microservice estates, and 30-year-old legacy stacks, on GitHub Enterprise, GitLab, and Jira. A 2-3 hour structured discovery interview reliably produces 8-11 implementation-ready specs with numbered acceptance criteria, boundaries, and task breakdowns; the edge cases surface in the interview instead of the sprint. Receipts, evidence JSON, and review gates are the audit trail enterprise adoption asks for: approval checkpoints and traceability are built in.

The open-source record is linkable, so it speaks in its own words: an outside contributor shipping a correct flowctl patch in PR #95, a feature in awesome-claude-code-workflows for plan-first workflows, Ralph autonomous mode, and receipt-based gating (#96), and a 3-OS test matrix on every push, because the field runs all three.

"I am enjoying your version of all these cool new plugins. So far yours has worked the best." @patrickmichalina

"really enjoying this project, thanks for making it and making it public" @possibilities, external contributor

"it’s been really useful in my workflow." @raydocs

License

MIT. See LICENSE.