The Pipeline

/flow-next:flow reads what you have and picks the route. The stages on this page are what it routes to. Rough intent hardens into a durable spec (through chart first when the idea is still too unclear to capture), work implements a ready spec directly or through a task graph, configured reviews gate the handovers, and the result is a PR built for human review, with receipts. A tiny, local, low-risk change skips the spec pipeline: it is changed directly, checked, and handed back. This page is the reference for every stage, the artifact it hands to the next stage, and where the autonomy loops attach. How Flow chooses shows the fifteen request shapes and which of these stages each one reaches.

A recorded walkthrough of the decomposed route. The current direct-work recommendation and both routes are shown below.

flowchart TD
  subgraph SHAPE["Shape - human judgment up front"]
    Intent["Whatever you have\nidea, ticket, bug report, spec id"] --> Route["/flow-next:flow\nroute from the shared matrix"]
    Route -->|"clear intent"| Capture["/flow-next:capture or refine"]
    Route -->|"oversized + unclear"| Chart["/flow-next:chart\noptional decision map"]
    Chart --> Brief["Briefing package"]
    Brief --> Capture
    Capture --> Spec["Spec with R-IDs\n.flow/specs/<id>.md"]
    Spec --> Fork{"Positive plan signal?\nasked, separate owners,\nstaged PRs"}
  end
  subgraph BUILD["Build - the mechanical middle"]
    Plan["/flow-next:plan\ncontext-fit task graph"] --> PlanReview["/flow-next:plan-review\nconfigured review (review.backend)"]
    PlanReview -->|"tasks"| Work["/flow-next:work\ninline for one task,\nfresh workers for several"]
    PlanReview -->|"no tasks"| NoPlan
    NoPlan["Direct route\nwork --no-plan\none full-spec execution owner"] --> Work
    Work --> ImplReview["/flow-next:impl-review\nconfigured review (review.backend)"]
    Work -.->|"skipped(config: review=none),\na risk skip, or a qualifying\ntriage-skip receipt"| Completion
    ImplReview --> Completion["/flow-next:spec-completion-review\n(skipped on the single-task route)"]
    Completion -.->|"pipeline.qa on, or auto with\nUI criteria + drivable surface\n+ startable target"| QA["/flow-next:qa\nlive-app pass"]
    QA -.-> MakePR["/flow-next:make-pr\nPR briefing"]
    Completion -->|"qa off, or auto with\nany of the three absent:\nskipped(reason)"| MakePR
  end
  subgraph SHIP["Ship - after your decision"]
    PR(["PR + receipts\nFlow stops here"]) --> Resolve["later flow run: offers land\n(unattended: DEFERRED_TO_LAND)"]
    Resolve -.->|"you merge, or\nauthorize land"| Land["land - separate driver\none named PR, gated merge"]
  end
  Fork -->|"no, and no design risk named\nor review requested - the default"| NoPlan
  Fork -->|"no, but design risk named\nor review requested"| PlanReview
  Fork -->|"yes"| Plan
  MakePR --> PR

Flow runs the routed stages by name. At the keyboard it stops with the change committed on a local branch and runs make-pr when you say “open the PR”; flow --auto stops when the PR exists; every stage below is also a skill you can invoke yourself, and flow --auto and land drive the build and ship segments unattended. Every path runs the same stage contracts, and flow --auto classifies each hop from the same routing references attended flow reads, so pipeline.qa=auto selects live QA by the same rule under both.

/flow-next:flow fn-52                # reads the spec's state, records the route, runs work with review, stops with the change committed
/flow-next:flow --explain fn-52      # the route, its signal, and the safe skip; writes nothing
/flow-next:flow fn-52                # on the open PR: offers landing once; with your consent hands the PR to land

/flow-next:plan-review fn-52   # optional spec/design review; zero tasks supported
/flow-next:work fn-52 --no-plan # ready cohesive spec + capable agent
/flow-next:impl-review fn-52   # one review, one fix pass, one scoped re-review
/flow-next:make-pr fn-52       # PR briefing

/flow-next:flow --auto                    # build loop - one ready spec to its PR, hop after hop
/loop 30m /flow-next:flow --auto --tick   # one hop per interval, for hosts without stable long sessions
/loop 15m /flow-next:land 123             # ship loop - one named PR: threads, CI, authorized merge

An optional live-app QA stage sits between completion review and make-pr - off by default. flowctl config set pipeline.qa on runs it on every spec under attended flow and flow --auto; auto runs it, under either driver, only when the spec’s acceptance describes UI behaviour on a drivable surface and a target can be started, and otherwise records skipped(config: pipeline.qa=auto: <reason>) on the stage line. Both drivers read that rule from the same gate-selection reference. It drives the running app like a real user over the complete build, one pass at the all-tasks-done juncture. It augments, never replaces CI/staging/manual QA: the cheap first live pass that catches obvious runtime breakage before a human opens the PR, surfacing its findings (it never hard-blocks the loop - merge stays the human’s + land’s decision).

1. Shape: rough intent becomes a spec

When one idea is still too big and too unclear for a single capture session, optional /flow-next:chart resolves one decision at a time (research, probe, eval, prototype, interview, task) until the effort is briefable. Chart never writes a spec; it hands a briefing package to capture. Skip it when intent and boundaries are already stateable - that is the default first-run path. In most organizations this discovery work has already happened upstream under another name - a roadmap, a product brief, a groomed backlog item is chart/prospect output - so the pipeline usually starts at capture, with shaped intent in hand.

/flow-next:capture is the intake valve. Pipe in whatever carries the intent - an idea, a briefing packet, an already-good ticket, research you just ran, a prototype, a long conversation - and it produces the initial spec (proposing whether that input is one spec or several, leaving your own words untagged and tagging what it wrote [paraphrase] or [inferred]). /flow-next:refine (interview) is the sharpening tool that follows, when a decision only a person can make is still open. It settles those decisions in one question pass that asks only what would change the build, optionally focused through a lens such as --biz (what should exist and why) or --tech (how it must fit this repo), and the capture tags make it targetable (“refine everything [inferred]”). A separate scope, --scope=research, asks nothing. Four read-only scouts resolve library versions, changed APIs, and gotchas into one ## Resolved via Research section, each bullet with its source. Capture marks the guesses; refine burns them down. The output is the spec: a single durable document at .flow/specs/<id>.md carrying goal, architecture, boundaries, decision context, and numbered acceptance criteria (R-IDs) that stay frozen once reviewed.

This is where human judgment concentrates. The spec is handover #1 and #2 - the same file at successive layers - and it replaces the standups, refinement meetings, and design chats that agent-paced delivery no longer has time for (why that matters). Chart sits outside the flow --auto build loop; attended chart decisions terminate NEEDS_HUMAN and never self-resolve.

2. Optional plan: build a task graph when useful

/flow-next:plan researches the repo (scout subagents, optionally anchored by the semantic code index) and decomposes the spec into dependency-ordered tasks, each sized for one focused worker context window and tagged with the R-IDs it satisfies. Use task graphs on a positive signal only: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs (the three signals).

/flow-next:plan-review is the first adversarial gate. A second model reviews the spec/design before code is written. Zero tasks are supported; architecture and requirements still receive review, with task coverage and ordering checked when tasks exist.

For a ready spec with no tasks, direct execution through /flow-next:work <spec-id> --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. The strong spec remains the implementation contract. One implicit execution owner covers every acceptance criterion and follows the same configured implementation review, coverage, completion policy, and evidence gates. Optional live QA stays opt-in and augments staging and manual QA; a NEEDS_WORK QA finding can accompany the PR and does not authorize merge. Record explicit consent with work --no-plan, capture with --no-plan, or flowctl spec set-no-plan fn-N. Under /flow-next:flow, capture applies the rule itself and records no_plan when it resolves to direct; user-invoked capture still needs the explicit flag. flow --auto applies the same rule unattended. For a ready spec with no tasks and no recorded route it reads plan-vs-no-plan.md, records the route with spec set-no-plan or spec clear-no-plan before creating any task, and prints why. It never infers consent from a flag.

3. Build: fresh workers, re-anchored every time

/flow-next:work implements a single-task spec inline in the conversation. With several tasks it gives each ready task a fresh worker context that re-anchors before editing. It rereads the spec, the task, git state, and repo conventions. No worker carries yesterday’s chat scrollback or a failed attempt’s residue. Independent tasks run in parallel off the dependency graph, and every task records evidence - commits, tests, a done summary - as it moves.

4. Review: adversarial, sized by risk

Two gates, each through the backend you configured in review.backend; the gate is independent only when that backend names a model family that did not write the diff. Every skip is recorded rather than silent: skipped(config: review=none), a risk skip for a small output, wording or display fix, a qualifying flowctl triage-skip receipt with mode: triage_skip, or the single-task completion-review skip (skipped(policy: single-task, per-task SHIP covers spec surface)).

/flow-next:impl-review reviews each implementation against the spec, sized by risk: three reviewers from another model family for a change that touches persisted or shared state, concurrency, security, data layout or migrations, or a multi-file feature; one otherwise; none for a small local output, wording or display fix, with the skip recorded. Attended, a NEEDS_WORK gets one fix pass and one re-review scoped to the fixes; unattended, fix and re-review repeat until SHIP. Findings are confidence-anchored and classified introduced-vs-pre-existing, so the gate measures what this change broke, not the repo’s history.
/flow-next:spec-completion-review verifies the whole spec at the end: every acceptance criterion implemented, no task-level drift hiding in the gaps.

Verdicts land as receipts in the repo - state transitions backed by artifacts, not promises.

Review receipt SHIP

.flow/review-receipts/<branch>.json

verdict: SHIP
reviewer: cross-model backend
introduced findings: 0
pre-existing: logged, not counted

Every verdict is a JSON artifact on disk: the verdict, confidence anchors, introduced-vs-pre-existing finding counts, and what was deferred or suppressed. Loops read receipts to decide progression - a stage transition is backed by a file you can cat, not a sentence in a transcript.

5. Hand over: a PR built for review

/flow-next:make-pr closes the finished spec on the branch and renders the PR briefing, written for the reviewer: why the change exists, what a user will notice, the review steps in reading order with their must-read files and requirement coverage, the blast radius, a verification checklist that ticks only what passed, tradeoffs, and open items. The agent authors one object and flowctl renders it. The reviewer gets a reading order and a count of what is safe to skip instead of a 10K-line archaeology dig. It opens ready for review unless it carries open items; an unattended run also writes its Decisions list into the body.

6. Ship: gated on evidence

Merge is a human decision by default; /flow-next:resolve-pr handles review feedback either way. The opt-in land loop automates the babysitting. You name one pull request. Per tick land resolves its review threads, makes one CI fix or one flake rerun, and - only after every gate passes and only when you authorized the merge in that session - squash-merges it. make-pr already closed the spec on the branch, so the merge carries the close to the base; releases run separately. It is the one place in Flow-Next licensed to merge.

A spec that depends on another spec ships as a chain: once the parent’s tasks are done and its branch is pushed, the dependent spec’s branch forks from the parent’s tip and its PR targets the parent’s branch, so each layer carries its own clean diff and the dependent spec never waits for the parent’s merge. On GitHub the PR is also linked into the parent’s stack. You merge from the bottom layer up, from GitHub’s stack UI or by letting land drain the chain one frontier per tick. Authoring: make-pr; landing: land.

The autonomous tier

Autonomy is the same pipeline with the human moved to the edges - judgment concentrates in the spec and the readiness gate, and a loop executes the mechanical middle. No gate is skipped; the loops just stop waiting for you between stages.

flowchart LR
 Board["Ready spec\n(flowctl spec ready / tracker board)"] --> PilotLoop["flow --auto - build loop\nwork → [qa per gate selection] → make-pr\n(plan and plan-review only on a signal)"]
  PilotLoop --> Draft["PR + Decisions list"]
 Draft --> LandLoop["land - ship loop\nresolve → CI → authorized merge"]
  LandLoop --> Merged["Merged"]

Flow —auto carries one ready spec through the build stages to a PR in one invocation, hop after hop, never asking and recording each decision it made in the PR, and ends with one PILOT_VERDICT line. --tick runs one hop per invocation for a host /loop or /goal, and replaced the /flow-next:pilot command in 6.1.0.
Land takes one pull request you name, wakes on your driver’s cadence, and ends each tick with a LAND_VERDICT line. Landing several is a loop you write.

Run flow --auto and a land loop side by side and they form the full assembly line. Drag an issue to your ready state and, with --until=merge or an authorized land loop, come back to a merged pull request. The topology, the safety model, and how to choose a loop: Going Autonomous.

Seeing a stage visually

The pipeline has three human touchpoints: spec review, plan review, and diff review. For a visual view at any of them, run /flow-next:visual on the spec, the plan, or the diff, or ask the agent for an HTML page when you want one.

Where to go deeper

Stage	Pages
Shape	Flow, Chart (optional), Writing Specs, Capture, Refine
Plan	Task Graphs, Plan, Plan Review, No-plan route (optional skip)
Build	Work, Concurrency
Review	Review Workflow, Receipts
Hand over	Make PR, Handover Files
Ship	Resolve PR, Land
Autonomy	Going Autonomous, Flow —auto
Visual views	Visual