For agents

This page is for an agent that uses Flow-Next on a person’s project: a coding agent in a session, or a bot that starts sessions and reads their output. If you are changing Flow-Next itself, the repository’s AGENTS.md and CLAUDE.md are your instructions instead. They are contributor rules and do not apply to a project that only uses Flow-Next.

Set up once per project

Install the plugin for the host you run in (Install). Installation is a terminal step; every workflow command below goes into the agent conversation.
Run /flow-next:setup in the project. It writes the instruction snippet and asks once which reviewer to use.

Use the host’s spelling for every command: Codex $flow-next-flow, OpenCode /flow-next-flow, everywhere else /flow-next:flow.

One entry point

Hand everything to Flow, verbatim:

/flow-next:flow <what the person gave you>

A sentence of intent, a pasted error or traceback, a ticket URL or key, a spec id like fn-12, a branch, a profile or crash dump, a question about the code, or a diff with “is this safe to merge?” all go in as they are. Flow reads the starting point, picks one of about thirty routes, runs it, and stops at the next decision that belongs to the person.

Do not pre-route. Calling plan, work, capture or review yourself skips the checks Flow makes before it picks a stage, such as whether a ready spec needs a plan at all. Call a stage directly only when the person names it.
Preview without running anything: /flow-next:flow --explain <the same input> prints the route and why, and writes nothing.
No input: /flow-next:flow with no argument reads the repository’s state and recommends what to do next.

The routes are listed on How Flow chooses. You do not need them to operate Flow; they help you predict and explain what it did.

Attended runs: relay the stop

An attended run ends with a short report:

Flow stopped at: <the decision that is the person's, or "PR exists">
Route taken: <hop> -> <hop> -> ...
stage: <name> - ran | skipped(<kind>: <reason>) | failed(<reason>)
Next: <the prompt or command to run next, or the decision to make>

Relay Flow stopped at and Next to your person. Product and authority decisions, such as what to build or whether to merge, are theirs; do not answer them on the person’s behalf. A pick among options a stage produced is asked inline, one per hop, and the run carries on after the answer.

Unattended runs: read the verdict line

--auto runs the same routes with nobody watching. It never asks, it writes every decision it made on the person’s behalf into the pull request, and its last line is always one verdict:

PILOT_VERDICT=<verdict> spec=<id> stage=<stage> reason="<one line>"

Verdict	Meaning	What your driver does
`ADVANCED`	The spec moved forward. Without `--tick` the run continued hop by hop and usually ends at an open PR (`stage=work+qa+make-pr`)	Under `--tick`, run again; otherwise report the PR. `ADVANCED` alone never means merged
`NO_WORK`	No ready spec with satisfied dependencies, or the selected one is already merged	Stop
`DEFERRED_TO_LAND`	Every remaining finished spec has an open PR	Hand that PR to `/flow-next:land` if the person authorized the merge; otherwise report it
`BLOCKED`	The stage ran but nothing moved; after a second strike the spec is un-readied	Report the reason; the person re-readies the spec or clears the strike
`NEEDS_HUMAN`	Something only a person can settle: a question, a dirty tree, a blocked task, a failed probe	Stop and show the reason; do not retry around it
`GOAL_MET`	Goal mode only: every criterion has recorded evidence	Stop and report

Backlog mode adds ASKED; the full grammar is on flow —auto.

A bot must use --auto, not plain flow. Attended /flow-next:flow refuses under any autonomy marker (FLOW_AUTONOMOUS, AUTONOMOUS=1, a mode:autonomous token) with NEEDS_HUMAN: /flow-next:flow is attended - run /flow-next:flow --auto for unattended runs. If nobody will answer questions, run --auto.

The forms:

Invocation	What it does
`/flow-next:flow --auto`	Picks one ready spec and drives it to a pull request
`/flow-next:flow --auto fn-12`	The same, for that spec only
`... --tick`	One hop, then the verdict; for hosts without long sessions, run it on a loop
`... --until=merge`	Also lands the PR; this is the person’s merge authorization for this run
`/flow-next:flow --goal <spec or source>`	Works toward an outcome bigger than one spec, child spec by child spec

Rules that keep a run safe

Only ready specs run unattended. The ready flag is the person’s consent to build. Do not mark a spec ready yourself unless the person told you to.
Merge consent is current and explicit. It comes from the person in this session or from --until=merge on this run, never from an old transcript, a receipt or an environment variable.
Start from a clean tree. Uncommitted changes outside .flow/ end an unattended run with NEEDS_HUMAN before it touches anything.
Judge an idle agent by what it wrote, not by its silence. Check its commits, receipts and task status. Sending a resume message to a slow agent restarts it and leaves two runs.
Never nest drivers. Attended flow and flow --auto are two drivers for the same pipeline. Start one per item from your loop; never start one from inside the other. Flow invokes land itself only with merge authorization.
State lives in the repository. Specs, tasks, receipts and evidence are under .flow/, read and written through the bundled flowctl. A crashed run resumes from disk on the next invocation; nothing is recovered from a transcript.

To run on a flowctl you built yourself, set FLOW_NEXT_FLOWCTL (Environment overrides).