Flow-Next

Agents generate. flow-next proves.

AI coding agents that ship like engineers - not slot machines. The workflow layer for AI coding agents: durable specs, re-anchored workers, adversarial reviews, receipts. Everything lives in your repo. Zero external dependencies. Uninstall: rm -rf .flow/.

Proof, not adjectives: a real recorded run - plan → cross-model plan review (catches a missing guard, fix, SHIP) → implement + tests → impl review SHIP → 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 just type the prompt or /flow-next:… command in your interactive session — same pipeline, same gates.}

A real /flow-next:plan result - dependency-ordered tasks, cross-model review iterated to SHIP, key decisions documented.

📖 Doc index · 👥 Teams guide · 💬 Discord

Agentic engineering compresses implementation from weeks to hours — and 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 didn't disappear — it moved upstream, to requirements, review, and verification. The spec has to carry the weight.

Flow-Next fixes the operating model, not just the prompt. 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. Between idea and merge it defines six named handover objects — each reviewable on its own, verified by a different model, and frozen at handover.

The artifact chain is not bureaucracy. It is the conversation that would otherwise be missing.

Flow-Next is an AI agent orchestration plugin: 28 agent-native skills covering the full lifecycle — idea → spec → tasks → review → ship → maintain — layered on a bundled pure-stdlib Python CLI (flowctl). The host agent is the intelligence; flowctl is the deterministic plumbing. No external services, no SaaS, no global config.

And one tenet about trust: everything lives in your repo under .flow/. Specs, tasks, memory, receipts — all of it is yours, in git, code-reviewable. Uninstall is rm -rf .flow/.

/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
# 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 all 22 agents + hooks into ~/.codex/config.toml. Idempotent — safe to re-run. 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.

/flow-next:capture                   # 1. Synthesize conversation → .flow/specs/<id>.md
/flow-next:plan <spec-id>            # 2. Break the spec into dependency-ordered tasks
/flow-next:work <spec-id>            # 3. Execute tasks in fresh-context worker subagents
/flow-next:make-pr <spec-id>         # 4. Render a cognitive-aid PR body (9 input streams)
/flow-next:resolve-pr <PR#>          # 5. Fetch review threads → triage → resolve

That's the inner loop. Branch in (/flow-next:prospect for ranked candidates, /flow-next:interview for structured discovery), branch out (/flow-next:pilot + /flow-next:land for the autonomous assembly line, /flow-next:ralph-init for hardened overnight runs, /flow-next:audit for memory garbage collection).

Plugin mode (Claude Code, the setup default for Claude-Code-only repos): nothing to do. Nothing is copied into your repo — flowctl rides the plugin's bin/ PATH injection, the agent guide is pulled live via flowctl usage, and the spec template resolves from the bundled copy. Plugin updates land silently; you never re-run setup for an update.

Copy mode (mixed-host repos — Codex/Cursor/Droid teammates, CI, plain terminals): update the plugin, then re-run /flow-next:setup in each project. In copy mode two things live as snapshot copies inside your repo's .flow/, not live links to the plugin: the bundled flowctl CLI (.flow/bin/) and .flow/usage.md (the in-repo agent guide). A plugin update does not touch them - re-running setup refreshes the CLI, usage.md, the model-routing scaffold, and the spec template. It is idempotent; nothing is lost. Plan detects a known copy/plugin version mismatch before planning; direct invocation of other skills does not run a version preflight. See Troubleshooting.

Setup asks the mode question once per repo (Claude Code only; other hosts are always copy mode) and stamps the choice; switching later is a consented setup re-run. Details: platforms.md.

The 5-command path is the opinionated default - rails for your first week, not a prohibition on anything else. Every stage is a composable primitive: skip stages, reorder them, chain them in one sentence, prompt into any of them - and whichever subset you run, the same execution, evidence, and review contracts hold. (Directly answers #28 and #91.)

You never have to type a slash command or a --flag. Every skill runs from plain language and every argument has a plain-language equivalent - "implement fn-12 on a new branch and review it with codex" is /flow-next:work fn-12 --branch=new --review=codex. The explicit forms below are the precise, copy-pasteable version. And the skills compose beyond the pipeline: research a competitor's pricing, then "capture a spec for it"; run a load test, then "spec the fixes the numbers point to" - the exploration is the input, the spec is the durable output.

Prototype first when the question needs it. Capture's input was never meant to be a requirements document - it can be a conversation, a half-formed briefing package, a business-language BRD, an eval result, or a working prototype. Some questions ("how should this look?", "how should this behave?", "does this state model survive the awkward cases?") cannot be settled in prose, so build the thing badly on purpose and then "capture a spec from this prototype - ignore the code quality, I want the intent and the requirements it demonstrates." What happens to the prototype code is a separate call made at plan time against your architecture and standards: throwaway evidence, keep-the-presentation-layer, or implementation seed.

Prototyping is the sharpest instance of a general move - let something real answer the question, then capture the answer - and the route should match the question: probe or load-test a performance complaint, reproduce a bug report as a failing test that becomes R1, run an eval for a model or prompt choice, bake off candidate approaches as one task each, research the outside world. Most of those run unattended, so the finding-out happens before anyone commits to a shape. See Prototype-Driven Specs and the cookbook.

Skip stages       Tiny fix? plan + work, nothing else: /flow-next:plan "rename the config key" → /flow-next:work fn-N
One-shot chain    "Plan fn-12, run plan-review until SHIP, work every task, then make-pr." One sentence, full pipeline.
Prompt into steps "/flow-next:work fn-12 - keep the UI tasks yourself; delegate the API plumbing to codex"
Reorder / re-run  Interview again after planning; /flow-next:sync re-aligns tasks after implementation drift.
Parallelize       /flow-next:plan reports execution waves. /flow-next:work inspects the ready frontier, dispatches
                  a safe subset in isolated workspaces when useful, joins it, then continues; otherwise it serializes.
Route models      flowctl config set review.backend codex · per-task review: pins · delegate:codex for implementation.

Skills are prompts executed by the host agent, not compiled code - if the variation you want isn't a parameter, describe it and the host builds the arrangement on the spot (orchestration guide). Use the smallest sufficient workflow. Full recipe catalog: flow-next.dev/cookbook.

flowchart LR
    Idea([💡 Idea]) --> P[/flow-next:prospect/]
    Idea --> C[/flow-next:capture/]
    P --> C
    P -.->|direct via promote| L[/flow-next:plan/]
    C --> L
    C --> I[/flow-next:interview/]
    I --> L
    L --> W[/flow-next:work/]
    W --> R[/flow-next:impl-review/]
    R -->|SHIP| Q[/flow-next:qa/]
    R -->|NEEDS_WORK| W
    Q -->|YES| Done([🚀 Ship])
    Q -->|NO| W

    Done -.maintenance.-> A[/flow-next:audit/]
    A -.-> M[(.flow/memory/)]

/flow-next:qa is an opt-in live-app QA stage (after work, before make-pr) — it drives the deployed app like a real user and only runs when there's a live deploy + a driver; with neither it surfaces the limitation rather than blocking. It augments, never replaces CI/staging/manual QA: the cheap first live pass that catches obvious runtime breakage before a human opens the PR. Run it by hand, or wire it into the autonomous loop as the optional pipeline.qa pilot stage (flowctl config set pipeline.qa on, default off) — plan → plan-review → work → qa → make-pr.

The loop is spec-driven. Each step below maps to one skill; click through to flow-next.dev for the full page.

/flow-next:capture                    # from a conversation
/flow-next:prospect <focus-hint>      # from a focus hint (concept, path, constraint, volume)

/flow-next:interview <spec-id>

/flow-next:plan <spec-id>             # or <free-form text>

/flow-next:work <spec-id>             # or <task-id>

5. Open the PR with a cognitive-aid body

Don't ask a human to skim a 10K-line diff. /flow-next:make-pr renders a PR body from nine flow-next input streams (spec R-IDs, per-task evidence, memory hits, glossary changes, strategy alignment, deferred review findings, the diff itself) — with an R-ID coverage table mapping every acceptance criterion to its satisfying task and evidence commit, and a "where to look" list that tells the reviewer which lines matter. A real one, from PR #215:

/flow-next:make-pr <spec-id>          # auto-detects from current branch

With HTML artifact mode on (flowctl config set artifacts.html.enabled true), make-pr also commits a self-contained pr.html review instrument — diff-derived churn map, R-ID → evidence table with flagged mismatches, where-to-look checklist — and links it from the PR body. Same switch gives capture/plan a spec visualizer. Opt-in; see docs/html-artifacts.md.

→ flow-next.dev/skills/make-pr

/flow-next:resolve-pr <PR#>

Three loops, one quality bar. Multi-model review at every handover, don't-thrash reflexes (two-strike unready, auto-block, bounded CI fix budgets), evidence over narration — invariant across all three. That's the differentiator from "ralph-wiggum"-style loops that run open-loop without gates.

The default path is the pilot + land pipeline — in-session, host-driven, zero scaffold:

flowctl spec ready fn-12          # bless work (or move its issue on the tracker board)
/loop 10m /flow-next:pilot        # build loop: ready spec → plan → reviews → work → draft PR
/loop 30m /flow-next:land         # ship loop: draft PR → CI green → reviews converged → merged → released

Run both concurrently — two instances, separate clones — and you have the full assembly line: board → pilot → draft PR → land → released. The ready flag (or your tracker's board state) is the consent boundary: humans bless specs, loops drain them. 📖 Going autonomous

Ralph is the hardened harness for fully planned specs (it never plans): an external shell loop drives a fresh session per iteration — failed attempts die with the session instead of polluting the next one — with hook-enforced guardrails and receipts on disk. Reach for it when a run outlasts a session or prose guardrails aren't enough.

/flow-next:ralph-init           # One-time setup
scripts/ralph/ralph.sh          # Run from terminal

Ralph mode at night, PRs in the morning. The TUI tracks task progress, streaming logs, and run state.

📖 Ralph deep dive · Ralph TUI (bun add -g @gmickel/flow-next-tui)

"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, said while shipping a correct kernel patch

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

Featured in awesome-claude-code-workflows for plan-first workflows, Ralph autonomous mode, and receipt-based gating (#96).

flow-next's ways of working are coached and run in enterprise environments worldwide - from CAD and construction software to proptech and education, from modern monorepos and hundred-repo microservice estates to 30-year-old legacy stacks, on GitHub Enterprise, GitLab, and Jira. Discovery interviews of 2-3 hours produce 8-11 structured, buildable specs; the edge cases surface in the interview, not the sprint.

Receipts, evidence JSON, and review gates are the audit trail enterprise adoption asks for - approval checkpoints and traceability are built in, not bolted on.

For teams: six named handover objects, Spec-as-PR (review the 50-line spec before the 500-line diff exists), and tracker projection to Linear / GitHub / GitLab / Jira. → docs/teams.md · flow-next.dev

Scope honesty, because the architecture depends on it:

• Not a hosted dashboard or SaaS tier. Everything is in the repo; a hosted layer would break the uninstall promise.
• Not a Jira/Linear replacement for human-only teams. Flow-Next is for agentic-engineering teams. If your team lives in a tracker, /flow-next:tracker-sync projects specs to it — projection, not coordination: the spec stays the source of truth; the tracker never drives flow state or spawns agents. (Contrast OpenAI Symphony, where the tracker is the control plane — Flow-Next is "Symphony, but with real specs, re-anchoring, and receipts.")
• Not split-file specs. One durable spec document evolving through layers — vs. Kiro-style requirements.md / design.md / tasks.md fragmentation.
• Not a replacement for human judgment. Humans own product decisions, risk tolerance, merge decisions, and production responsibility. Flow-Next makes those decisions easier to verify because the evidence is structured.
• Not waterfall. Waterfall means irreversible phases, a plan frozen at minimum knowledge, and handovers that discard what the next phase learns. Flow-Next has none of them: stages are re-enterable (re-interview after planning exposes a hole, re-plan after a task proves the approach wrong), the spec is captured at the moment of most knowledge because exploration comes first, and evidence is written back into the spec as work proceeds. It does ask for more thought earlier than a loose ticket does; it does not ask for more commitment earlier. The spec is a ratchet, not a gate. Full argument: Prototype-Driven Specs.

Phrase-triggered skills (no slash command — just ask): flow-next-deps ("what's blocking what?" — dependency graph + execution order), flow-next-drive (drive a running app like a real user; powers /flow-next:qa), flow-next-export-context (export RepoPrompt context for external-LLM review), flow-next-rp-explorer (token-efficient codebase exploration via RepoPrompt), flow-next-worktree-kit (worktree create/list/switch/cleanup + .env copying), and base flow-next ("show me my tasks", "what's ready?").

Full catalog of all 28 skills with triggers: docs/skills.md. Full CLI reference (every flag, every default): docs/flowctl.md. Steering all of it — model routing, review backends, delegation, loop chaining: docs/orchestration.md.

Flow-Next is a methodology, not just a tool. The teams guide maps the AI-native SDLC onto concrete commands: the six handover objects, Spec-as-PR (review the 50-line spec before the 500-line implementation exists), parallel work from one spec, the symmetric interview (PO and tech lead run the same skill on the same file), and a week-1 → month-1 → quarter-1 adoption ladder.

Teams that live in Linear, GitHub Issues, GitLab, or Jira keep their board: the tracker bridge projects every spec to an issue, two-way. On Linear, make-pr output is additionally Linear Diffs-ready — review the PR inside the issue. → docs/teams.md · docs/tracker-sync.md

Rolling it out to everyone? On Claude Code you can skip the per-developer install: deploy the marketplace + plugin org-wide via a managed-settings.json (MDM/GPO — extraKnownMarketplaces + enabledPlugins), or commit a .claude/settings.json to a repo for prompt-on-trust install. Each repo still needs /flow-next:setup. → Install: team / org-wide deployment

The repo holds the offline-resilient reference. flow-next.dev holds the narrative, browseable guide. Pick by audience.

Doc index with one-line descriptions: plugins/flow-next/docs/README.md.

• Python 3.11+ (or the py launcher on Windows) — 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.

Detailed install + cross-platform patterns in docs/platforms.md.

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. Re-run /flow-next:setup for current scaffolding, then follow the manual three-step pre-1.0 layout port in troubleshooting.

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.

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

MIT — see LICENSE.