# Introduction

Source: https://flow-next.dev/introduction/

Flow-Next runs inside your coding agent. Tell Flow what you have, read the route it picks, and get a reviewed pull request with evidence, alone or with a team.

Flow-Next is a workflow plugin that runs inside your coding agent. **Agents generate. Flow-Next proves.** The checks establish what changed, which acceptance criteria the change covers, what an independent reviewer found, and which tests ran; whether the change is the right product decision stays with you. You describe what you have (an idea, a ticket, a bug report, a question about the code, a ready spec) and Flow picks the smallest sufficient route, runs it, and stops at the decision that is yours. The spec and its state live in your repository, so a new session or a different agent reads the same record.

Flow-Next is fast on the actual work: across more than 170 full end-to-end runs, the change came back in about the time plain Claude Code, or your harness, takes, often less. The result is already better than the plain agent’s before any review. The optional stages, review by another model and live QA in the running app, widen the gap to up to 25% better outcomes, especially on large and long-horizon work, and Flow adds a stage only where the risk calls for it.

## What you say, what you get

Type the request in ordinary language. On a host that needs the command, prefix it with `/flow-next:flow` (`$flow-next-flow` on Codex, `/flow-next-flow` on OpenCode).

| You say                                         | What Flow does, and what appears                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ”Lock down what we just discussed and build it” | Writes a spec from the conversation and shows you its summary, implements it on the route it picked, runs the configured review inside work, and commits the change on a local branch. Say “open the PR” and it opens one. On disk: the spec under `.flow/specs/`, task evidence, a review receipt, the branch.                                                                                                                                                   |
| ”Work ticket WOR-17”                            | Reads the issue through the access your session already has and routes on its content and current state: a clear request is captured as a spec and built, a defect report is checked for existing fixes and reproduced first, a question is answered, and an issue already linked to a spec resumes from that spec. On disk: whatever the route produces, as in the rows above and below.                                                                         |
| ”This fails: `<pasted stack trace>`”            | Checks for an existing fix, reproduces the failure, confirms its cause, and bisects to the introducing commit when a known-good revision exists. The failing reproduction becomes the requirement; the fix must make it fail on the base and pass on the head. Then it reviews the fix and commits it on a local branch, ready for a PR when you ask. On disk: the minimal spec, the failing-then-passing test, the record of each step, the receipt, the branch. |
| ”Why does the parser reject empty headers?”     | Answers with citations from git history, the PRs behind the commits, and the project’s bug and decision memory, each finding tiered `direct`, `supported`, `inferred`, or `unknown`. Writes nothing under `.flow/` and opens no PR.                                                                                                                                                                                                                               |
| ”Work fn-12”                                    | Reads the spec’s state, records the route on the spec, runs work with the configured review, and stops with the change committed on a local branch. On disk: the recorded route, task evidence, the receipt, the branch.                                                                                                                                                                                                                                          |

When you are at the keyboard, change-producing routes on a spec end with the change committed on a local branch and one line: say “open the PR” when you want it. The pull request then opens ready for review unless something is left open for a human, and the merge is yours. A small fix without a spec is changed directly and handed back; ask for a PR when you want one. `flow --auto` opens the pull request itself. The investigation route ends at the cited answer.

## Inspect what supports the result

* **Independent review by risk.** Review runs through the `review.backend` you set at setup: three reviewers for a risky change, one otherwise, and a small output, wording or display fix is skipped with the reason recorded. The verdict lands as a receipt on disk. `review=none` is a recorded skip, never a verdict.
* **Test evidence.** The work and review contracts require commits and test commands before a task closes; `flowctl done` records what the worker supplies, and the reviewer reads that record. Worker narration never supplies a missing verdict.
* **Visible skips.** Every stage Flow reaches prints one line: `ran`, `skipped(<reason>)`, or `failed(<reason>)`. Live QA defaults to `off`; `auto` runs it only when the acceptance criteria describe a UI on a surface the QA driver can reach and start.

[Follow one real change through review](https://flow-next.dev/guides/worked-example/) to see a finding become a correction commit and reach the PR.

## You keep the controls

Flow asks a pick inline, at most one question per hop, when a stage produced options. It stops at a run-ending decision: merge, a review verdict that needs a person, a product question no stage framed as options. `flow --explain <what you have>` prints the route, its signal, and the safe skip, and writes nothing.

Every stage Flow runs is a skill you can invoke by name: capture, refine (interview), plan, plan-review, work, qa, make-pr, resolve-pr. For a ready spec, direct execution is the default; planning into tasks needs a positive signal. [How Flow chooses](https://flow-next.dev/choosing-your-route/) lists the signals and shows how to read and override a route.

## Choose how much to attend

By default, attended Flow ends with the change committed on a local branch and opens the pull request when you ask; it does not ask about landing a pull request it just opened. With `--until=merge`, it invokes land for the selected item. Plain attended flow on an existing PR asks once before landing unless that item is already authorized. [`/flow-next:flow --auto`](https://flow-next.dev/autonomy/pilot/) runs the same conductor unattended. One invocation carries a ready spec to a PR, hop after hop, without asking: it decides from evidence, writes every decision into the PR, and reports `NEEDS_HUMAN` only for a call a person has to make; [land](https://flow-next.dev/autonomy/land/) merges the result under your CI and review rules. [Flow and the road ahead](https://flow-next.dev/understand/flow-and-the-road-ahead/) records how the one conductor came about and what comes next.

## Run across your configured harnesses

First-class on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, and OpenCode. The entry is the same word on every host in that host’s spelling: `/flow-next:flow`, `$flow-next-flow`, `/flow-next-flow`. [Install](https://flow-next.dev/install/) carries the prerequisites (Python 3.11+, `jq` and `gh`, a reachable reviewer) and the setup invocation per host; the [platform matrix](https://flow-next.dev/integrations/platforms/) carries the differences in model routing and delivery.

## Alone or with a team

Alone, start with one change. Tell Flow what you have, read the spec summary it shows you, then say “open the PR” and inspect it. Add `flow --auto` and land when you want the same gates to keep working between your visits.

With a team, product reviews intent and acceptance criteria in the spec, engineering adds constraints and reviews the approach, agents implement, and the reviewer receives a PR that maps changes to requirements and evidence. Keep your existing board; the tracker bridge keeps it in step with the spec. [For teams](https://flow-next.dev/guides/for-teams/) shows the handovers and a first-week trial.

## Start one change

1. [Install for your coding agent](https://flow-next.dev/install/).
2. Run setup in the repository you want to change.
3. [Tell Flow one change and read what it decided](https://flow-next.dev/first-30-minutes/).

The tutorial includes a two-file Python example if you have no small change ready. Keep your normal Git and CI workflow. [For teams](https://flow-next.dev/guides/for-teams/) covers adoption.