# For agents Source: https://flow-next.dev/for-agents/ Read this first if you are an agent or bot operating Flow-Next on someone's project. One entry point, how to read what it hands back, the unattended verdict line, and the few rules that keep a run safe. 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 1. Install the plugin for the host you run in ([Install](https://flow-next.dev/install/)). Installation is a terminal step; every workflow command below goes into the agent conversation. 2. 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: ```text /flow-next:flow ``` 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 ` 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](https://flow-next.dev/choosing-your-route/). 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: ```text Flow stopped at: Route taken: -> -> ... stage: - ran | skipped(: ) | failed() Next: ``` 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: ```text PILOT_VERDICT= spec= stage= reason="" ``` | 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](https://flow-next.dev/autonomy/pilot/#the-verdict-grammar). **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 ` | 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](https://flow-next.dev/flowctl/configuration/#environment-overrides)). ## Read next * [Going autonomous](https://flow-next.dev/autonomy/going-autonomous/): the autonomy dial and the consent boundary. * [flow —auto](https://flow-next.dev/autonomy/pilot/): the verdict grammar, strikes and backlog mode in full. * [Land](https://flow-next.dev/autonomy/land/): taking one named PR to merge. * [Goal mode](https://flow-next.dev/autonomy/goal-mode/): outcomes larger than one spec. * [The flow skill](https://flow-next.dev/skills/flow/): the conductor and its routing reference.