# Orchestration - pipeline routing & model routing Source: https://flow-next.dev/guides/model-routing/ 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, an unattended field case with 38 pull requests landed, and a five-rung setup ladder. flow-next is an orchestration layer. The host agent conducts. It fans work out to tiered [subagents](https://flow-next.dev/subagents/overview/), routes [reviews](https://flow-next.dev/guides/review-workflow/) to a *different* model family than the writer, optionally drives a second CLI agent through a headless bridge, and runs autonomous [build](https://flow-next.dev/autonomy/pilot/)/[ship](https://flow-next.dev/autonomy/land/) loops. Which model does what is a routing decision - and every routing decision in flow-next is either a parameter or a sentence of intent away. The second kind carries judgment. Each dispatch resolves its model in a fixed order: an explicit argument in the invocation, then the routing block in your instruction file, then the agent definition’s own default (the scouts ship with a `model:` line, for example `why-scout` on `sonnet`; two agents inherit), then the session model when no applicable default is reachable. The pipeline runs complete with no routing block. Review backends are configured separately through `review.backend`; with it unset, the review commands need `--review=` or `FLOW_REVIEW_BACKEND` on each run, and `/flow-next:setup` sets the key once. Reach for this page when your model mix, subscriptions, or taste differ from those defaults, and ignore it until they do. **flow-next routes on two axes, and each decision prints its reason.** A per-prompt model router picks a model path for one request and the choice disappears. flow-next decides the *shape* of the pipeline per item and the *model* per job, and each decision lands as a line in the run report or a receipt on disk. | Axis | The question | Who decides | Where the decision shows | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **A. Pipeline routing** | Which stages does this item run - refine, plan, plan review, work directly, rolling or wave, QA, how many review rounds? | Capture’s `Recommended next:` line, flow’s route step (attended and under `--auto`), work’s Phase 3 route and zero-task fork, the review triage gate, `flowctl review-route` | The `Recommended next:` / `Scheduling:` / `PILOT_VERDICT` lines, the triage receipt, the review ledger | | **B. Model routing** | Which model runs this job - the implementer, the reviewer, a scout - and from which family? | The routing block in your instruction file, `review.backend`, per-task `review:` pins, the bridge recipes, a sentence in the moment | The review receipt’s `model` field, the worker dispatch prompt, the PR body’s verification block | Axis A is [Pipeline routing](https://flow-next.dev/guides/model-routing/#pipeline-routing-who-decides-the-shape) below; most of this page is axis B. A [field case](https://flow-next.dev/guides/model-routing/#field-case-one-paragraph-a-run-still-going) shows both axes running unattended through 38 merged pull requests, and the [setup ladder](https://flow-next.dev/guides/model-routing/#setup-ladder-from-nothing-to-a-standing-policy) takes a repo from zero configuration to a standing policy in five copy-paste rungs. Routing is one move on a larger menu. The doctrine (skip, reorder, prompt into, chain, parallelize, all under the same contracts) is [Skipping and composing stages](https://flow-next.dev/understand/compose-the-pipeline/); the copy-paste recipes, including a [model-routing section](https://flow-next.dev/guides/cookbook/#model-routing), live in the [Cookbook](https://flow-next.dev/guides/cookbook/). Optional [chart](https://flow-next.dev/skills/chart/) discovery respects the same automation boundary as the rest of the menu. Unattended drivers may fan out **one invocation per open unattended D-ID** (research / probe / eval); attended decisions (`prototype`, `interview`, attended `task`) terminate `NEEDS_HUMAN` and never self-resolve. Chart ends at a briefing for capture and never enters the `flow --auto` build loop. ## Tiers: what kind of model a job wants Two words carry the whole routing story. A **tier** is what kind of model a job wants. **Reach** is how the active harness obtains one - the in-session model, an in-host subagent, shelling out to another CLI, or not available. | Tier | What it means | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **reviewer** | Anything grading work someone else produced. The only tier carrying a family rule: a reviewer from the writer’s own family is not an independent verdict. | | **implementer** | Work handed to another harness. The load-bearing case - keep judgment on the session model and route implementation to a suitable model when useful. Absent, the session model implements. | | **fast scout** | Mechanical inventory scanning, where the cheapest model is the correct one. | | **thinking scout** | Analysis that degrades badly on a fast model. | | **unset** | The default, and the majority: planning, capture, refine passes, requirement analysis, every verdict, and the worker run on the session model (the scouts keep their pinned default). This is the never-delegate-judgment doctrine, stated as the default rather than as a special case. | Four names, chosen once. An **unrecognized tier name is treated as unset**, with one advisory line - never an error. **Per-task tier selection with a key (5.6.0+).** With `TYPESAFE_API_KEY` in the host environment, the conductor asks one judgment request per task before a worker or scout is dispatched: which tier would a senior engineer assign this task to? Only the two confident extremes act. A `mechanical` answer at confidence 0.8 or above sends the task to your routing block’s fast-scout model (the spawn model changes, and the dispatch carries `IMPLEMENTER:` for the bridge path); a `long_running` answer at 0.8 or above adds a bridge recommendation and changes nothing by itself. Every other answer keeps the current model, an explicit `IMPLEMENTER:` in the invocation always wins, with or without a key, and becomes the worker’s model (`Tier: implementer - (explicit invocation)`, since 8.5.2), and a block with no fast-scout model, or a host with neither model steering nor a bridge, keeps the model and says so. The dispatch and the done summary carry `Tier: mechanical (jev 0.88) -> ` with the model that actually ran. Without the key, the precedence below is the whole story. See [Optional Jev judgments](https://flow-next.dev/guides/jev-judge/). **Workers think less on routine tasks and more on hard ones.** The same tier call sets each worker’s reasoning effort, one level on the host’s own scale: one below the host’s default for a `mechanical` answer at 0.8 or above, one above it for an `intelligent` answer at 0.8 or above, and the default for every other answer. The step never goes past the host’s lowest or highest level. An effort you name in the invocation or the routing block, or one the worker role pins, wins over the tier; naming only a model (“use `` for the implementation”) keeps the tier’s effort. Without a key, or with the judge off or unavailable, every worker runs at the default, as before. The effort is fixed at dispatch, and scouts keep their own. The effort reaches a worker through the host’s spawn effort parameter (Claude Code builds that take one, such as 2.1.296; Codex `spawn_agent`) or a bridged implementer’s effort setting, carried as ` at `. Elsewhere the worker runs at the default. A spawn that rejects the level runs once more at the default, never at a third level. The `Tier:` line in each task’s done summary names the effort applied, or says it was not applied and why: ```text Tier: mechanical (jev 0.91) -> at low effort (host default medium) Tier: session (jev intelligent 0.84) at high effort (host default medium) Tier: mechanical (jev 0.88) -> ; effort not applied (host spawn takes no effort) ``` Measured in October 2026 on Opus 5.5, with three routine tasks the judge confidently called mechanical and five runs per side: workers at low effort passed 15 of 15, as workers at the medium default did, at a median cost per run 20 to 28% lower. The wall-time difference stayed inside run-to-run noise, so the measurement supports no speed claim. The raised effort on intelligent tasks has not been measured. Confident answers at either extreme are rare (about 1% of the maintainer’s past tasks for mechanical and 2% for intelligent), so most workers keep the default. **A tier says which model executes a stage, not which stages run.** Which stages run is decided by what you invoked; asking for a leaner pipeline is a separate instruction that already works. **The family rule is advice, not enforcement.** A model’s family cannot be verified from a name you invented, so the reviewer tier documents the rule, the receipt records what ran, and nothing fails closed on it. ### The routing block Preferences live in **your** instruction file (`CLAUDE.md` / `AGENTS.md`), in your own words, naming models you can verify against your own account. One line per tier: ```markdown reviewer: implementer: at fast scout: thinking scout: ``` An absent tier leaves the defaults in place: each scout keeps the model its definition pins (`sonnet`), and everything else runs on the session model. An unparseable line is ignored with one advisory, never an error. Effort semantics stay the host’s - flow-next passes effort through and never translates between vendors’ scales. [`/flow-next:setup`](https://flow-next.dev/skills/setup/) proposes this block commented out, for you to edit; nothing infers availability into it, and nothing rewrites a block a human has edited. The block is the durable form of an ad-hoc instruction: written once, read every turn, and still beaten by an explicit instruction in the moment. [`/flow-next:setup`](https://flow-next.dev/skills/setup/) offers to scaffold it with **every value commented out**, so nothing routes until you fill one in; it never asserts which models are installed, never overwrites a block a human edited, and is marker-fenced so `/flow-next:uninstall` removes it cleanly. Tier names are durable; model identifiers are volatile. That asymmetry is why routing is expressed as tiers here and as model names only in your file. Worked example, in a consumer’s own words: ```text you conduct + review (frontier, medium effort); implementation goes to via , one task per dispatch ``` ### Routing precedence **Highest first: an explicit argument in the invocation, then the project routing block in your instruction file, then the agent definition’s own default, then the session model.** There is no error surface. The chain terminates at the session model by construction. Agent definitions keep their `model:` field as the **floor** - what applies when nothing overrides - which is why a repo with no routing block behaves exactly as it always has. A model this harness cannot reach - another vendor’s identifier, a retired one, one your account lacks - falls back to the session model, says so once, and continues. No probing, no question, no failure. The [review backend](https://flow-next.dev/guides/model-routing/#route-the-reviews) is separate. It keeps its own `backend[:model[:effort]]` configuration and its own documented precedence. The tiers never touch it: the reviewer is chosen with `review.backend`, a spec’s or task’s review setting, or `--review=`. ## Reach: how each harness gets a model Reach is documented **once per harness**, never inside a skill. A skill asks for a tier and never names a spawn primitive, a CLI flag, or a vendor path. The three mechanisms are the in-session model, an in-host subagent, and shelling out to another CLI. | Harness | In-session model | In-host subagent | Shell out to another CLI | | ---------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | Claude Code | Yes | Yes - an agent definition’s model field is honored; current builds also take a spawn effort (seen on 2.1.296, absent on 2.1.283) | Yes | | OpenAI Codex | Yes | Yes - model and effort steering works on both the role and explicit-parameter paths since codex-cli 0.146.0 | Yes | | Factory Droid | Yes | Yes - reads flow-next’s agent definitions directly | Yes | | Cursor | Yes | Yes, but an agent definition’s model field is **ignored** | Yes | | xAI Grok Build | Yes | Yes - verified by a full planning fan-out | Yes | | OpenCode | Yes | Yes (Task-tool subagents; confirm per major) | Yes | | Meta Muse Code | Yes | Yes - verified by planning scouts and work workers | Yes - with Muse’s sandbox disabled | | Anything else / undetectable | Assume yes | Assume no until observed | Assume no until observed | **An undetectable harness takes the last row and says so once.** Guessing a harness is worse than naming the fallback: the generic row assumes the least reach and degrades cleanly. **Discovery beats declaration.** Where a harness or a CLI can list what it offers, ask it at the moment of use - one command beats a stored fact that goes stale. This is why the tables and examples on this page name no model identifiers: which model fills a tier is a property of your account and your machine, not of a document. **Degradation is the same everywhere:** a tier the harness cannot honor runs on the session model and says so once. That is the shipped default, so a harness with no dispatch mechanism at all still runs the whole pipeline - only the tier split is lost. Two harnesses carry a caveat worth stating outright: * **Codex** - a role’s declared model and effort win over an explicit spawn parameter; where the role declares none, the explicit parameter applies. Record what actually ran from the child rollout, never from the child’s self-report. One watch on a bridged child’s own fan-out: openai/codex#33267 (a `codex exec` parent unable to decode a spawned child’s result) is still open upstream against older codex-cli builds; current builds run its minimal repro clean, so the child keeps its delegation license. * **Grok Build and Muse Code** - every model each can reach natively belongs to one family. That matters for exactly one tier: **reviewer**, whose whole point is a verdict from outside the writer’s family. When it cannot be satisfied natively, the honest outcomes are to shell out to another vendor’s CLI, or to state that the review is same-family and let a human decide. An attended session asks; an unattended one stops and says a human is needed. ### Cursor host When the **session** is Cursor itself, orchestration differs from reaching Cursor models *from* another host via the headless `cursor-agent` CLI. | Surface | What happens on a Cursor host | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Agent-definition model fields** | Ignored - subagents inherit the session model. There is **no** alias-to-slug rewrite mechanism and none is planned. | | **The escape hatch** | Caller-side: name the model in the dispatch itself and the harness honors it (it also self-corrects a near-miss identifier). Slugs are **volatile** - ask `cursor-agent --list-models` immediately before pinning one rather than copying an identifier from a document. | | **`review.backend host`** | Bare only (`host:` is rejected). Review runs as a **host-native fresh-context subagent** pinned to a family that did not write the diff - never the session model grading its own diff, no subprocess. Preferred default from inside Cursor. | | **≠ the `cursor` CLI backend** | `review.backend cursor:…` is a separate headless subprocess path (multi-family reach from *outside* Cursor; circular when you are already inside it). | | **Cross-family rule** | Reviewer family ≠ writer family, measured from the **writer**. Fail-closed: without a cross-family pin, interactive setup asks; autonomous runs stop with `NEEDS_HUMAN` rather than silent same-family self-review. | With no caller-side model in the dispatch, every tier resolves to the session model - which is exactly the shipped default and needs no configuration. ```bash # In-session impl + host review (cross-family pin from the AGENTS.md routing block) flowctl config set review.backend host # or per-run: --review=host # Bridges FROM a Cursor host - the same recipes, reverse direction claude -p "" --output-format text --allowedTools "Read,Bash" " at ` One line in CLAUDE.md / AGENTS.md, read every session including unattended flow --auto runs. Absent, the session model implements - nothing to enable. [The routing block →](https://flow-next.dev/guides/model-routing/#the-routing-block) ## Route the reviews The review subsystem is the most routable surface, and it keeps its own configuration rather than reading these tiers. The spec grammar is `backend[:model[:effort]]` over `codex | copilot | cursor | claude | host | none`. ```bash flowctl config set review.backend codex # project default flowctl config set review.backend host # host-native fresh-context subagent (bare only) flowctl config set review.backend codex::xhigh # explicit model + effort ``` **The model that writes is never the model that reviews.** Route the reviewer to a different family than your session model and blind spots stop being correlated. The ladder, the per-task pins, the precedence chain, and what the reviewer actually receives are in [Review backends](https://flow-next.dev/reference/review-backends/). A compatible host can also supply [managed review execution](https://flow-next.dev/reference/review-backends/#managed-review-execution), routing the chosen backend through a registered account while Flow-Next keeps receipt ownership. The host wires the scoped connection automatically. Standalone Flow-Next keeps its normal CLI path. ### Steering the fan-out Review goes by risk, not by size. A small output, wording or display fix is not reviewed; the skip and its reason are recorded. On every backend, a change that touches persisted or shared state, concurrency, security, data layout or migrations, or a multi-file feature, gets **three reviewers at once** on the first round; a small diff in one area that touches none of those gets one. Each of the three runs the same backend, model, and base prompt and differs by a single axis line: correctness and logic of the changed code, contracts and consistency (do docs, tests, and stated promises agree with what the code does), and integration with unchanged code. The coordinator merges the finding sets into one deduped set and runs a single fix pass. The re-review resumes the reviewer’s session and looks only at the fixes. Attended, that one re-review is final; unattended, fix and re-review repeat until SHIP. Three reviewers because one is a sample, not a sweep: on a risky diff, three differently focused reviewers find more than one. The cost is review tokens, which is why a small diff gets one, and reviews are optional to begin with, so the panel only ever applies to a layer you already chose to switch on. The topology is steered by a sentence in the invocation. There is no flag and no config key. The coordinator reads your phrasing and hands the machinery explicit per-draw specs, and the machinery never reads prose. Take the shipped shape - reviewers by risk, one merged fix pass. `/flow-next:work fn-14` Say nothing and a risky diff gets three reviewers, a small one gets one. The right default when an agent wrote the diff and it will be merged without a human reading it line by line. You know the diff is small and clean - one reviewer is enough. `/flow-next:work fn-12 - use 1 reviewer instead of 3` The round runs a single reviewer whatever the risk call would have picked. The same phrasing works on /flow-next:impl-review. High-stakes merge - decorrelate families as well as axes. `/flow-next:impl-review fn-14 - use three different model families for the review fan-out` Each draw routes to a named family, so blind spots differ by model as well as by axis. On a CLI backend the correctness draw stays on the configured backend and the other two may name any CLI backend; on the host backend the per-draw pins are unconstrained. ## Implementation offload: the bridge route Offloading the token-heavy part (writing code) to a second CLI is a **routing decision you write, not a subsystem you configure**. There is no packaged delegation mode and no delegation config. Name an [implementer tier](https://flow-next.dev/guides/model-routing/#tiers-what-kind-of-model-a-job-wants) and drive the other CLI through a headless bridge, either ad hoc in the session or as standing policy in your instruction file. ```bash codex exec -m -c model_reasoning_effort= "" cursor-agent --model --force "" claude -p "" # the same bridge in reverse, from a Codex/Cursor host ``` Two rules survive from the packaged path and are not optional: * **The bridged child owns the task; the worker keeps judgment.** The child writes code, may commit checkpoints on the branch the worker names, and decides its own delegation under the same license an in-host worker holds. It never pushes, never rebases or rewrites history, never decides scope, never issues a review verdict, and never spawns a bridge of its own. The worker reviews the child’s commit range from the base it recorded before dispatch and runs the gates on it. Drop the never clauses and a bridge recipe becomes an unbounded second agent; forbidding the local commit or the child’s own fan-out bought nothing and forced host-inserted turns on long tasks. * **Which tier to bridge to:** on well-specified work a value tier matches a strong tier on correctness for meaningfully less wall clock, so send clear, well-scoped tasks to the value tier and escalate to the strong tier only for genuinely gnarly ones. Spec quality is what makes the trade safe - a vague brief burns the saving on rework. Full recipes, including the wrapper pattern for unattended loops, ship into the repo you work in and are read on demand with `flowctl usage` (`## Orchestration & model steering`). **Coming from `delegate:codex`?** The packaged mode and its `work.delegate*` keys were removed in 4.0.0. Leftover keys in `.flow/config.json` are inert - flowctl names them once in a non-blocking advisory and otherwise ignores them. Run [`/flow-next:setup`](https://flow-next.dev/skills/setup/), accept the routing-block scaffold, and use the bridge recipes above. ### Unattended bridges need a wrapper A raw bridge call fails quietly outside an interactive session. `codex exec` refuses in about a second outside a trusted git directory, and `cursor-agent` blocks on a workspace-trust prompt and then exits “successfully” with empty output. A loop dies silently on either. The wrapper pattern that fixes it, and its two load-bearing rules, are in [Driving a loop](https://flow-next.dev/autonomy/driving-a-loop/#the-wrapper-pattern-for-bridged-clis). ### Raw-bridge review prompts: demand severity tiers Applies to **ad-hoc bridge reviews only** - a hand-rolled review whose output a human reads directly. Put two things in the prompt: **P0-P3 severity tiers plus spec-grounded verdicts**, so an edge-case finding does not flip a ship gate; and optionally **a minimal suggested fix and blast radius per finding** when no fix loop follows the review. The **packaged** [`/flow-next:impl-review`](https://flow-next.dev/skills/impl-review/) prompt is deliberately not this shape. Its find-vs-fix split (the reviewer returns findings; the internal fix loop investigates and fixes, with validator and iteration caps) is by design. ## Prompted orchestration: routing with judgment This is the mode parameters can’t reach: routing policy that’s *conditional* and *per-item*, decided against the actual work rather than fixed up front. **Per-item complexity routing** - the host classifies, then routes: ```text Work through the three ready specs. Decide per spec, based on complexity, how the work stage runs: anything touching auth or the migration you implement yourself on the session model; plain CRUD goes out to the implementer tier over a bridge. Reviews come from a different family either way. ``` **Focus and scope steering** - instruction the skill never anticipated, read as intent: ```text /flow-next:plan fn-12 --depth=deep - focus the research on the migration path; I care about rollback /flow-next:refine fn-12 - push hard on failure modes and operational edges, skip UI polish /flow-next:work fn-12 - the UI tasks stay with you; send the API plumbing out to a bridge ``` **Conditional escalation** - routing that reacts to outcomes: ```text Run /flow-next:work fn-12 and bridge implementation out. If a task's review comes back NEEDS_WORK twice, stop bridging that task and implement it yourself on the session model. ``` **Prompting a capability into existence** - no registry entry exists for a session-model reviewer; that didn’t stop this repo’s own loop from running fresh-context, session-model-reviewed rounds: ```text /flow-next:plan-review fn-12 - don't use the configured backend; spawn a fresh-context subagent on the session model with the same review criteria, and feed its verdict into the fix loop like any other reviewer. ``` Backends, reviewers, and bridged implementers are prompts plus plumbing - when a rung you want is missing, describe it and the host builds the arrangement on the spot. The deterministic flags (`--review=`, `--depth=short`) still work inline for the parts that *are* parameterized; prompting composes around them. ## Pipeline routing: who decides the shape For a ready spec with no tasks, direct execution through `/flow-next:work --no-plan` is the default. Plan is chosen only on a positive signal: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs. Risk, size, and file count never trigger plan on their own. Design risk routes to `/flow-next:plan-review`, which reviews a zero-task spec; unresolved product or authority choices route to `/flow-next:refine`. This is guidance, not model detection or a configuration default. Explicit route consent still controls unattended execution. Nobody configures the shape an item takes. Six deciders read the item’s state and print their reason; you override any of them with a flag, a field, or a sentence. Capture’s closer, plan’s next-steps menu, work’s zero-task ask, and flow’s route step read the same six routing reference files (route matrix, spec count, plan versus no-plan, gate selection, prototype before ask, tail), so the recommendation you read and the route that runs come from one rule. | Decider | Reads | Decides | Prints | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Capture](https://flow-next.dev/skills/capture/)’s next step | The spec it just wrote: readiness, product/authority gaps, cohesion, agent capability, coordination constraints | refine, plan, `work --no-plan`, or `flow --explain` when signals conflict | `Recommended next: /flow-next: - ` on every run | | The [flow](https://flow-next.dev/skills/flow/) conductor | Whatever you hand it: nothing, an idea, a spec or task id, a tracker issue, a branch, a pasted bug report, a how or why question | The matching route-matrix row; runs it, or with `--explain` only prints it | `Next:` / `Route:` / `Signal:` / `Skip/narrow:` / `Skip kind:` / `Why not the alternatives:` under `--explain`; `Flow stopped at:`, `Route taken:`, one `stage:` line per stage, and `Next:` after a run | | [`flow --auto`](https://flow-next.dev/autonomy/pilot/)’s hop classifier | One ready spec’s state, matched against the same routing references attended flow reads: tasks, plan-review status, done tasks, the `no_plan` field, an open PR | `plan`, `plan-review`, `work`, `qa` (when gate selection selects it), `make-pr`, or defer to [land](https://flow-next.dev/autonomy/land/); re-classified after every hop | `PILOT_VERDICT= spec= stage= reason="..."`, with every dispatched stage joined by `+` in a long-horizon run | | [Work](https://flow-next.dev/skills/work/)’s Phase 3 route | Whether the run was given a task id, `planSync.enabled`, the open task count, the dependency closure | Inline in the conversation for one task; rolling frontier (default) or the wave loop for several; a zero-task spec forks to plan-first or [work-directly](https://flow-next.dev/skills/work/#start-without-a-plan) | `Scheduling: inline (single task)`, `Scheduling: rolling` or `Scheduling: wave ()` before the first claim | | The [review](https://flow-next.dev/guides/review-workflow/) triage gate | The diff: lockfile-only, docs-only, release chore, generated files | Skip the review backend with a `triage_skip` receipt, or run the full review; `FLOW_TRIAGE_LLM=1` adds a judge for ambiguous diffs | `Triage-skip: ` and a SHIP receipt with `mode: triage_skip` | | `flowctl review-route` | The review ledger: pending reservations, the last verdict, the artifact hash | A first review round (one reviewer or three, by risk), fix-then-rereview, or stop on an unchanged artifact | The route action in JSON, consumed by the review skills | Every decider fails closed toward the more careful shape: a missing `Touches:` line holds a task out of the rolling frontier, a spec with a named open decision routes to refine, an ambiguous diff gets the full review. Land’s merge gates, your session’s merge authorization and the patience window decide when a PR merges, and `flowctl gate classify` tiers a diff so a docs-only change runs lint alone. **Overriding a decider** is one surface each: `--no-plan` or `flowctl spec set-no-plan` for the fork, a task id instead of a spec id for the wave route, `--no-triage` for the gate, `--review=` or `flowctl task set-backend` for the reviewer, and a sentence for anything else (“use 1 reviewer instead of 3”). The rubric the deciders apply is [How Flow chooses](https://flow-next.dev/choosing-your-route/). ## Field case: one paragraph, 38 PRs landed One unattended run building a Linux desktop app in a private repo landed **38 pull requests**, steered by a single paragraph of standing policy with nobody in the loop. Each item was planned or worked directly by judgment, reviewed by another model family, QA’d in the running app, CI-green, and merged with a receipt. The policy steered both routing axes. The host chose the pipeline shape per item and the model per job; the build driver (pilot ticks then, `flow --auto` now) advanced the work toward pull requests, and land handled CI and review convergence through merge. | Run outcome, as of 5 September 2026 | Result | | ----------------------------------- | ------------------------------------------------------- | | Pull requests landed | 38 | | Steering | One paragraph of standing policy, nobody in the loop | | Pipeline shape | Planned or worked directly, chosen by judgment per item | | Review | Another model family reviewed each item | | Live QA | Each item exercised in the running app | | Merge evidence | CI green and a receipt for each merged pull request | The useful pattern is the malleable pipeline. One policy can send a fully understood change directly to work and give another change a planning pass, while assigning models and verification to suit the job. Rung 5 below shows how to write that kind of standing policy for your own repo. ## Field patterns, mapped to flow-next The orchestration patterns that emerged in the wild through mid-2026 all have a direct flow-next expression - most need one config key or one sentence: | Pattern from the field | The idea | flow-next expression | | --------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Orchestrator → executor** | The frontier model plans and judges; a cheaper, highly steerable model writes the code | An implementer tier plus a bridge recipe, ad hoc or as standing prose. Host keeps gating/git/review | | **Orchestrator → reader** | Token-hungry, low-judgment reads run on fast models that report summaries back | [Scouts](https://flow-next.dev/subagents/planning-scouts/) already return digests from fresh context; they ship on Sonnet, and a `fast scout` line moves them to another model | | **Cross-family reviewer** | The model that writes is never the model that reviews | `review.backend `; per-task `review:` pins exceptions | | **Effort discipline** | Orchestrator at high, not max - top effort tiers are token furnaces on routine work | Session effort is yours; a bridged child takes its effort inline, and the routing block’s `at ` makes the floor durable | | **Token-hungry offload** | Computer use and live-app verification go to other agents; results come back as evidence | [`/flow-next:qa`](https://flow-next.dev/skills/qa/) drives the app in its own context; workers run fresh-context and return receipts | | **Single path** | One request, one model, done | A tier pinned in the routing block (`implementer: at `); absent, the session model | | **Cascade** | A cheap model tries first; a gate decides whether a stronger one takes over | The value tier implements, the review verdict is the gate, and the standing permission to escalate (“if a cheaper model misses the bar, rerun on a smarter one”) moves the job up. The gate is a real review with a receipt, never a classifier | | **Critique** | A second model criticises and the first revises | Cross-family review on every backend, reviewers by risk (three on a risky diff, one otherwise, on every backend), a re-review scoped to the fixes, one re-review attended and a loop until SHIP unattended, a round cap, and `MAJOR_RETHINK` escalating to a human instead of looping | ## A default pipeline, expressed as tiers The routing this repo runs, stated in [tier](https://flow-next.dev/guides/model-routing/#tiers-what-kind-of-model-a-job-wants) terms. It names no model identifiers on purpose. Which model fills a tier is a property of your account and your harness, and only you can name it. | Stage | Tier | Why | | ----------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Plan (capture / refine / plan / plan-review critique) | unset - the session model | Spec authoring is inline and judgment-heavy; this is the never-delegate-judgment default | | Plan-review | reviewer, from a different family than the planner | Uncorrelated blind spots on the highest-leverage artifact | | Work (implementation) | implementer | Well-specified work runs correctly on a cheaper or faster tier; the saving is real only when the spec is clear | | Impl-review, first pass | reviewer, measured from the **writer** - not the host | A reviewer from the family that wrote the diff re-correlates the blind spots | | Impl-review, final gate | unset - the session model | Merging the findings and choosing the fixes stay with the session model; the verdict stays the reviewer’s | Notes that keep this honest: * **Single subscription? It still reads correctly.** Every tier degrades to the session model, and the pipeline works exactly as shipped - routing is optional garnish, never a prerequisite. * **Reach differs per harness, the tiers do not.** The bridges run in both directions, so the same tier assignment holds everywhere; only how you get there changes. See [Reach](https://flow-next.dev/guides/model-routing/#reach-how-each-harness-gets-a-model). * **Scouting splits by kind of work, not by price.** Mechanical inventory goes to the fast scout tier; analysis that degrades on a fast tier goes to the thinking scout tier. * **Routing is checkable after the fact.** Where the harness exposes it, a stage records the model that actually ran - a preference written in prose leaves evidence instead of a hope, and unavailable provenance is recorded as unknown, never as the configured value. ## Setup ladder: from nothing to a standing policy Each rung is one copy-paste and one sentence on what it buys. Stop at any rung; the rungs below it keep working. **Rung 1 - nothing.** Axis A runs with zero configuration: [`/flow-next:flow`](https://flow-next.dev/skills/flow/) routes from the shared matrix, capture prints its next step, `flow --auto` classifies, work builds one task inline and picks rolling or wave for several, triage skips trivial diffs. The agent definitions’ own defaults still apply (the scouts ship on `sonnet`; the two `inherit` agents run on the session model), and the session model takes every other job. **Rung 2 - a cross-family reviewer.** ```bash flowctl config set review.backend codex # or copilot | cursor | claude | host ``` Every review that runs now comes from a model that did not write the diff, and the verdict lands as a receipt on disk. Unattended runs read this key; a prompt cannot reach a 3am `flow --auto` run. **Rung 3 - the routing block.** In `CLAUDE.md` or `AGENTS.md` (`/flow-next:setup` scaffolds it commented out): ```text reviewer: at high implementer: at medium fast scout: thinking scout: ``` Name the ids your harness serves. Unset tiers keep the defaults: the scouts stay on their pinned `sonnet`, and planning, capture, refine and every verdict stay on the session model, where they belong. A model the harness cannot reach falls back to the session model with one note. **Rung 4 - per-item exceptions.** ```bash flowctl task set-backend fn-12.3 --review cursor: # this task's reviewer flowctl spec set-no-plan fn-14 # this spec skips planning /flow-next:work fn-12 --review=host # this run's reviewer ``` Fields ride with the item, so `flow --auto` and land honour them at 3am too. **Rung 5 - a standing policy paragraph.** In the same instruction file: ```text Work ready specs through Flow-Next work --no-plan by default. Plan only on a positive signal: I asked for a plan, separate human owners will implement, or delivery is staged across several PRs. Refine material product or authority gaps first; design review supports zero tasks. Record no-plan consent on the spec for unattended runs. Anything touching auth or the migration you implement yourself on the session model; plain CRUD goes out to the implementer tier over a bridge. Reviews come from a different family either way; if a task's review comes back NEEDS_WORK twice, stop bridging it and implement it yourself. Reviews focus on over-engineering and YAGNI. ``` The host judges each item against the paragraph and prints the reason with each decision. The last sentence is a standing [review focus](https://flow-next.dev/skills/impl-review/). Every reviewer gets it, including Codex reviewers, which never read this file. The field case above has run a shorter paragraph than this one since 3 September 2026. ## In your repo This page lives in the docs site - *outside* the repo you’re working in. At use time the host agent reads two things that are always current with the installed plugin: * **The usage guide**, pulled live with `flowctl usage` (the always-loaded `CLAUDE.md` / `AGENTS.md` block points agents at it). Its `## Orchestration & model steering` section carries the headless bridge commands - `codex exec`, `cursor-agent`, and the reverse `claude -p` - plus the flow-next shortcuts (`review.backend`, per-task `review:`) and prompted-orchestration examples. The bridges run in **every direction**: any harness that can run Bash can be the conductor. * **`CLAUDE.md` / `AGENTS.md`**, holding the durable routing block above. ## What stays fixed * **Judgment stays with the host** - a bridged child writes code; it never owns git, task state, review verdicts, or decisions. * **Merge is human-gated** everywhere except the explicitly opted-in land loop and `flow --auto --until=merge`. * **Verification is independent** - a bridged diff is never trusted on the child’s own summary; the host re-runs the gates before `flowctl done`. * **Escalation beats thrift** - when you downgrade a tier, watch the first outputs and revert on the first quality miss.