# Going Autonomous Source: https://flow-next.dev/autonomy/going-autonomous/ The autonomy dial from Flow at the keyboard to flow --auto and land unattended, the two loops, the consent boundary that gates all of them, and the safety model behind hands-free shipping. Autonomy is one dial with the same gates at every rung. At the keyboard, [`/flow-next:flow`](https://flow-next.dev/skills/flow/) reads what you have, routes it, runs the stages, and stops at the decision that is yours; a run from intent ends with the change committed on a local branch, and the pull request opens when you ask. Away from the keyboard, [`flow --auto`](https://flow-next.dev/autonomy/pilot/) builds and [land](https://flow-next.dev/autonomy/land/) ships. You concentrate judgment in the spec and the [readiness gate](https://flow-next.dev/guides/writing-specs/#the-ready-flag), and the unattended driver executes the mechanical middle. The same review gates fire, the same receipts get written, and the run stops waiting for you between stages. ## The dial | Rung | Driver | Who decides the next step | Where it stops | | ----------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | At the keyboard | `/flow-next:flow ` | Flow, from the shared routing reference, with you settling product decisions and answering at most one pick per hop | The change committed on a local branch by default, with the PR opened when you say “open the PR”; an existing PR offers landing and asks once unless already authorized | | Unattended build | `/flow-next:flow --auto` | `flow --auto`, from the same routing reference, hop after hop to the PR (`--tick` runs one hop for hosts without stable long sessions); it never asks, and it writes every decision it made into the PR | A PR per spec (ready, or a draft when it carries an open item for you), `NEEDS_HUMAN` on anything it cannot settle | | Through merge | `/flow-next:flow --auto fn-12 --until=merge` | Flow routes the selected item to land | Landing complete, or an existing blocker; waits happen at the driver’s cadence | | Toward an outcome | `/flow-next:flow --goal [--until=merge]` | [Goal mode](https://flow-next.dev/autonomy/goal-mode/): it measures the goal’s criteria, mints the next child spec and builds it through `flow --auto` | `GOAL_MET` on recorded evidence for every criterion, or `NEEDS_HUMAN` with an open question in the goal log | | Unattended ship | `/loop 15m /flow-next:land ` | Land, on the one pull request you named | Merged, when you authorized the merge in that session; otherwise repaired and merge-ready | Flow without `--auto` is attended by contract. Under any autonomy marker (`FLOW_AUTONOMOUS`, `AUTONOMOUS=1`, a `mode:autonomous` token) it stops before any read with `NEEDS_HUMAN: /flow-next:flow is attended - run /flow-next:flow --auto for unattended runs`. `flow --auto` has no marker refusal, because it sets the autonomy markers itself for the stages it dispatches, and it invokes land only for the selected item with explicit merge authority; recursive drivers remain forbidden. Both entry shapes read `pipeline.qa` through the same gate-selection reference, so `auto` takes effect unattended. Flow-Next runs fully without the loops. [`/flow-next:flow`](https://flow-next.dev/skills/flow/) and [`/flow-next:work`](https://flow-next.dev/skills/work/) are the human-driven equivalents and need no loop primitive at all. Reach for `flow --auto` and land when there is a queue of blessed work and nobody who wants to sit through it. The review, QA, and tracker layers are recommended for unattended operation, because with nobody watching they are what replace the human, and each keeps its own switch: review runs through `review.backend` (unset, the review commands need `--review` or `FLOW_REVIEW_BACKEND`); live QA defaults to `off`, with `on` and `auto` both honoured unattended; tracker sync is opt-in through `/flow-next:tracker-sync`. Every key is on the [configuration reference](https://flow-next.dev/flowctl/configuration/). Optional [chart](https://flow-next.dev/skills/chart/) sits **before** capture and **outside** `flow --auto`. Unattended chart work may resolve independent unattended D-IDs in parallel (separate invocations); attended decisions stop at `CHART_VERDICT=NEEDS_HUMAN`. Chart never sets `ready` and never enters the build loop, so get the briefing captured first. ## Two loops, two slices of the lifecycle | Loop | Owns | Loop driver | Status | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | **[`flow --auto`](https://flow-next.dev/autonomy/pilot/)**, the build loop | ready spec → recorded direct/planned route → work → \[opt-in [qa](https://flow-next.dev/skills/qa/)] → PR, hop after hop in one invocation (opt-in [backlog mode](https://flow-next.dev/autonomy/pilot/#backlog-mode): widen selection to the whole open backlog) | one invocation per item; your host’s `/loop` or `/goal` with `--tick` where sessions are short | shipped in 5.1.0 | | **[Land](https://flow-next.dev/autonomy/land/)**, the ship loop | one named PR → threads resolved → CI green → authorized squash merge | your host’s `/loop` cadence, one PR per loop, or [your own loop over a list](https://flow-next.dev/autonomy/land/#several-pull-requests) | shipped | **`flow --auto` + land are the default autonomy path.** Together they cover the whole lifecycle from blessed spec to merged pull request; releases run separately under your project’s own instructions. Land picks up where `flow --auto` stops: at the open PR. Ralph, the older shell harness, was removed in 7.0; pin flow-next 6.7.x to keep it, or see [Migrating from Ralph](https://flow-next.dev/autonomy/pilot/#migrating-from-ralph). The `/flow-next:pilot` command was removed in 6.1.0; [Migrating from pilot](https://flow-next.dev/autonomy/pilot/#migrating-from-pilot) maps its arguments onto `flow --auto --tick`. ## The consent boundary No loop selects work you haven’t blessed. The entry gate is the spec-level **`ready` flag**: * **Local repos.** `flowctl spec ready fn-12` is the blessing; `flowctl spec unready` revokes it. * **Tracker-connected repos.** The board is the control plane: a Linear issue in your configured ready state (or a GitHub / GitLab issue carrying the ready label, or a Jira issue in the configured workflow status) blesses the spec, and moving it out starves the loop. See [Readiness as the control plane](https://flow-next.dev/autonomy/pilot/#readiness-as-the-control-plane). A half-baked draft is never executed unattended, and a spec that stops advancing is **automatically un-blessed** ([the two-strike guard](https://flow-next.dev/autonomy/pilot/#dont-thrash-guard)) rather than retried forever. The opt-in [**backlog mode**](https://flow-next.dev/autonomy/pilot/#backlog-mode) (`pilot.autonomy=backlog` or `flow --auto --backlog`, default off) moves this boundary one step *inside* the loop. It manages the whole open backlog, and when it can’t safely proceed on an item it surfaces a precise **async question** rather than stalling. It still **never authors a spec**, **never promotes** (the `ready` flag stays the human’s act), and grants **no merge authority from readiness alone**. Add `--until=merge` to authorize landing the selected item through land. Readiness remains the human’s explicit signal; the only erosion of the consent boundary is an auditable question a human answers async. [**Goal mode**](https://flow-next.dev/autonomy/goal-mode/) rests on a different explicit act: you name a goal on `--goal`. Within that goal, and only there, the run writes child specs and marks them ready, under the goal’s criteria and Boundaries, which it never edits. The goal spec itself stays unready, so no other loop builds it as one spec. ## Running the full pipeline For one ready spec, run `/flow-next:flow --auto fn-12 --until=merge`. Flow builds, opens the PR, and invokes land for that item through its existing gates. Because the run holds the merge, it makes a call itself when the call is reversible, inside the spec and backed by evidence (updating a snapshot the change legitimately altered, say), and records it in the PR’s Decisions list. An irreversible step, a product choice the spec leaves open, or anything that makes merging unsafe stops the run `NEEDS_HUMAN` before the merge. The default command without `--until=merge` still stops before landing. See [the destination and consent contract](https://flow-next.dev/skills/flow/#continue-through-merge). Building and landing can also run **side by side**: `flow --auto` builds spec N while land babysits spec N-1’s pull request. Land takes one named pull request per call, so the landing side is a loop you write. Two topologies. **Same session, one chained tick.** Simplest, zero setup: ```text /loop 30m - one tick: run /flow-next:flow --auto --tick --review=codex. If PILOT_VERDICT=DEFERRED_TO_LAND, find the open pull request of the spec it names and run /flow-next:land on that pull request in the same tick. I authorize merging it. Stop on any NEEDS_HUMAN. ``` Ticks serialize (a loop fires only while the session is idle), so a long work hop delays the next landing tick. Good for draining a small backlog in one sitting. On a host with stable long sessions, run `/flow-next:flow --auto` directly instead and let it carry each item to its PR. **Two instances, the assembly line.** Run `flow --auto` in one Claude Code / Codex instance and land in another, indefinitely. **Give the build instance its own clone (or git worktree) of the repo.** `flow --auto` checks out spec branches and refuses a dirty tree. Land never checks out a branch where you invoke it and repairs in an isolated checkout, so it can run from any clone. GitHub is the shared state: make-pr closes the spec on the pull request branch, the merge carries the close to the base, and land writes nothing afterwards. The strike ledgers of `flow --auto` are per-clone by design. The default build route of `flow --auto` does not pull the base branch; its branch matrix probes the current branch for an open PR and either stays put or checks out the local default branch, so the operator or scheduler fetches and fast-forwards the build clone before each invocation (they live under `.git/`, never committed). ```text clone A: /flow-next:flow --auto --review=codex # builds: ready spec → PR, one item per invocation clone B: /loop 15m - land pull requests 123 and 127 # ships: PR → merged; the list and the consent are yours board: drag issues to your ready state to feed the front of the line ``` The full instruction for clone B is [the loop over several pull requests](https://flow-next.dev/autonomy/land/#several-pull-requests). The two sides never fight over work. Land touches only the pull request you named, and only when every spec that pull request carries is closed at its head; an unfinished spec stops it `BLOCKED` with nothing changed. `flow --auto` defers specs that already have an open PR (`DEFERRED_TO_LAND`). The board (or `flowctl spec ready`) is the only throttle you need. A dependent spec does not wait for its parent’s merge: once the parent’s tasks are done and its branch is pushed, `flow --auto` builds the child as a chain on the parent’s branch, and land merges the chain from the bottom, one layer per invocation ([chains and stacks](https://flow-next.dev/autonomy/land/#chains-and-stacks)). ### Sculpt it into the factory you need The two loops do not change shape per use case; the paragraph of policy above them does. A bug-fixing factory reads the issue tracker and captures each accepted report as a spec that goes straight to work. A feature factory drains a blessed backlog on the direct route by default (`no_plan` recorded on the spec); plan runs only on a positive signal: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs. A docs factory leans on `flowctl gate classify` so a docs-only diff runs lint alone and skips the review backend. Same `flow --auto`, same land, same gates, a different paragraph. ### Built on it: Forge, a factory-manager bot [Forge](https://www.killenberger.com/#forge), by [Daniel Killenberger](https://www.killenberger.com/), is a Grok bot that wraps these loops as a standing process. It wakes on a push, a tracker change or a schedule, classifies each ready spec from its git state, hands the named flow-next job to a cloud agent or a CLI, and stays with it until land ships. It is one answer to the process question above, built outside this repo on the same verdict grammar. ## The safety model Hands-free is only useful if it can’t go off the rails. The same discipline applies across both loops: * **Readiness gate.** Loops select blessed work only; the human decision is structural, not skippable. * **Same review gates.** The same gates fire as in an attended run; autonomy suppresses *questions*, never *gates*. `flow --auto` reads them from the same gate-selection reference attended flow reads and never lowers one. Unattended, review loops fix and re-review until SHIP, with flowctl’s round cap as the backstop; the run may end the loop only over hardening, scope-creep or pre-existing findings below Major, and records each disagreement in the PR’s Decisions list. Terminal completion status is derived from the durable recorded attempt and live review cap, never from transient shell state. * **Delegation consent never stalls a run.** Work recognizes `FLOW_AUTONOMOUS=1` and literal `mode:autonomous` markers before the consent gate. Without persisted sandbox consent it disables Codex delegation and continues standard Work; it does not prompt, persist a choice, or widen authority. * **Decisions in the PR.** An unattended run never asks. Each default it chose, finding it declined and review it skipped goes into a Decisions list in the PR body, with its evidence. The PR opens ready; a human call that blocks nothing else goes in as an open item on a draft PR. Under `--until=merge` a reversible, evidence-backed call inside the spec is made and recorded instead, and anything else stops `NEEDS_HUMAN` before the merge; land never marks an unattended draft ready. * **Don’t-thrash.** The two-strike `spec unready` in `flow --auto`, land’s single CI fix per failure: every loop has a stop-digging reflex that hands the problem back instead of burning tokens. * **Surface, don’t force.** In [backlog mode](https://flow-next.dev/autonomy/pilot/#backlog-mode) “stuck” becomes an **async question** written into the spec or tracker, never an interactive prompt and never an autonomous guess. * **Never nested.** Attended flow refuses under every autonomy marker, and `flow --auto` dispatches no other flow or host loop. * **Evidence over narration.** Advancement is judged on observed state (flowctl fields, receipts, gh-confirmed PR URLs), echoed into the transcript or written as receipts. A loop never grades its own homework. * **Resume from disk.** Every hop ends with committed receipts and a ledger write, so a run that dies mid-way leaves what a dead tick leaves and the next invocation classifies from disk; nothing is resumed from transcript. ## Start here ```bash flowctl spec ready fn-12 # or move its issue into your ready lane ``` ```text /flow-next:flow --auto --review=codex ``` The run reports `ADVANCED` with the stages it dispatched and the PR URL, or `NEEDS_HUMAN` naming exactly where your judgment is needed. Run it again for the next item; when the backlog drains it prints `NO_WORK`. On a host without stable long sessions, `/loop 30m /flow-next:flow --auto --tick --review=codex` takes one hop per interval instead. ## Where this goes One driver reads the shared routing reference at both ends of the dial, with every rail carried across unchanged. An unattended run comes back in about the time plain Claude Code, or your harness, takes on the same change, often less; review and live QA are added only where the risk calls for them. Model and harness recommendations are deferred; your routing block chooses models today. [Flow and the road ahead](https://flow-next.dev/understand/flow-and-the-road-ahead/) states what the driver keeps and what it changes. ## The rest of this section [Flow --auto - the build loop ](https://flow-next.dev/autonomy/pilot/)One invocation carries one ready spec to its PR, hop after hop. The two shapes, the rails, the verdict grammar, readiness as the control plane, and backlog mode. [Goal mode - toward an outcome ](https://flow-next.dev/autonomy/goal-mode/)Work toward an outcome larger than one spec: measure a goal spec's criteria, mint the next child spec, build it through flow --auto, and keep a goal log that survives the session. [Land - the ship loop ](https://flow-next.dev/autonomy/land/)One named pull request from open to merged: the authorization rule, the verdict line, the land loop recipes, and the two land.\* config keys. [Driving a loop ](https://flow-next.dev/autonomy/driving-a-loop/)The default one-invocation recipe, the --tick snippets per host, why the verdict grammar is the driver contract, and the wrapper pattern for bridges that must not fail silently. [Unattended operation ](https://flow-next.dev/autonomy/unattended-operation/)The queue policy above the loops: eligible scope, worktree isolation, overlap defers, hourly wakes, headless runners, and what to measure.