Choosing your route

Flow-Next has one pipeline and many routes through it. This page answers the question you actually have at the start: which stages does this change need? It gives you the shortcut for where you are standing, the reasoning that picks a route, six worked examples, and the cases where the answer is “don’t use Flow-Next for this”.

The Pipeline is the canonical walk; Skipping and composing stages is the doctrine that says you may deviate from it. /flow-next:guide is the live router when you would rather ask than read.

Start from where you are

Your situation	What to run
You know what to build, and it is in this conversation	`/flow-next:capture`, then plan the spec it writes
You have a conversation, not a spec	`/flow-next:capture`, which synthesizes the thread into a source-tagged spec and shows a read-back before writing
One large idea, still too unclear to capture	`/flow-next:chart`, which resolves one decision at a time until the effort is briefable
You have a target but need clarity	`/flow-next:interview`
A fully-known spec exists with no tasks yet	`/flow-next:work <spec-id> --no-plan` - the fork mints one implicit task and runs the standard pipeline; `flowctl spec set-no-plan <spec-id>` records the same choice on the spec for autonomous runs
You do not know what to build next	`/flow-next:prospect`, for ranked candidates grounded in the repo, strategy, memory, and open specs
You need product alignment first	a business interview before the technical pass
You need high confidence before merge	the full review stack
You want overnight execution	pilot and land under a host loop
You are unsure which of these applies	`/flow-next:guide`, which names whether a skip is signal-absent or taken despite unresolved risk

The common case is three commands:

/flow-next:capture
/flow-next:plan fn-1
/flow-next:work fn-1

Chart is optional discovery, never a mandatory stage. Skip it whenever intent and boundaries are already stateable, which the guide reports as signal absent:

/flow-next:chart multi-tenant billing with unknown pricing and migration risks
# ... resolve decisions until briefable ...
/flow-next:capture

Product alignment first. Splitting the interview is the best default for teams where a PO, PM, designer, or support lead owns part of the requirement:

/flow-next:interview fn-1 --scope=business
/flow-next:interview fn-1 --scope=technical --strategy --docs

High confidence before merge. Plan review checks whether the work is safe to start, implementation review checks the diff, and completion review checks the whole spec once every task is done:

/flow-next:plan-review fn-1
/flow-next:work fn-1
/flow-next:impl-review fn-1
/flow-next:spec-completion-review fn-1
/flow-next:make-pr fn-1

Overnight execution. Same pipeline, same gates, with the human moved to the edges (Going Autonomous has the full picture):

/loop 10m /flow-next:pilot     # build loop
/loop 30m /flow-next:land      # ship loop

The same thing as a command path, when you already know the shape:

Situation	Command path
Unsure which stage fits	`/flow-next:guide`
One large idea, still too unclear to capture	`/flow-next:chart` → briefing → `/flow-next:capture` → plan → work
Conversation already contains the requirement	`/flow-next:capture` → `/flow-next:plan` → `/flow-next:work`
Spec fully known, decomposition would convert no unknown	`/flow-next:work <spec-id> --no-plan` (or mark it: `flowctl spec set-no-plan <spec-id>`)
Team needs product clarification	`/flow-next:interview --scope=business`
Team needs technical clarification	`/flow-next:interview --scope=technical --strategy --docs`
Plan needs adversarial review	`/flow-next:plan-review`
Implementation needs review before PR	`/flow-next:impl-review`
Spec is done and needs final verification	`/flow-next:spec-completion-review`
PR needs reviewer-focused body	`/flow-next:make-pr`
PR review comments need resolution	`/flow-next:resolve-pr`

Read the six variants below as worked examples, not tiers to pick from a list. They illustrate what the smallest-sufficient rule produces for six common shapes of work. Your change composes its own route out of the same primitives.

Pick by risk and unknowns

Size and complexity correlate with ceremony, but neither is the criterion. The question each stage answers is: what don’t we know yet, and what does it cost to be wrong?

A five-line change to auth handling deserves more ceremony than a five-hundred-line refactor of well-understood code. Every stage in the pipeline exists either to convert an unknown into a known - interview burns down requirement unknowns, plan-review burns down design risk, QA burns down runtime-behavior risk - or to bound the cost of being wrong, which is what the gates, receipts, and reviews of the verification spine do. A stage with no unknown left to convert and no risk left to bound is ceremony, and ceremony is what the smallest-sufficient rule tells you to drop.

Three questions pick the route:

What’s unknown? Requirements unclear → capture + interview. Design contested → plan-review. Runtime behavior unproven → QA. Nothing unknown → straight to work.
What breaks if we’re wrong? High blast radius - auth, data, money, a public API - justifies review stages even on a tiny diff. Low blast radius on a large diff may need nothing beyond the standard review contract.
Who else needs the record? A team consuming handover files, a tracker audience, or an autonomous loop that must re-anchor from files all pull toward the fuller spec surface. Solo, present, at the keyboard pulls lean.

Before the pipeline: discovery is upstream, and often already done

/flow-next:prospect (ranked candidate ideas) and /flow-next:chart (decision-map discovery for one oversized, unclear idea) sit upstream of every variant - they are not stages of any of them. In most organizations their work has already happened under another name: a roadmap, a product brief, a groomed backlog item is prospect/chart output. Reach for them only when no shaped intent exists yet - when you cannot state the outcome in a sentence.

The pipeline proper starts where shaped intent exists: at capture (turn the intent into a spec) or directly at plan (when the intent is already sharp enough to decompose).

flowchart LR
  subgraph DISCOVERY["Upstream discovery - often external"]
    direction LR
    P["/flow-next:prospect"] -.-> Ch["/flow-next:chart"]
  end
  DISCOVERY -.->|"only when no shaped\nintent exists yet"| Entry["Shaped intent\n(brief, ticket, roadmap item,\nconversation, prototype)"]
  Entry --> Pipeline["The pipeline proper\ncapture or plan onward"]

The variants

Variant	Driving signal	Route
Epic	Many requirement unknowns, high blast radius, multi-task scope	capture → interview → plan → plan-review → work → qa → make-pr → land
Feature, requirements known	Design risk remains; requirements already clear	plan → plan-review → work → make-pr
No-plan route	Spec exists and is fully known; decomposition would convert no unknown	work `--no-plan`, or the spec-carried `no_plan` field (mints one implicit task)
Small task	Low risk, one implementation context, no real unknowns	plan → work (or `work "idea text"`)
Bug or defect	The unknown is the cause; the risk is regression	work + regression test as the R-ID
Docs or chore	Near-zero risk, fully known	direct change → triage-skip receipt → PR

Epic

Signal: a large intent with many requirement unknowns and real blast radius - the kind of work several people will touch and an autonomous loop may finish.

flowchart LR
  E([Epic intent]) --> C["/flow-next:capture\nthe whole epic"] --> I["/flow-next:interview\nsharpen what's soft"] --> P["/flow-next:plan"] --> PR["/flow-next:plan-review"] --> W["/flow-next:work"] --> Q["/flow-next:qa"] --> M["/flow-next:make-pr"] --> L["land"]

The pattern that works in practice: capture the entire epic, then let the machinery scope it. Capture proposes whether the input is one spec or a dependency-sorted set, and source-tags every criterion [user], [paraphrase], or [inferred]. Then interview sharpens exactly what is soft - “interview me on everything [inferred]” burns down the lines the agent guessed instead of re-litigating the whole spec. Plan decomposes into a context-fit task graph, plan-review burns down design risk before any code exists, work executes in fresh re-anchored workers, QA drives the live app when there is one, and land babysits the PRs to merged.

Every stage earns its place here because every stage has an unknown to convert or a risk to bound. This is the route The Pipeline walks in full.

Feature, requirements known

Signal: requirements are already clear - a good brief or ticket exists, or the team already argued this out - but design risk remains.

flowchart LR
  B([Brief / ticket]) --> P["/flow-next:plan"] --> PR["/flow-next:plan-review"] --> W["/flow-next:work"] --> M["/flow-next:make-pr"]
  C["capture / interview"] -.->|"unknown already\nconverted - skipped"| P

Capture and interview are skipped because their unknown is already converted: the requirements exist. Plan turns the brief into R-IDs and tasks; plan-review stays because the design is where the remaining risk lives. What still holds: R-IDs, gates, review, receipts - the full evidence chain from plan onward.

No-plan route

Signal: a spec already exists and is fully known - the acceptance criteria are clear, the work fits one implementation context, and decomposing it into tasks would convert no unknown.

flowchart LR
  S([Zero-task spec]) --> F{explicit fork} -->|work directly| M["mint one implicit task"] --> W["/flow-next:work"]
  F -->|plan first| P["/flow-next:plan"]

/flow-next:work fn-N --no-plan   # pre-answer the fork ("skip planning" in prose works too)
/flow-next:work fn-N             # or take the fork's interactive ask
flowctl spec set-no-plan fn-N    # or record the choice on the spec — pilot and work read it; refused once tasks exist

/flow-next:work on a zero-task spec forks explicitly: an interactive ask offers plan-first vs work-directly with a recommendation judged from that spec’s size, independent surfaces, and blast radius - its reason stated, no static default. The direct route mints exactly one minimal implicit task (“implement this spec”, satisfying every R-ID, its review contract pointed at the parent spec) and runs the standard pipeline from there. What still holds: receipts, per-task review, done evidence, and the single-task completion-review skip - the fork drops plan and its automatic plan-review, nothing else. Autonomous loops keep planning unless a human recorded the choice: a zero-task spec under autonomy stops with a typed report unless it carries no_plan: true — set at capture time (/flow-next:capture … --no-plan) or via flowctl spec set-no-plan fn-N (refused once the spec has tasks; clear-no-plan undoes it) — and pilot classifies a ready marked spec straight to this route. The minted task runs on work’s wave route (one lane has nothing for rolling admission to schedule). No autonomous path ever sets the field.

Small task

Signal: low risk, fits one implementation context, nothing genuinely unknown.

flowchart LR
  T([One-liner]) --> P["/flow-next:plan"] --> W["/flow-next:work"]

Tiny fix? Plan + work, nothing else.

/flow-next:plan "rename the config key" && /flow-next:work fn-N

Fewer stages, same contracts: done still demands evidence JSON, the green receipt still gates completion.

All skip recipes →

Or skip the explicit plan call entirely: /flow-next:work "rename the config key" accepts idea text and mints the minimal spec + task itself, and /flow-next:work fn-N.M runs a single task of an existing spec without looping onward. Spec-less is a UX affordance, not a data model - a spec always exists underneath, which is exactly why the contracts still hold on the fastest route.

Bug or defect

Signal: the unknown is not the requirements - it’s the cause. The risk is regression.

flowchart LR
  R([Bug report]) --> Repro["Reproduce as a\nfailing test"] --> W["/flow-next:work"] --> Rev["/flow-next:impl-review"]
  I["interview"] -.->|"wrong instrument\nfor a defect"| Repro

The sharpening tool for a defect is reproduction, not conversation - an interview is usually the wrong instrument here. Reproduce the bug as a failing test and make that test the R-ID: the requirement is “this no longer happens, provably.” Enter with /flow-next:work "fix: <report>" for a direct fix, or capture when the diagnosis conversation itself carries decisions worth locking down - a root-cause discussion that ruled out three approaches is spec material. What still holds: the regression test, review, receipts. The deeper pattern - let something real answer the question, then capture the answer - is Explore first, then capture.

Docs or chore

Signal: near-zero risk, fully known - lockfile bumps, docs-only edits, release chores, regenerated files.

flowchart LR
  D([Direct change]) --> TS["flowctl triage-skip\ndeterministic verdict"] --> PR([PR])

The change is made directly; flowctl triage-skip --base <ref> deterministically verdicts qualifying diffs (docs-only, lockfile-only, release-chore, generated-only) and writes a receipt with mode: triage_skip. That receipt is the whole point: the review pass is skipped, and the skip is recorded, never silent.

Do not use Flow-Next for

One-line edits where no durable context matters.
Throwaway prototypes that will not be reviewed or maintained.
Product decisions the agent should not make.
Work where nobody will read the spec or receipts.

When in doubt, start with a small spec. Flow-Next adds the most value when ambiguity, coordination, or review cost would otherwise dominate the work.

What a skipped stage still owes you

Skipping a stage never skips the evidence, consent, or review contract that stage would have provided. The contract is satisfied by a cheaper mechanism, or the skip is recorded as a deliberate decision:

Evidence - flowctl done requires evidence JSON (commits, test commands) on every variant. There is no route where a task closes on narration.
Gates and receipts - green receipts, review receipts, and QA verdict receipts gate the same transitions regardless of how much ceremony preceded them.
Recorded skips - every orchestrated stage records ran, skipped(reason), or failed(reason) in the receipts it already writes; read it back with flowctl usage --stages <spec-id>. A stage you deliberately left off is an explicit entry with your reason attached, not a silent absence.
Review - the review path scales with the risk (a cross-model backend, an in-host pass, or a triage-skip receipt), but some review artifact exists on every route. The dial from a cross-model backend down to host or none, and what each setting keeps running, is priced in What each layer costs.

That set of gates, receipts, evidence, and review is how work gets proven. The variants differ in which unknowns they pay to convert; none of them touches it.

Since 4.4.0 the capture and plan closers apply this page’s rule at the decision point: each prints one advisory Recommended next: line judged against the risk-and-unknowns selector, right where the route is chosen. The menu below it stays a menu.

Where to go next

Skipping and composing stages - the doctrine these variants instantiate, and what holds on every route.
Guide - /flow-next:guide, the live router: one situation in, the smallest sufficient route out.
What each layer costs - the adjacent axis: which layers to switch on at all, priced.
Cookbook: skip & lighten - copy-paste recipes for the lightweight routes.
The Pipeline - the full walk the epic variant runs.
Features - alongside the routes rather than in them: a committed user-POV map QA reads for navigation, kept current on your own cadence.