Flow-Next

Flow-Next

Agents generate. flow-next proves.

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

Flow-Next is the workflow layer that carries the weight: durable specs, re-anchored workers, adversarial cross-model review, and a receipt behind every claim of done. Everything lives in your repo, and uninstall is rm -rf .flow/.

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

Agentic engineering compresses implementation from weeks to hours, and it quietly removes every safety valve pre-agentic Agile relied on. The standups, the hallway clarification, the mid-flight course correction that used to finish a vague ticket over a two-week cycle: gone. When an agent can ship the task in one sitting, a rough ticket plus a chat scrollback is the whole work surface.

That work surface fails predictably. Agents drift mid-task, forget requirements, overfit to recent context, and hand reviewers 10K-line diffs with no focus signal. The bottleneck did not disappear; it moved upstream, to requirements, review, and verification. The spec has to carry the weight.

That failure surface is measured rather than asserted. SlopCodeBench (Orlanski et al., Mar 2026) chains an agent across 93 checkpoints of extending its own prior code, under specs that fix only external behavior:

• No model finished a problem. Across 11 models, not one solved a single problem end to end.
• The pass rate collapses as the work goes on. The best strict pass rate was 17.2%, down to 0.5% by the final checkpoint.
• Quality erodes with every iteration. Code quality degraded in 80-90% of trajectories, diverging further from maintained human repositories at each step.
• The cheapest fix was tested and ruled out. Quality-aware prompts lowered initial verbosity by about a third, changed the rate of decay not at all, left every pass-rate subtype statistically unchanged, and cost up to 48% more.

Better instructions do not survive iteration. What the paper's authors name as untested is enforcing structural discipline across checkpoints through tooling, and that is the bet this repo makes.

Flow-Next puts the discipline in the operating model. It turns rough intent into durable specs, specs into context-sized task graphs, task graphs into re-anchored worker runs, and implementation into reviewed PRs with receipts. From the conversation you already had to a merged pull request, it defines six named handover objects, each reviewable on its own, verified by a different model, and frozen at handover. The artifact chain is the conversation that would otherwise be missing.

What you get

Flow-Next is an AI agent orchestration plugin: agent-native skills layered on a bundled pure-stdlib Python CLI (flowctl). The host agent is the intelligence; flowctl is the deterministic plumbing. One arc, from the conversation you already had to a merged pull request: decide what to build, build it, prove it. Every skill runs from plain language, and the slash commands are the precise form of the same thing. No external services, no SaaS, no global config.

Ship more without lowering the bar. A different model reviews every plan and every implementation, the loop iterates until SHIP, and a task cannot be marked done without evidence JSON.

Reviews stop being where work waits. The pull request arrives explaining itself: which acceptance criterion each change satisfies, which decisions still need a human, what deliberately did not change.

Your team's context stops living in three people's heads. Specs, decisions, glossary, and memory are files in your repository that the next run reads. A teammate joining on Monday reads the same thing the agent does.

Climb to autonomy without a leap of faith. One dial from a supervised pair to a loop draining the backlog overnight. The gates do not change as you climb.

Spend the expensive model where it earns its keep. Route any model to any role, by parameter or by sentence. Cost and quality become steering decisions you make per task.

Your process outlives your agent. The same specs, gates, receipts, and task state across harnesses. Everything sits in your repository under .flow/, in git and code-reviewable, and uninstall is rm -rf .flow/.

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.

Adoption is not uniformly euphoric, and pretending otherwise would cost this page its credibility. The consistent pattern: product and delivery roles feel relief early, with specs they can read, evidence they can audit, and progress they can see. Senior developers feel friction early, because the pipeline formalizes judgment they already exercise implicitly, and the ceremony reads as overhead until the first review gate catches something they would have missed. The friction fades with the first caught regression; the relief does not.

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: /flow-next:setup

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

Why a script for Codex? Codex's plugin protocol only registers skills from plugin.json, not custom .toml agents or hooks. install-codex.sh merges the bundled agents and hooks into the active Codex home's config.toml (~/.codex by default). It is idempotent, so re-running it is safe. To install into another Codex home, run CODEX_HOME="$HOME/.codex-work" ./scripts/install-codex.sh once for that home (any path works; quote it if it contains spaces). Full platform matrix + community ports in docs/platforms.md.

Grok Build (xAI)? It picks up the Claude Code install automatically - skills, commands, and multi-agent flows verified. Details + caveats in docs/platforms.md.

The 5-command happy path

/flow-next:capture                   # 1. Synthesize co

…