The pipeline is a composable pipeline. This page is the menu written out: verified recipes, organized into moves. Every recipe is three things - a scenario in your words, the exact invocation, and one line on why the execution, evidence, and review contracts survive the shortcut.
Two conventions throughout:
fn-14 / fn-14.2 are placeholder ids - substitute your own spec and task ids (tracker keys like wor-17 resolve everywhere the fn- form does).| Move | The idea |
|---|---|
| Say it in plain language | No slash command or flag required - describe what you want; the host maps it onto the skill. |
| Skip & lighten | Drop stages the change does not need; the contracts stay. |
| Lean artifacts | A house-style block in your instruction file sets the length of PR bodies, done summaries, and spec prose. |
| Prompt into a stage | Every skill takes plain-language steering next to its arguments. |
| One-shot chains | Chain the pipeline in a single message; each stage still fires its gates. |
| Evidence-first | Put proof at the center: your research, your tests, live-app verdicts. |
| Model routing | Route reviewers, workers, and delegates per step - parameter or sentence. |
| Parallelize | Disjoint tasks in parallel: multiple sessions or one prompted dispatch. |
| Autonomy dial | One dial from Flow at the keyboard to flow --auto and land; gates fire identically at every rung. |
| Integration tricks | Trackers, feature maps, readiness checks, external reviewers. |
| Team patterns | Specs as PRs, atomic claims, handover breadcrumbs. |
| Compose beyond the pipeline | Research, test, or eval first - then let the result write the spec. |
| Frontier moves | N-model review juries, spec-review synthesis, best-of-N implementations, reproduction-driven specs, memory mining, harness-hopping. |
You do not have to type a single slash command or --flag. Say what you have and /flow-next:flow picks the route, runs the stages, and stops at the next decision that is yours. Every stage is also a skill triggered by describing what you want, and every argument has a natural-language equivalent - the host agent maps your sentence onto the skill and its options. The explicit forms in this cookbook are the precise version; a sentence does the same thing.
Hand Flow whatever you have and let it choose.
"this endpoint got slow after the last release" == /flow-next:flow <the same words> ✓ Flow routes on content, never on input kind. A measured slowness gets a baseline first, a bug report gets a prior-fix check and a failing reproduction, a why question gets a cited answer. Every stage it runs or skips prints one line with its reason; a change-producing run stops when the PR exists and an investigation stops at the answer.
How Flow chooses →See the route before anything runs.
/flow-next:flow --explain fn-14 ✓ Prints Next, Route, Signal, Skip/narrow, Skip kind, and why not the alternatives, then stops. No .flow/ write, no dispatch; the route is recorded only on a plain run.
Make a spec from what we just worked out - no command needed.
"lock down what we just discussed as a spec" == /flow-next:capture ✓ Skill descriptions carry natural-language triggers; the host recognizes the intent and runs capture on the conversation.
Steer the whole run in one sentence instead of stacking flags.
"implement fn-12 on a new branch and review it with codex" == /flow-next:work fn-12 --branch=new --review=codex ✓ Arguments are parsed from plain language - 'a new branch' and 'review with codex' resolve to the same options as the flags.
Trim the research without remembering the flag name.
"plan fn-21 but keep the research light" == /flow-next:plan fn-21 --depth=short ✓ 'keep the research light' maps to the depth control; the gates it does not touch (R-ID coverage, plan review) are unchanged either way.
Pull a tracker issue in and spec it, conversationally.
"grab issue WOR-17 and spec it" == /flow-next:tracker-sync (tracker-first link) ✓ The tracker-first link path is reachable by intent; flow keeps the spec as source of truth, the issue as a co-editable mirror.
Interview a spec on the business angle, without the flag.
"interview fn-14 - focus on the business requirements, not the tech" == /flow-next:refine fn-14 --scope=business ✓ 'focus on the business requirements' resolves to the business scope; the question pass focuses on product decisions, sections no answer belongs in come back byte-for-byte, and the read-back names every section it changed.
Assess the repo before you trust an agent with it.
"is this repo ready for agents? what should I fix first?" == /flow-next:prime ✓ Prime classifies the project and leads with a ranked next-actions list - the same output whether you ask in words or by command.
Drop the stages a change does not need. Skipping is a route through the contracts, never around them.
Clear local change - skip chart; capture or plan directly.
"Capture the --json export flag - intent and boundaries are clear" == skip /flow-next:chart ✓ Chart only adds signal when consequential unknowns block stating intent. Signal absent means skip chart and still keep capture/plan/review contracts.
Tiny local fix - just tell flow; no spec at all.
/flow-next:flow the export footer prints the wrong year ✓ A tiny, local, low-risk change goes direct: changed, checked, and handed back, with no spec and no pull request unless you ask. A small output, wording, or display fix is not reviewed, and the skip is recorded with its reason.
How Flow chooses →Small fix - skip prospect and refine, write the spec yourself.
flowctl spec create --title "Fix retry backoff" ✓ Fill the strong spec before execution, then use Flow-Next work --no-plan for a cohesive change. The work and review contracts still require evidence, and flowctl done records it.
Ready cohesive spec and capable agent - execute through Flow-Next work.
/flow-next:work fn-21 --no-plan ✓ One execution owner covers every R-ID through the same configured review, coverage, completion, and evidence gates.
The no-plan route →Record direct execution consent so flow --auto works the full spec unattended.
flowctl spec set-no-plan fn-21 ✓ The field is the flag's durable, autonomy-compatible form - human-set on the item, read by flow --auto and work, refused once tasks exist, and never tracker-projected. Left unset, flow --auto records the route itself from the plan-versus-no-plan rule before any mint.
The no-plan route →Contained change - trim the planning research.
/flow-next:plan fn-21 --depth=short ✓ Depth trims the scout fan-out, not the gates: R-ID coverage and plan structure are unchanged.
Low-stakes spec - skip the plan review and go straight to work.
/flow-next:work fn-21 ✓ Implementation review and per-task evidence still fire; you dropped one gate consciously, not all of them silently.
Trivial task - skip the code review, on the record.
/flow-next:work fn-21.3 --review=none ✓ An explicit, visible opt-out: commits and evidence are still recorded, and the configured backend returns on the next task.
No spec at all - fix it first, then decide if it was worth freezing.
/flow-next:capture ✓ Smallest sufficient workflow: capture exists for when the conversation produced decisions worth keeping, not as a toll on every edit.
Skip the review backend on a docs-only, lockfile-only, release-chore, or generated-only diff, with a receipt.
flowctl triage-skip --base main ✓ A qualifying diff gets a deterministic verdict and a receipt with mode: triage_skip that satisfies the review gate. A diff that does not qualify gets no receipt and the backend still runs; the receipt, never the label, justifies the skip.
Flow-Next sets no length rule for the artifacts it writes. The right budget for a PR body is not the right budget for a memory entry, so length is a house-style decision, and house style lives in your AGENTS.md or CLAUDE.md. The drafting agent reads that file in the same context as the prose contract, and the host hands it to subagents too, so one block there reaches every artifact the agent drafts.
That includes the part of the PR body that looks machine-made. flowctl renders the The change, top to bottom walkthrough deterministically and picks its compact or full form from the size of the change, with no per-repo switch. The agent still writes every word in it: the thesis, how many step groups there are (one to seven), each group summary, and each per-file summary.
Measured on one real 23-file PR, same payload, same files, same full form:
| Default | With the block below | |
|---|---|---|
| Whole walkthrough | 1136 words | 662 words |
| Prose (thesis, group summaries, evidence lines) | 490 | 147 |
| Table rows (proof table, one row per file) | 646 | 515 |
The file rows are the floor. Every changed file keeps its row with its path and links, so a 60-file PR stays longer than a 6-file one whatever the house style says.
## Artifact house style
### PR body (make-pr)- Walkthrough: at most 3 step groups. Merge steps one reviewer would read together.- No optional walkthrough groups (problem, principle, kept, verify) unless the PR is confusing without one.- Thesis: one sentence, under 30 words. Group summaries: under 25 words.- File summaries: under 8 words. One word ("Mirror.", "State.") for generated and mechanical files.- Why: three sentences at most. What to check in each review step: one line.
### Task done summaries- Lead with what changed for the user, in one sentence.- One line per acceptance criterion it satisfied. No narration of the work.
### Spec prose (capture, refine, plan)- Goal & Context: under 120 words.- One sentence per acceptance criterion, plus its error cases.- Decision Context: the decision and the rejected alternative, one line each.What the block cannot do is drop or reshape a section an emitting skill defines. A house rule that says “no Verification section” loses to the PR body’s own structure, on purpose, because reviewers learn where to look.
The captured spec opens with 15 to 20 lines of raw quotes nobody acts on.
Delete "Conversation Evidence" from auxiliary_sections in your SPEC.md ✓ Capture writes only the sections your scaffold names. It still collects the quotes during the run and still checks every untagged line against them, so an untagged line keeps its meaning: the user's own words.
Leaving a section out →Every skill takes steering prose next to its arguments. Say what you want; the stage does its job under your constraint.
Constrain the plan before it exists.
/flow-next:plan fn-8 - keep it to 3 tasks max; the schema migration is the only risky part, isolate it ✓ The planner works inside your constraint; task structure, R-ID coverage, and plan review are unchanged.
Reshape a plan you disagree with.
/flow-next:plan fn-8 - re-plan: merge tasks 2 and 3, the schema work is one unit ✓ Re-planning rewrites the task graph through the same skill that built it - nothing is hand-edited out from under the contracts.
Steer the worker toward the codebase's own patterns.
/flow-next:work fn-8.2 - follow the existing repository pattern in src/repos/, no new abstractions ✓ Steering changes how the task is implemented, not whether it is reviewed and evidenced.
Interview for business shape only - the tech is already decided.
/flow-next:refine fn-9 --scope=business ✓ The scope focuses one question pass over the same spec; a later session with --tech picks up the technical decisions.
Capture anything that carries intent - a ticket, a briefing packet, research, a prototype.
"here's the JIRA ticket text - capture the initial spec" ✓ Capture is the intake valve, not a conversation-only tool. It synthesizes the spec, proposes whether the input is one spec or several, leaves your own words untagged and tags what it wrote [paraphrase] or [inferred] - the provenance the next stages run on.
Stop debating spec size - capture the entire epic.
"here's the whole epic from the kickoff - capture it" ✓ The 'how big should a spec be?' debate dissolves at intake: capture scopes the epic into several specs with the dependency edges already recorded, each self-contained and independently reviewable. Then improve each one where it's soft - steering prose or a targeted interview - instead of hand-carving one oversized document.
Aim the interview at exactly what the agent guessed.
"do a business interview with me on fn-9 regarding anything that has been inferred" ✓ Capture tagged the guessed lines [inferred]; targeting them means every question lands on a guess, none on what you already stated, and refine still asks only about the guesses that would change the build.
Pressure-test the one requirement that worries you.
"in-depth technical interview on fn-9 regarding R9" ✓ The full question machinery - recommendation-led questions, codebase investigation before asking, experiments instead of questions - concentrates on a single criterion instead of re-walking the whole spec.
None of the interview's options fit - steer instead of settling.
Other: "go research how our billing service handles this before asking me, then re-ask" ✓ The proposed answers are support for your thinking, not a multiple-choice test - the AI shouldn't make judgment calls for you. Other is fully agentic: answer in your own words, send it back to research, redirect the questioning, or park the question. Picking the recommended option every time launders guesses into requirements.
Point the reviewer at what worries you.
/flow-next:impl-review fn-8.2 - scrutinize the locking around the job queue ✓ Focus prose adds attention, never subtracts: the full review criteria and verdict grammar still apply.
Guide the planner's scouts on a domain the base model is weak at.
"plan fn-8 - it's a 3D composition task; have the scouts read the three.js scene-graph + camera docs and the examples in <repo/urls> before breaking it down" ✓ Plan dispatches research scouts (framework docs, best practices, code patterns); naming the exact references grounds the breakdown in the real API instead of the model's shaky prior - especially valuable where the base model tends to hallucinate. The scout fan-out is steerable; the plan structure and R-ID coverage it produces are not.
Chain the pipeline in a single message. Each stage in the chain fires the same gates it fires when stepped.
Idea to PR in one message.
/flow-next:plan fn-14 - then work the spec and open a PR when everything is green ✓ Chained stages are the same skills in sequence: plan review, impl review, evidence, and PR body generation all still run.
Freeze a design discussion and take it to a plan, one message.
/flow-next:capture - then refine the new spec and plan it ✓ Capture saves the spec and offers it for editing; refine and plan consume it exactly as if you had invoked them by hand.
Run a whole spec end-to-end.
/flow-next:work fn-14 ✓ Spec-level work is the built-in chain: a single task is built inline in the conversation, several tasks run on the rolling frontier in dependency order, and each change is reviewed by risk with its evidence recorded.
Advance one ready spec by exactly one hop, the equivalent of one flow --auto hop.
/flow-next:flow --auto --tick fn-14 ✓ One hop is the bounded chain: --tick classifies one stage from the routing reference, dispatches it, verifies from observed state, and ends with one PILOT_VERDICT line. Gates are identical to attended runs. It replaces /flow-next:pilot --spec fn-14, removed in 6.1.0.
Six worked traces of pre-capture discovery live with the discovery material rather than here: Discovery before capture. The recipes below assume you already have something to capture.
Put proof at the center of the run - your research, your tests, live-app verdicts. Verification is the spine the menu hangs off.
Plan from research you already have.
/flow-next:plan fn-14 - we already did the research, it is in the spec; skip redundant scouting and go straight to breakdown ✓ The scout fan-out is the default floor for cold starts, not a tax on warm ones - R-ID coverage and plan review still gate the breakdown.
Maintainer-flagged. When a spec was preceded by real research - audits, evals, a long exploration - tell the planner so. Live example: the messaging overhaul that produced this very page was planned this way from a six-audit research pass.
Wire your own proof into task completion.
flowctl done fn-14.2 --summary-file s.md --evidence-json e.json ✓ flowctl done records the evidence JSON you supply on the task. The work and review contracts require the commits and test evidence before a task closes, and PR links join the record once a PR exists. Whatever proof your project produces belongs in that JSON.
Resolve an unfamiliar library's current docs into the spec before anyone codes against it.
/flow-next:refine fn-14 --scope=research ✓ Four read-only scouts (docs, practice, docs-gap, memory) return sourced findings; refine drafts one Resolved via Research section from them, with a source on every bullet, and writes it back only after you ratify it. An existing section or a plan that ran the scouts skips the pass for what they already cover; a library named since then reruns for that delta only, and --force reruns the whole pass and replaces the section.
The research scope →Find out why a guard exists before touching it.
"why does the parser reject empty headers? cite the commit or PR" ✓ Flow dispatches why-scout: git blame, the PRs behind the commits, the tracker thread through access you already have, then bug and decision memory. Each finding is tiered direct, supported, inferred, or unknown, and nothing under .flow/ is written.
Run live QA only on the specs that have a UI to drive.
flowctl config set pipeline.qa auto ✓ Attended or under flow --auto, auto runs the live pass when the acceptance describes UI behaviour on a drivable surface with a startable target, and records skipped(config: pipeline.qa=auto: reason) otherwise. Both drivers read the same gate-selection rule since 5.1.0.
Live-app QA →Get a live-app verdict before the PR.
/flow-next:qa fn-14 ✓ QA derives scenarios from the spec's acceptance criteria and is forbidden from passing by reading source - the verdict rests on captured evidence from the running app.
Stop re-deriving how to reach each screen.
/flow-next:features ✓ Seeds a committed user-POV map at .flow/features/ - every route proven by one live drive before it lands, and QA reads navigation from it instead of rediscovering it.
How the map works →Keep the feature map honest on a cadence.
/loop 1d /flow-next:features ✓ A present map routes the same command to the maintain pass: source readers, one live drive per feature, then clean, one chore PR of proven corrections, or a named block. Never a pipeline stage - the cadence is yours. Run it from a plain session you start; an autonomy marker ends it REFUSED.
Keep the feature map current →Read the receipts before you merge.
flowctl show fn-14.2 --json ✓ Every task carries its evidence and review state on the record - merge decisions read artifacts, not vibes. See Receipts for the full trail.
How receipts work →Make live-app QA a standing pipeline stage.
flowctl config set pipeline.qa on ✓ Attended flow and flow --auto insert one QA pass when all tasks are done, before the PR - findings surface into the PR instead of hard-blocking the loop. `auto` runs it, under either driver, only when the spec describes UI behaviour on a surface that can be started.
See which requirements you actually said, and which the agent guessed.
flowctl cat fn-14 | grep -oE '\*\*R[0-9]+[a-z]?:.*\[[^]]+\]$' ✓ Capture and refine both tag every acceptance criterion they write at source - the human's own words stay untagged, [paraphrase] marks their meaning tightened, [inferred] the agent's own inference. Reviewing a spec is then a filter, not a re-read.
The tally is the useful part. Piped through sed and awk you get counts per tag, so “how much of this spec is guesswork” becomes a number instead of a feeling:
flowctl cat fn-14 \
| grep -oE '\*\*R[0-9]+[a-z]?:.*\[[^]]+\]$' \
| sed -E 's/^\*\*(R[0-9]+[a-z]?):.*\[([^]]+)\]$/\2\t\1/' \
| sort | awk -F'\t' '{c[$1]=c[$1]" "$2; n[$1]++} END {for (t in c) printf "%-26s %2d %s\n", t, n[t], c[t]}'
user 6 R1 R13 R5 R6 R7 R8
paraphrase 3 R10 R12 R2
inferred 4 R11 R3 R4 R9
strategy:Cross-platform parity 1 R14Two details there are load-bearing, because a track name keeps its literal casing and can contain spaces: the class is [^]]+ rather than [a-z:]+ (a lowercase-only class silently drops every [strategy:*] criterion), and sed emits a tab that awk reads with -F’\t’ (with the default whitespace split, a spaced track name lands in the wrong field and the tally reports a phantom tag).
This is deterministic - a grep, not a judgement call - which is the point. You are not asking a model whether the spec is well-grounded; you are reading a tag the authoring pass already committed to. The read-back also refuses to recommend approve while unverified [inferred] items remain, so the tags gate the write-back rather than just decorating it.
Two things to know when reading a tagged spec: a pass tags only the criteria it writes and never retags an existing bullet, so on a spec refined in a product session then a technical one each tag reflects its author; and an untagged line is the user’s words only when capture or refine wrote it - hand-written or older criteria carry no tag either.
Interview only the requirements the agent guessed.
/flow-next:refine fn-14 - focus only on the [inferred] acceptance criteria (R3, R4, R9, R11); the untagged and [paraphrase] ones are settled, leave them alone ✓ The expensive part of a refine pass is re-litigating what you already said. Naming the inferred R-IDs keeps the pass on the actual uncertainty, and refine still asks only about the guesses that would change the build.
Get the list from the recipe above, then paste the R-IDs in. Append-only R-ID numbering is what makes this safe: a later pass cannot renumber or rewrite the criteria you already blessed, so a targeted pass can only add or sharpen the ones you pointed it at.
Route reviewers, implementers, and scouts per step. A parameter sets the floor; a sentence steers above it. Full doctrine: Orchestration.
Make reviews cross-family by default.
flowctl config set review.backend codex ✓ A different model family than the writer means uncorrelated blind spots - the review gate itself is unchanged.
Pin a different reviewer for one task only.
flowctl task set-backend fn-14.2 --review cursor ✓ Per-task overrides win above env and config; every other task keeps the default backend.
Override the reviewer for one run, no config change.
/flow-next:work fn-14 --review=cursor ✓ A run-scoped override routes this run's reviews and nothing else - the configured default is untouched.
Offload implementation to a second CLI agent.
"implementer: <your model> at <effort>" - one line in CLAUDE.md / AGENTS.md ✓ No layer to enable: name an implementer tier and the worker hands the task to the other CLI over a headless bridge. The bridged child owns it: it writes code, commits checkpoints, and decides its own delegation; the worker reviews the child's commit range, re-runs the gates, and keeps task state, review, and judgment. Absent the tier, the session model implements.
Implementation offload →Force one reviewer when you know the diff is small and clean.
/flow-next:work fn-12 - use 1 reviewer instead of 3 ✓ On every backend a risky diff gets three reviewers, one per axis, and a small one gets one. Saying this runs one reviewer whatever the risk call would have picked, and saves the review tokens of the other two.
Steering the fan-out →Spread a high-stakes review across model families, not just axes.
/flow-next:impl-review fn-14 - use three different model families for the review fan-out ✓ Each of the three draws routes to a named family, so blind spots decorrelate twice over. 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.
Steering the fan-out →Route by sentence, not by flag.
/flow-next:work fn-14.2 - use a fast-tier subagent for the bulk file sweep, keep judgment on the session model ✓ Prompted routing rides the same worker contract - the sweep is cheap, the decisions are not, and the review gate does not care who typed the code.
The planner reports execution waves from the task DAG. The work conductor inspects the current ready frontier and may dispatch a safe subset concurrently; no flag is required. It chooses worker count, isolated mutable workspaces, and integration arrangement from the live host capabilities. By default it runs a rolling frontier: each time a worker returns, it admits the next ready task in its own worktree. The wave loop, which joins a whole wave before the per-task gates, is the fallback (a task-id run, planSync.enabled, or a fully sequential chain).
Two sessions, one spec - each takes a task.
/flow-next:work fn-14.2 ✓ Session B may run .3 at the same time when each writer has an isolated workspace and a safe integration path. Atomic claims prevent duplicate ownership; they do not protect a shared Git index or filesystem.
Parallel work from one spec →One session, let the host schedule the ready frontier.
/flow-next:work fn-14 ✓ The host admits the next ready task each time a worker returns, integrates each result, and runs the unchanged review, evidence, completion, and tracker gates; the wave loop is its fallback.
Isolate a build in its own worktree.
/flow-next:work fn-15 --branch=worktree ✓ Filesystem isolation for parallel streams - each checkout builds and commits independently before the conductor-owned join and integration step.
Find out which specs can run in parallel.
/flow-next:deps ✓ The dependency graph shows blocking chains and independent phases - parallelism planned from declared edges, not guessed.
One dial from Flow at the keyboard to fully autonomous - same pipeline, same gates at every rung. The rungs below are in increasing order of independence.
Stay at the keyboard and let Flow drive to a finished change.
/flow-next:flow fn-14 ✓ Attended by contract. It asks at most one pick per hop, stops by default with the change committed on a local branch (say 'open the PR' when you want one), and offers landing on an existing PR. --until=merge authorizes that item upfront; otherwise it asks once, and refuses to run under any autonomy marker. flow --auto and land are the unattended rungs below.
Flow →Run one skill unattended.
/flow-next:plan fn-14 mode:autonomous ✓ Autonomous mode swaps questions for hard errors - it never swaps gates for trust.
Mark a spec safe for autonomous pickup.
flowctl spec ready fn-14 ✓ Ready is the consent flag you set - loops consume only what you explicitly blessed. The one exception is goal mode, which readies only the child specs it mints for a goal you named.
Run the build loop unattended, one item per invocation.
/flow-next:flow --auto ✓ One invocation carries one ready spec to its PR, hop after hop, never asks, writes every decision it made into the PR, and ends with one PILOT_VERDICT line; run it again for the next item. Every hop leaves receipts and a ledger entry, so a run that dies mid-way resumes from disk.
Flow --auto →Run one hop per interval on a host without stable long sessions.
/loop 30m /flow-next:flow --auto --tick ✓ Each tick advances one ready spec by one stage and ends with a verdict line - bounded progress, receipts every tick. /loop needs Claude Code 2.1.72 or later and a loop expires after 7 days. It replaces the /flow-next:pilot recipe; that command was removed in 6.1.0.
Prep a dependency-ordered backlog so the loop drains it in the right order.
"plan all of these specs so they're ready, and set the dependencies so flow --auto knows the correct order" ✓ Plan each spec and wire its blockers; the loop selects a spec once its dependencies are satisfied - done, or a parent whose tasks are done and whose branch is pushed, in which case the dependent builds as a chain on the parent's branch - so the order emerges from the graph you set, not from luck. Do the ordering once, up front; the loop respects it every tick.
Let flow --auto work the whole backlog.
/flow-next:flow --auto --backlog ✓ Backlog mode widens selection and never permissions - the stage set, verdict grammar, and gates are the same as single-spec mode. One run drives its selected item to a terminal and stops; the next invocation selects the next item.
Port an app, run a migration, or work a PRD down to shipped changes.
/flow-next:flow --goal docs/migration/target-spec.md --until=merge ✓ Goal mode captures the document as a goal spec whose criteria are the bar, then measures, mints the next child spec and builds it through flow --auto, one merged child at a time. The goal log in the spec carries the run across days; a question only you can answer parks one criterion while the rest continues.
Goal mode →Babysit one open PR to merge.
/loop 15m /flow-next:land 123 ✓ Land resolves review feedback, makes one CI fix or one flake rerun per failure, and squash-merges the pull request you named once every gate passes. Naming it yourself is the merge authorization. To land several, list them and call land on each.
The land loop recipes →Drain a blessed maintenance queue all the way through production proof.
"/goal run the maintenance-factory policy: select only ready maintenance items, isolate each spec in its own worktree, alternate flow --auto --tick and Land, and stop after two hourly NO_WORK wakes" ✓ The controller narrows intake and authority; flow --auto and Land keep their normal stage gates. Overlap is deferred, ambiguity becomes an auditable question, and runtime completion requires release identity plus per-target live evidence.
Copy the full maintenance-factory goal →Run one fresh maintenance wake per hour from a scheduler.
codex exec -C "$repo" --sandbox workspace-write "$(cat .flow/automation/maintenance-queue.md)" ✓ The scheduler owns cadence, budgets, repository locking, and durable logs; the headless host executes one bounded wake and lets the flow --auto and land verdict lines drive the next action. The same pattern works with claude -p, CI jobs, or an internal operator.
Headless Claude, Codex, and tracker setup →The pipeline meets the rest of your toolchain: trackers, feature maps, readiness assessments, external reviewers.
Grab a tracker issue and spec it.
/flow-next:tracker-sync - grab WOR-17 and spec it ✓ Tracker-first specs are keyed by the tracker id (Linear and Jira keys qualify); the spec stays the source of truth, the issue a co-editable mirror.
Project a spec onto the tracker for PM visibility.
/flow-next:tracker-sync fn-14 - push to linear ✓ Projection, not coordination: status and comments reconcile two-way, and the spec remains canonical.
Give scouts a semantic map of the codebase.
/flow-next:map ✓ A feature index anchors R-IDs and investigation targets to concrete code regions - better plans in, same review gates out.
Check the repo is agent-ready before adopting.
/flow-next:prime ✓ A verdict plus ranked next-actions, with commands actually executed - substance over existence, before you trust a loop with the repo.
Assess a different repo without leaving this session.
/flow-next:prime ~/other-project ✓ Prime takes a path - triage another codebase (or a whole portfolio, one at a time) for agent-readiness from where you already are, without checking it out into your working tree.
Hand-edit a spec or task in your own editor between stages.
"open the spec and all subtasks in zed" → edit → /flow-next:work fn-14 ✓ Specs and tasks are plain markdown in your repo - the skills do not own them. Tighten an acceptance criterion in your editor, then hand the file back to the next skill; it picks up your edits. You are never locked out of your own files.
The same contracts that keep agents honest keep teams coordinated - handover objects instead of standups.
Review the spec like code, before any code.
git add .flow/specs && git commit -m "spec(fn-14): payment retries" && gh pr create --draft ✓ Spec-as-PR puts the cheapest-to-fix artifact through the strongest review culture you already have.
Team workflow →Claim a task before touching it.
flowctl start fn-14.3 ✓ Atomic claims with assignee collision checks - two actors cannot silently work the same task.
Standup without the meeting.
flowctl list ✓ Specs, tasks, statuses, and claims in one view - the state of the build is a query, not a ceremony.
Read the breadcrumb before starting a dependent task.
flowctl show fn-14.2 ✓ Per-task done summaries are the handover: the next task re-anchors on recorded evidence, not on memory of a conversation.
Stop repeating the same rule in every PR review.
echo '- **G1:** Every route change regenerates the API contract.' >> .flow/criteria.md && flowctl criteria list ✓ The completion review already running on every spec judges each standing rule against the whole implementation and records met/violated/n-a in the receipt - no auditor pass, and nothing at all until the file exists.
Standing criteria →Let the tracker column drive readiness.
flowctl config set tracker.readyState "Ready for Dev" ✓ One-way projection: the tracker state sets the local ready flag on sync - nothing runs until you run a loop.
Use Jira or Linear as the maintenance factory's front door.
flowctl config set tracker.readyState "Ready for Dev" ✓ Moving a bounded item into the exact configured state is the human blessing boundary. Backlog-mode flow --auto can union tracker-only, Flow-only, and linked work without inventing readiness from priority or prose.
Tracker-driven factory intake →The skills are primitives, and the host agent can do real work before it reaches for one - browse, run code, evaluate, iterate. The most valuable workflows chain that work into a spec. The exploration is the input, the spec is the durable output. Nothing here is a special mode; it is the host doing its job, then handing the result to a flow-next skill.
Turn competitive research into a business-requirements spec.
"research how <competitor> prices their plans, then capture a spec for a tiered pricing page - business requirements, not implementation" ✓ The host does the research in the conversation; capture synthesizes it into a source-tagged spec. The findings are the input, the spec is the durable artifact - review and R-ID discipline apply from there.
Probe first, spec from what you actually found.
"run the load test against staging, then lock down a spec for the fixes the numbers point to" ✓ Whatever the host ran (a test, an experiment, a reproduction) sits in the conversation; capture reads that context, so the spec is grounded in observed results, not a guess.
Explore a few approaches, keep the winner, spec it.
"prototype these three approaches, tell me which wins and why, then capture the winner as a spec" ✓ The host runs the throwaway exploration; only the decision and its rationale land in the spec - captured with its source tags, so the 'why' survives the throwaway code.
Run the bake-off inside the spec: one task per approach, a final task to crown the winner.
"plan this with one task per candidate approach to the effect, plus a final task that compares them and keeps the winner" ✓ The inverse of prototype-then-spec: when you cannot judge an approach without building it properly (visual effects, perf strategies), make each candidate a tracked task so it gets real gates and review. The judging task depends on all of them, so the comparison lands as recorded evidence - and tearing down the losers is part of the plan, not an afterthought.
Spike to learn, throw away the code, keep the understanding.
"revert those changes and capture our discussion as a spec" ✓ You spiked something to find out how it should work, not to ship the spike. Revert the code; the conversation still holds what you learned, and capture freezes that into a spec - the durable output of a throwaway session is the plan, not the diff.
Run an eval / autoresearch loop, then let the evidence write the spec.
"evaluate the two prompt variants on our fixtures, iterate until one clearly wins, then capture a spec to adopt it" ✓ flow-next has no built-in eval engine - your host agent runs the loop. When it converges, capture turns the evidence into a plan; this is exactly how flow-next's own review-prompt work was specced (an eval that said no is on the record).
Ground the whole thing in strategy first.
"from that market research, write our STRATEGY, then prospect ideas that serve it" ✓ Strategy and prospect read each other: research → STRATEGY.md → ranked ideas grounded in it → plan. Each step is a skill; the chain is yours to assemble in a sentence.
These lean on primitives a single-agent setup does not have: worktree isolation, cross-model review by construction, durable specs you can diff, receipts that cannot be narrated around, and self-improving memory. Each one is a composition you drive - the host orchestrates existing skills; there is no --magic flag. They cost more (more agents, more models, more tokens) and earn it on the work where being confident matters more than being fast.
An N-model jury on one diff - merge only on cross-family consensus.
"review fn-14.2 with codex, then again with cursor:<a model from another family>, then cursor:<a third> - only ship if all three agree" ✓ Review backends are pluggable per task, so the host can send the same diff to three different families and require agreement. Uncorrelated blind spots become a vote, not a single reviewer's guess - perspective-diverse verification, taken to a jury.
Cross-model synthesis on one spec - fold in where the reviewers agree, judge where they don't.
"have two reviewers from other model families look over fn-14 - are they happy with the direction and what we plan to do?" ✓ A loose sentence is the whole invocation. The host dispatches both cross-family reviews, then synthesizes: an agreement matrix (both flagged these five things), each reviewer's solo points listed for your judgment, and a recommendation. Where uncorrelated families agree is the strongest pre-code signal you can buy; folding the agreed fixes into a ratified spec is a rewrite pass with its own read-back, never a silent mutation. The jury above gates a diff on consensus - this weighs consensus as signal on a spec, before any code exists.
Best-of-N implementation - three attempts, a judge keeps the winner.
"implement fn-14.3 three ways in separate worktrees (two in-host tiers and one bridged CLI), then have a fresh model score them and keep the best" ✓ Worktree isolation lets competing implementations exist at once without collision; a cross-model judge scores them against the same acceptance criteria. The spec is the fixed target, so 'best' is measured, not asserted. Costly by design - reach for it on the gnarly task, not the rename.
Reproduction-driven spec - the failing test IS acceptance criterion R1.
"write a test that reproduces #123, watch it fail, then capture a spec whose R1 is 'this test passes'" ✓ Because the work and review contracts require evidence and reviews check R-ID coverage, a spec anchored on a reproduction is not closed until the repro is green. The bug defines its own proof of fix, and flowctl done records it.
Mine your own memory - let accumulated bugs spec their own root-cause fix.
"audit the bug memory for recurring patterns, then capture a spec that eliminates the whole class, not the last instance" ✓ Every fixed bug leaves a memory entry. After enough of them, the memory is a dataset: audit surfaces the pattern, capture turns it into a root-cause spec. The factory improves via the factory - the loop compounds instead of repeating.
Graduate a repeated fix into a gate - the same correction shows up twice in .flow/memory/, or a reviewer rejects the same class of issue again.
"this is the second time we've fixed this class of issue - write the lint rule (or CI check, or CLAUDE.md rule) that makes it impossible, then run /flow-next:audit" ✓ A repeated memory entry marks a class worth automating: once the rule exists, every future run inherits the gate for free, and audit flags the now-redundant memory entry for cleanup. Memory, audit, and plain prompting - no special mode, works today.
Harness-hopping - plan on one vendor, build on another, review on a third.
"I planned this on Claude Code; implement fn-14 with a Codex host and review it from Cursor" ✓ The spec, tasks, receipts, and memory live in the repo, not in one vendor's session - so the same .flow work-order runs on Claude Code, Codex, Droid, or Cursor. Your process outlives your agent; cross-vendor review is a side effect of the artifacts being portable.
Red-team the spec before a line of code exists.
"attack fn-14's acceptance criteria as an adversary - find the ambiguities and edge cases an implementation could technically pass while being wrong - then tighten the spec" ✓ The cheapest place to catch a wrong requirement is before implementation. A dispatched adversarial pass over the R-IDs (or a plan-review with an attacker's lens) hardens the contract while it is still 50 lines of markdown, not 500 of diff.
Every recipe above ends the same way for the same reason: the guarantees live in the contracts, not in the ceremony. Execution discipline, evidence JSON at done, and the review gate are stage-independent - which is exactly what makes the menu safe to use. The doctrine behind that claim: Compose the pipeline.