# Flow-Next

> Agents generate. flow-next proves. Flow-Next is a workflow plugin inside your coding agent. It turns intent into specs, implementation, review, and pull requests with evidence.

Start with the established workflow, then shape it in plain language. Choose stages, models, and merge conditions per change or in standing project policy. Specs, decisions, and task state live in your repository.

First-class on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, and OpenCode. Flow-Next is MIT-licensed; you supply agent access and project tools. Python 3.11+ runs the bundled CLI; review and PR plumbing use jq and gh. No Flow-Next account or hosted service is required.

Workflow invocations belong in the agent conversation. Codex uses $flow-next-<name>, OpenCode uses /flow-next-<name>, and Claude Code, Droid, Grok Build, and Cursor accept /flow-next:<name>. Cursor also accepts the hyphen form. See Install for the terminal commands.

## Start

- [Introduction](https://flow-next.dev/introduction.md): What Flow-Next installs, how your coding agent runs and adapts the workflow, and where to start with one change or a team.
- [Install](https://flow-next.dev/install.md): Install Flow-Next on Claude Code, OpenAI Codex, Factory Droid, xAI Grok Build, Cursor, and OpenCode - plus org-wide team deployment via managed settings.
- [Your First 30 Minutes](https://flow-next.dev/first-30-minutes.md): Try Flow-Next on a two-file Python CLI. Capture one change, inspect the spec, run implementation and review, then open a PR with evidence.
- [One change through review](https://flow-next.dev/guides/worked-example.md): Follow a real Flow-Next change from requirement R8 through a forced-color Git parsing defect, its fix, test evidence, and the final PR.
- [Choosing your route](https://flow-next.dev/choosing-your-route.md): Which stages this change needs - the risk-and-unknowns selector, the situation-to-command shortcuts, six worked routes, and the cases where Flow-Next is the wrong tool.

## Understand

- [Understand](https://flow-next.dev/understand.md): Why the pipeline is shaped this way - the problem it answers, how work gets proven, what each layer costs, and the vocabulary the rest of the docs use.
- [Why Flow-Next](https://flow-next.dev/understand/why-flow-next.md): Why faster code generation makes requirements, review, and verification the next constraint, and how Flow-Next carries that work through a change.
- [The Pipeline](https://flow-next.dev/understand/pipeline.md): The canonical end-to-end walk - rough intent to merged release, every handover, every gate, and where the autonomy loops and render lenses attach.
- [How work gets proven](https://flow-next.dev/understand/how-work-gets-proven.md): One system with one bias, verification. In-loop checks against numbered acceptance criteria, review receipts, evidence JSON, live-app QA verdicts, and gate receipts keyed to exact commits.
- [Compose the pipeline](https://flow-next.dev/understand/compose-the-pipeline.md): Skip, reorder, prompt into, chain, parallelize, route models per step. Every arrangement keeps the same execution, evidence, and review contracts.
- [Explore first, then capture](https://flow-next.dev/understand/explore-first.md): The spec is written at the moment of most knowledge, after exploration rather than before it. What that buys you, what the prompt-look-fix loop costs by comparison, and how it answers the waterfall objection.
- [What each layer costs](https://flow-next.dev/understand/what-each-layer-costs.md): What agent work each optional Flow-Next layer adds, when to use it, and how to choose review, QA, tracker sync, and autonomous loops.
- [How it compounds](https://flow-next.dev/understand/how-it-compounds.md): How review corrections, decisions, and project vocabulary become repository knowledge that the next task, teammate, or coding agent can read.
- [Architecture & harnesses](https://flow-next.dev/understand/architecture.md): How Flow-Next runs inside your coding agent and stores specs, tasks, and evidence in your repository, with a bundled CLI for state changes.
- [Concepts](https://flow-next.dev/understand/concepts.md): The vocabulary behind Flow-Next - spec, task, R-ID, handover object, re-anchoring, receipt, harness.

## Guides

- [Guides](https://flow-next.dev/guides.md): How to do the work - write specs, shape task graphs, run reviews, route models, drive the app, and work as a team.
- [Writing specs](https://flow-next.dev/guides/writing-specs.md): What belongs in a spec, how the ready flag gates it, how capture and interview divide the work, and the patterns that keep a team spec useful.
- [From prototype to spec](https://flow-next.dev/guides/prototype-to-spec.md): Let something real answer the question, then capture the answer - the capture inputs, the fidelity rule, the evidence-first route family, and what the plan stage does with prototype code.
- [Customizing the spec scaffold](https://flow-next.dev/guides/spec-scaffold.md): The template cascade, house-style overrides, the four headings flowctl parses, scope-owner markers, and what setup copies.
- [Tasks, dependencies & parallelism](https://flow-next.dev/guides/tasks.md): How a spec becomes an execution graph, what makes a good task, how dependencies gate work, and when parallel workers are safe.
- [Review workflow](https://flow-next.dev/guides/review-workflow.md): The gates from plan to PR, what each one checks, and the single symptom-to-fix table for when one of them finds something.
- [Render lenses](https://flow-next.dev/guides/render-lenses.md): The opt-in HTML artifact mode - the spec lens for business and plan review, the PR lens for diff review, activation, and the annotate loop.
- [Orchestration - pipeline routing & model routing](https://flow-next.dev/guides/model-routing.md): flow-next routes on two axes - the pipeline shape per item and the model per job - and prints a reason for each decision. Six shape deciders, four model tiers, a routing block in your own instruction file, a multi-day unattended field case still running, and a five-rung setup ladder.
- [Discovery before capture](https://flow-next.dev/guides/discovery.md): How chart turns one oversized, unclear idea into a briefable set of decisions - the destination rule, the evidence-first decision types, the grounding snapshot, and the handoff to capture.
- [Live-app QA & driving UIs](https://flow-next.dev/guides/live-qa.md): The live pass that drives the running app against the spec, and the driver ladder underneath it - surface detection, the web rungs, the native rung, and graceful degradation.
- [For teams](https://flow-next.dev/guides/for-teams.md): Try Flow-Next on one team change. Product reviews intent, engineering shapes the approach, and reviewers follow the PR evidence. Keep your existing board.
- [Cookbook](https://flow-next.dev/guides/cookbook.md): Verified dynamic-usage recipes for the whole pipeline - skip stages, prompt into them, chain them, route models, parallelize, and dial autonomy. Every recipe is a real scenario, the exact invocation, and why the gates still hold.

## Autonomy

- [Going Autonomous](https://flow-next.dev/autonomy/going-autonomous.md): The three flow-next loops - pilot builds, land ships, Ralph hardens - the consent boundary that gates all of them, and the safety model behind hands-free shipping.
- [Pilot - the build loop](https://flow-next.dev/autonomy/pilot.md): How the single-tick build conductor works - the consent boundary, what one tick does, the don't-thrash guard, readiness as the control plane, and backlog mode.
- [Land - the ship loop](https://flow-next.dev/autonomy/land.md): The cadence-driven babysitter that takes the build loop's draft PRs through CI, review convergence, gated merge, spec close, and release.
- [Driving a loop](https://flow-next.dev/autonomy/driving-a-loop.md): The /goal and /loop snippets for each host, why the verdict grammar is the driver contract, and the wrapper pattern that keeps a bridged CLI from failing silently at 3am.
- [Unattended operation](https://flow-next.dev/autonomy/unattended-operation.md): The queue policy above the loops - bounded intake, worktree isolation, overlap control, hourly wakes, tracker integration, release proof, and headless runners.
- [Ralph (deprecated)](https://flow-next.dev/autonomy/ralph.md): The repo-local shell harness - a fresh agent session per iteration, hook-enforced rails, review receipts on disk. Still supported, no longer the recommended path.

## Integrations

- [Tracker sync](https://flow-next.dev/integrations/tracker-sync.md): Project a spec onto a Linear, GitHub, GitLab, or Jira issue and reconcile body, status, and comments two-way. Positioning, the discovery ceremony, and the three ways in.
- [Tracker operations](https://flow-next.dev/integrations/tracker-operations.md): The lifecycle touchpoints, the who-wins ladder, readiness and dependency projection, the deterministic transport contract with its error classes, and Jira's specifics.
- [Platform matrix](https://flow-next.dev/integrations/platforms.md): What each host harness runs, how it is installed, which slash form it uses, and the caveats that differ per platform.

## Reference

- [Reference](https://flow-next.dev/reference.md): Look-up material - every skill and subagent, the flowctl CLI, configuration, review backends, receipts, the spec schema, standing criteria, the glossary, troubleshooting, and the FAQ.
- [All Skills](https://flow-next.dev/skills.md): Every flow-next skill in one grid, grouped by pipeline stage - shape, plan, build, ship, autonomy, teams, maintenance, workspace.
- [Strategy](https://flow-next.dev/skills/strategy.md): Create and maintain STRATEGY.md - the product anchor downstream skills read for grounding.
- [Guide](https://flow-next.dev/skills/guide.md): Prompt-first router that recommends the smallest sufficient flow-next workflow for your starting state.
- [Prospect](https://flow-next.dev/skills/prospect.md): Generate ranked candidate ideas grounded in the repo, upstream of /flow-next:plan.
- [Chart](https://flow-next.dev/skills/chart.md): Decision-map discovery for one oversized or unclear idea before capture - resolve one decision at a time until the effort is briefable.
- [Capture](https://flow-next.dev/skills/capture.md): Synthesize a conversation into a flow-next spec with source-tagged R-IDs and mandatory read-back.
- [Interview](https://flow-next.dev/skills/interview.md): Refine a spec via symmetric Q&A - business and technical passes, append-only R-IDs.
- [Plan](https://flow-next.dev/skills/plan.md): Research scouts in parallel; structured plan with R-ID coverage; tasks sized for one work-loop iteration.
- [Work](https://flow-next.dev/skills/work.md): Execute a flow-next spec - rolling-frontier scheduling by default, isolated workers, conductor-owned review, evidence-gated completion.
- [Make PR](https://flow-next.dev/skills/make-pr.md): Render a cognitive-aid PR body from spec state - R-ID coverage table, critical changes, decision context.
- [Resolve PR](https://flow-next.dev/skills/resolve-pr.md): Resolve PR review feedback - fetch threads, triage, dispatch resolver agents, reply + resolve via GraphQL.
- [Pilot](https://flow-next.dev/skills/pilot.md): Single-tick autonomous build-loop conductor - one ready spec, one pipeline stage per tick, driven by your host's /loop or /goal.
- [Plan Review](https://flow-next.dev/skills/plan-review.md): Carmack-level adversarial review of a spec via RepoPrompt, Codex, Copilot, or Cursor.
- [Impl Review](https://flow-next.dev/skills/impl-review.md): Carmack-level review of implementation changes on the current branch.
- [Spec Completion Review](https://flow-next.dev/skills/spec-completion-review.md): Verify the combined implementation of all tasks in a spec satisfies the spec requirements.
- [QA](https://flow-next.dev/skills/qa.md): Live-app real-user QA pass that drives the running app and derives its test scenarios from the spec.
- [Visual](https://flow-next.dev/skills/visual.md): Restate a spec, task, diff, or the current topic as a compact markdown digest - the light register between raw markdown and the HTML render lenses.
- [Prose](https://flow-next.dev/skills/prose.md): Apply the shipped artifact prose contract to a substantial reply or draft - the same ten rules the pipeline already applies to PR bodies, specs, tracker comments, and changelogs.
- [Setup](https://flow-next.dev/skills/setup.md): Optional local install of flowctl plus CLAUDE.md and AGENTS.md instructions.
- [Prime](https://flow-next.dev/skills/prime.md): Opinionated agent-readiness assessment - classifies your project, judges substance over existence, and leads with a verdict + ranked next-actions.
- [Audit](https://flow-next.dev/skills/audit.md): Review .flow/memory/ against the current codebase - Keep / Update / Consolidate / Replace / Delete / Harden per entry.
- [Features](https://flow-next.dev/skills/features.md): Seed and maintain the committed user-POV feature map at .flow/features/ - how a user reaches each feature, how an agent drives it, and which traps waste a run.
- [Map](https://flow-next.dev/skills/map.md): Wrap clawpatch map for a semantic feature index of the repo - opt-in convenience consumed by scouts.
- [Memory Migrate](https://flow-next.dev/skills/memory-migrate.md): Lift legacy flat memory files into the categorized YAML schema.
- [Sync](https://flow-next.dev/skills/sync.md): Manually trigger plan-sync to update downstream task specs after implementation drift.
- [Deps](https://flow-next.dev/skills/deps.md): Show spec dependency graph, execution order, and parallelizable phases.
- [Worktree Kit](https://flow-next.dev/skills/worktree-kit.md): Manage git worktrees for parallel feature work, isolated review, and clean workspaces.
- [Export Context](https://flow-next.dev/skills/export-context.md): Export a review prompt for external LLMs (ChatGPT Pro, Claude web, Gemini).
- [Tasks & Inventory](https://flow-next.dev/skills/flow-next.md): Conversational access to specs and tasks in .flow/ - the meta-skill behind 'show me my tasks'.
- [Flow-Next Drive](https://flow-next.dev/skills/flow-next-drive.md): Surface-aware UI automation - detects the surface (web app, Chromium-backed desktop app, or true-native app) and picks the best available driver, degrading gracefully.
- [Subagents](https://flow-next.dev/subagents/overview.md): Every flow-next command is backed by a fleet of specialized subagents the skills dispatch for you - scouts that investigate, workers that build, auditors that check.
- [Planning Scouts](https://flow-next.dev/subagents/planning-scouts.md): The eight read-only scouts /flow-next:plan dispatches to research the codebase, the ecosystem, and the existing plan graph before a single task is written.
- [Readiness Scouts](https://flow-next.dev/subagents/readiness-scouts.md): The eight read-only scouts /flow-next:prime dispatches in parallel to assess whether a repository is ready for agents and production - one scout per pillar.
- [Execution & Review](https://flow-next.dev/subagents/execution.md): The four subagents that actually change code and guard quality - worker, plan-sync, quality-auditor, and pr-comment-resolver - spawned by /flow-next:work, /flow-next:sync, and /flow-next:resolve-pr.
- [CLI Reference](https://flow-next.dev/flowctl/cli-reference.md): The deterministic Flow-Next CLI.
- [Configuration](https://flow-next.dev/flowctl/configuration.md): The complete .flow/config.json reference - every key, generated from the published schema.
- [Review backends](https://flow-next.dev/reference/review-backends.md): The backend ladder, the backend:model:effort grammar, precedence, the host sentinel, and what the reviewer actually receives.
- [Receipts](https://flow-next.dev/reference/receipts.md): Proof-of-work artifacts, including the portable structured-findings contract.
- [Spec Schema](https://flow-next.dev/reference/spec-schema.md): Canonical Flow-Next spec sections.
- [Standing Criteria](https://flow-next.dev/reference/standing-criteria.md): Project-wide acceptance criteria in .flow/criteria.md, judged by spec completion review and recorded in the review receipt.
- [Glossary](https://flow-next.dev/reference/glossary.md): The canonical Flow-Next vocabulary - specs, tasks, R-IDs, handover objects, receipts, Ralph, pilot, land, tracker projection, and the rest of the terms the docs lean on.
- [Troubleshooting](https://flow-next.dev/reference/troubleshooting.md): Common recovery patterns - post-update drift, stuck tasks, Ralph debugging, review-loop caps, model downgrades, Windows Python discovery, and clean uninstall.
- [FAQ](https://flow-next.dev/reference/faq.md): Answers about Flow-Next adoption, spec size, preserved history, agent usage, prerequisites, and workflow controls.

## Project

- [Evidence & evals](https://flow-next.dev/project/evidence.md): The measured decay Flow-Next is built against, the boundary between what the benchmark shows and what we claim, and the evals we ran on ourselves - including the two results that killed a feature.
- [Changelog](https://flow-next.dev/releases/changelog.md): Human-readable release highlights for Flow-Next.
- [Compatibility & migration](https://flow-next.dev/releases/compatibility.md): What changed across major versions, what an upgrade requires, and the removals that need a hand-port.

## Complete documentation

- [Full documentation](https://flow-next.dev/llms-full.txt): All published documentation in one file. Use individual page links above for focused retrieval.

## Source

- [Source repository](https://github.com/gmickel/flow-next): plugin source, releases, issues, and offline documentation.