Flow-Next

Agents generate. flow-next proves.

Implementation got cheap. Reviewing it, verifying it, and keeping a codebase coherent did not.

Flow-Next is a workflow plugin that runs inside your coding agent. Give it the change you want and the rules your project follows. It turns that intent into specs, implementation, review, and pull requests with evidence. Your specs, decisions, and task state live in your repository.

A real recorded run: plan, then cross-model plan review (catches a missing guard, fix, SHIP), then implement plus tests, then impl review SHIP, ending on the receipt. Nothing staged; every frame is live output.

_{The recording drives each tick with claude -p "..." (Claude Code's non-interactive / headless mode) so the whole run captures unattended. In normal use you type the prompt or the /flow-next:... command in your interactive session: same pipeline, same gates.}

📖 Doc index · 👥 Teams guide · 💬 Discord · Full documentation site: flow-next.dev

Why this exists

Generating a change is only part of the work. Someone still has to clarify 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 preserves intent beyond the chat. Focused workers reread it before implementing. Review and live QA examine the result, and the PR connects changes to their requirements and evidence. Start with one change, then adapt the same workflow to a team or an unattended backlog.

The pipeline proves the change does what was asked and records what it did; it does not prove the codebase stays maintainable. Plan review and the technical refine pass ask two structural questions while the change is still a plan (does it make the same edit twice, does it bend a dependency direction) and record the answer; measuring what happened to the code after the fact is separate, later work.

The evidence page covers the measured problem behind this approach, field use, and internal evaluations. One real change through review shows what the workflow produced in this repository.

What you get

Decide what to build, build it, and verify the result. Describe the workflow in plain language or invoke its skills directly. The host agent runs the process and adapts it to the work.

Everything reaches your queue already reviewed. Configured review checks the design or implementation and records its verdict; the work contract closes each task through flowctl done with its evidence JSON (commits, tests, PRs), which the receipt records. Review settings, completion-review policy and opt-in QA apply on both direct and planned routes.

Open a PR that already makes its argument. The pull request arrives explaining itself: which acceptance criterion each change satisfies, which decisions still need a human, what deliberately did not change.

Decide what to build before anyone builds it. An idea too big to write down gets charted one decision at a time; a conversation becomes a spec; a product owner and an engineer refine it in their own passes on one file.

Your team's context lives in the repo. A review correction becomes a lesson the next task can read. Specs, decisions, glossary, and memory stay in your repository, available to the next agent and your teammates.

Prove it in the running app, not by reading the source. Live QA drives the app the way a user would, from the spec's own criteria, and files what it finds with screenshots and a verdict you can audit.

Hand over as much as the receipts have earned. One dial from a supervised pair to a loop draining the backlog overnight. The gates do not change as you climb.

Choose the model for each job. Name a model per role once in your CLAUDE.md, or say it in the prompt for a single run. Whatever you pick, the model that wrote the diff never reviews it. The pipeline shape per item and the model per job are decided separately, and each decision prints its reason: orchestration.

A way of working, not a tool you bolt on. The same rails carry a solo developer on a Sunday and a fifty-person organisation on a rollout. The spec is the handover object, and it reads the same to product, engineering, and the next agent run.

Your process outlives your agent. The same specs, gates, receipts, and task state across harnesses. In a harness that can dispatch subagents, the same routing runs across models in-host with no bridge at all. Specs and task state live under .flow/, in Git and available for review. The files remain readable when you stop using Flow-Next.

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.

Try it on one change that crosses roles. Check whether the spec makes the intended behavior clear, the review catches a concrete defect, and the PR gives the next person enough evidence to decide. Use those handovers to judge which stages your team needs.

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

Quick start

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-; OpenCode uses /flow-next-; the other hosts accept /flow-next: (Cursor also accepts the hyphen form).

Cursor, Grok Build, or OpenCode? Install by platform has the current steps. Codex installs are per home; set CODEX_HOME when you use more than one.

Trying it for the first time? Your First 30 Minutes includes a two-file Python example, the review setup, and the output to inspect. You need your agent access, Python 3.11+, and the project tools; review and GitHub PR plumbing also use jq and gh.

The recommended happy path

/flow-next:flow <anything>           # Say what you have and let flow pick the route

Flow takes whatever you have (nothing, an idea, a spec id, a branch, a pasted bug report, a how or why question about the code, a slowness to measure, a cleanup that keeps behaviour, a design fork to settle), picks the smallest sufficient route, runs it, and stops at the next decision that is yours. Describe the request without naming a skill and flow picks it up; a stage's pick is asked inline and the run continues. /flow-next:flow --explain shows the route without running it.

Add --until=merge for a selected spec to continue through landing. On a plain attended rerun with an existing PR, flow offers landing and asks once unless you have already authorized that item; declining or leaving the question unanswered causes no landing mutation. The same path by hand:

/flow-next:capture                   # 1. Synthesize conversation → .flow/specs/<id>.md
/flow-next:work <spec-id> --no-plan  # 2. Implement a ready cohesive spec through Flow-Next
/flow-next:make-pr <spec-id>         # 3. Open a PR connecting requirements to evidence
/flow-next:resolve-pr <PR#>          # 4. Fetch review threads → triage → resolve
/flow-next:land                     # 5. Opt in to gated landing of eligible PRs

Direct execution is the default for a ready cohesive spec and a capable coding agent. Plan is chosen on a positive signal, where you asked for one, separate people will implement, or delivery is staged across several PRs. Multi-file scope or risk alone does not require decomposition. Refine unresolved material choices with /flow-next:refine; when the spec names a library or API the repo does not use yet, refine --scope=research reads the docs first. An explicit plan-review can review the spec design without task files. Live QA is opt-in (pipeline.qa set to on, or auto, which runs QA only when the acceptance criteria are UI-observable, the surface is drivable, and a target can be started, and records skipped(reason) when any of the three is absent) and neither review nor QA guarantees every regression is caught. The route guide explains when each stage helps; running lean explains the agent work each layer adds.

After every update

Nothing to do. Nothing is copied into your repo: flowctl resolves from the plugin install on every host, the agent guide is pulled live via flowctl usage, and the spec template resolves from the bundled copy. Plugin updates land silently. Re-run /flow-next:setup only when setup tells you the docs-snippet schema bumped, or to change configuration. If a repo still carries .flow/bin/ from an older install, delete it; setup offers to, and nothing reads it. Details: platforms.md.

Compose the pipeline

Start with the established workflow, then shape it in plain language. Choose which stages run, which models do the work, and what must pass before merge. Keep a policy in CLAUDE.md or AGENTS.md for repeated use, or steer one run in conversation.

The host reads the item's state and your instructions, chooses the route, and reports its reason. A stage you invoke keeps its execution and evidence contract; configured review policy applies across the arrangements you choose. Pipeline variations · Orchestration and model routing · Cookbook.

One change through review

In PR #215, a performance change batched Git searches. Requirement R8 said reference attribution must stay unchanged. Review caught a forced-color Git setting that broke output parsing and dropped references. The correction added --color=never; the task recorded the fix and verification, and the PR pointed the human reviewer at that exact change.

Follow the requirement, correction, and evidence.

The optional HTML views present the same spec and PR information for readers who prefer a visual review surface.

Going autonomous

/flow-next:flow --auto drives one ready spec to a draft pull request by default. Add --until=merge to carry the selected spec through land's CI and review convergence, gated merge, spec close, and persistence. Destination and interaction mode are independent; /flow-next:flow --until=merge uses the attended route. Release and tracker actions retain their existing authorization and configuration. Run flow --auto once per item, or flow --auto --tick under your host's loop primitive where sessions are short. The same skills you use interactively do the work.

/flow-next:flow --auto                      # one item, hop after hop, to its draft PR
/flow-next:flow --auto <spec-id> --until=merge # same route through gated landing
/loop 30m /flow-next:flow --auto --tick     # one hop per interval on a host that loops
/goal keep running /flow-next:flow --auto --tick until PILOT_VERDICT=NO_WORK

--tick performs at most one landing tick. A longer run can continue across CI and review waits using land's cadence; external waits do not consume pilot strikes. Merge consent covers the selected spec and PR while active, including retries. A fresh session needs the flag again or current explicit authorization; old receipts are not consent. See the landing contract for scope, ownership, and recovery.

/flow-next:pilot keeps working for one release as an alias for flow --auto --tick.

Work the ready specs overnight. Plan changes with unresolved design risk,
work fully understood changes directly, review with another model family,
and run live QA before opening the PR. Stop on product decisions I need
to make. Use land under this repository's merge policy.

Drive a loop for your host, or read unattended operation for isolation, readiness, and stop conditions. The field case describes a run that landed 38 PRs under one paragraph of policy.

Existing Ralph installation? Ralph is deprecated; its reference remains available. New setups should use flow --auto and land.

Why it works

Where it fits

Flow-Next is useful when requirements, coordination, or review deserve a record that outlives a chat. It works inside your coding agent and alongside your repository, tests, CI, and tracker. Use direct edits for disposable work where no durable context matters.

Humans own product decisions, risk tolerance, and production responsibility. The workflow makes those decisions easier to inspect through specs and evidence. Stage selection and model routing remain yours to shape.

Commands

Use the skill name or describe what you want in the agent conversation. The skills catalog covers all 31 skills and their invocation forms; the CLI reference covers scripting and state inspection.

Flow picks the route from whatever you have; --explain shows the route without running it. The optional /flow-next:chart stage resolves an oversized idea one decision at a time before capture. Review findings keep a defect's identity and history across review rounds.

Adopting in a team

Start with one repository and one change. Product reviews the goal and acceptance criteria in a shared spec. Engineering adds constraints and reviews the approach. Agents implement the tasks. The reviewer receives a PR connecting the changes to those criteria and their evidence.

After the trial, judge whether the spec surfaced a missed decision, review found useful defects, and the PR reduced investigation work. Add the stages that earn their time. Team guide.

Keep your existing board when the team needs it. The tracker bridge projects specs to Linear, GitHub, GitLab, or Jira and reconciles them two-way. Claude Code teams can deploy the plugin through managed settings, with setup once per repository.

Where to look

Requirements

Flow-Next is MIT-licensed. You supply access to your coding agent and its providers, plus your project environment. Additional planning, implementation, review rounds, and live QA consume agent usage. There is no Flow-Next account or hosted service to run.

• Python 3.11+ (or the py launcher on Windows): the bundled flowctl CLI is pure-stdlib. Launchers skip broken aliases and working interpreters below the supported floor before loading flowctl.
• jq and gh: required for the review subsystem and PR plumbing.
• bun (optional): only needed for the Ralph TUI.

Platforms

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

Detailed install + cross-platform patterns in docs/platforms.md, the canonical home for the tiering sentence above.

Upgrading from 0.x? The 1.0 release renamed the epic surface to spec; the legacy aliases and automated migration commands were removed in 3.0. Update the plugin, then follow the manual three-step pre-1.0 layout port in troubleshooting.

Ecosystem

Contributing

Bug reports and PRs welcome: start at CONTRIBUTING.md (local dev, adding skills, the docs-only rule) and SECURITY.md for private disclosure. Questions and show-and-tell: GitHub Discussions. Or come say hi on Discord.

Every PR runs the same gate: the full test suite on a 3-OS matrix (Ubuntu / macOS / Windows) plus an offline docs-linkcheck - green CI is the merge floor.

Also check out

GNO: local hybrid search for your notes, docs, and code. Long-term memory over your files via MCP.

bun install -g @gmickel/gno && gno mcp install --target claude-code

License

MIT. See LICENSE.

Made by Gordon Mickel · @gmickel · gordon@mickel.tech