The pipeline is a menu, not a rail. 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).You do not have to type a single slash command or --flag. Every flow-next skill is 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. Say what you need; reach for the exact syntax only when you want zero ambiguity or a copy-pasteable line.
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:interview fn-14 --scope=business ✓ 'focus on the business requirements' resolves to the business scope; the interview writes only the sections that scope owns and preserves the rest byte-for-byte.
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.
Small fix - skip prospect and interview, write the spec yourself.
flowctl spec create --title "Fix retry backoff" && /flow-next:plan fn-21 ✓ Plan still breaks the spec into reviewable tasks, and done still demands evidence JSON.
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.
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:interview fn-9 --scope=business ✓ Scoped interviews write into the same spec sections; the technical pass stays available later.
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 draft PR in one message.
/flow-next:plan fn-14 - then work the spec and open a draft 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 interview the new spec and plan it ✓ Capture writes the spec with mandatory read-back; interview 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: every task runs in dependency order with per-task review and evidence.
Advance the next ready spec by exactly one stage.
/flow-next:pilot --spec fn-14 ✓ Pilot is the bounded chain: one stage per tick, a terminal verdict line every time, gates identical to interactive runs.
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 ✓ Done is not a status flip - it requires evidence (commits, tests, PRs). Whatever proof your project produces belongs in that JSON.
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.
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 ✓ Pilot inserts one QA pass when all tasks are done, before the PR - findings surface into the draft PR instead of hard-blocking the loop.
Route reviewers, workers, and delegates 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.
Delegate implementation to a second CLI agent.
/flow-next:work fn-14.2 delegate:codex ✓ Opt-in and consent-gated: the delegate writes code; the host keeps git, task state, review, and judgment. Tests re-run on every delegated diff.
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.
Task-level parallelism within one spec is live in two forms: multiple sessions claiming disjoint tasks, and one session dispatching batched workers on request. Both run the standard per-task contracts.
Two sessions, one spec - each takes a task.
/flow-next:work fn-14.2 ✓ Session B runs .3 at the same time: atomic claims and assignee collision checks make simultaneous work race-safe by construction.
Parallel work from one spec →One session, batched dispatch.
/flow-next:work fn-14 - run .2 and .3 in parallel, they touch disjoint files ✓ Prompted orchestration over the same primitives: each worker gets its own contract, review, and evidence - the batch changes wall-clock, not gates.
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, contracts unchanged.
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 interactive to fully autonomous - same pipeline, same gates at every rung. The rungs below are in increasing order of independence.
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 a human-owned flag - loops consume only what you explicitly blessed.
Run the build loop on a cadence.
/loop 10m /flow-next:pilot ✓ Each tick advances one ready spec by one stage and ends with a verdict line - bounded progress, receipts every tick.
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 pilot knows the correct order" ✓ Plan each spec and wire its blockers; the backlog loop selects only specs whose dependencies are satisfied, 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 pilot work the whole backlog.
/flow-next:pilot --backlog ✓ Backlog mode widens selection, not permissions - the stage set, verdict grammar, and gates are the same as single-spec mode.
Babysit the open PRs to merge.
/loop 30m /flow-next:land ✓ Land keeps CI green within a bounded fix budget, resolves review feedback, and merges only converged, explicitly-gated PRs - evidence over narration.
Go fully autonomous, hardened.
/flow-next:ralph-init ✓ Scaffolds the repo-local Ralph harness (then scripts/ralph/ralph.sh runs the loop): fresh sessions, review gates, receipts, guardrail hooks - Ralph with a seatbelt, not an open loop.
Ralph internals →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.
Take a review to an external model, interactively.
/flow-next:export-context - export the fn-14 plan for review in an external LLM ✓ A hand-carried export for a second opinion (requires RepoPrompt); the verdict comes back through you, and the normal review gates still decide.
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.
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.
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.
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:claude-opus, then cursor:gpt-5.6-sol - 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.
Best-of-N implementation - three attempts, a judge keeps the winner.
"implement fn-14.3 three ways in separate worktrees (opus, sonnet, a codex delegate), 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 done demands evidence JSON and reviews check R-ID coverage, a spec anchored on a reproduction cannot be closed until the repro is green. The bug defines its own proof of fix - done cannot lie about 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.
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: Menu, Not a Rail.