# The Pipeline

Source: https://flow-next.dev/understand/pipeline/

The canonical end-to-end walk - rough intent to merged release, every handover, every gate, and where the autonomy loops attach.

[`/flow-next:flow`](https://flow-next.dev/skills/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](https://flow-next.dev/skills/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](https://flow-next.dev/understand/pipeline/#the-autonomous-tier) attach. [How Flow chooses](https://flow-next.dev/choosing-your-route/#compare-fifteen-request-shapes) shows the fifteen request shapes and which of these stages each one reaches.

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`. See [the direct route](https://flow-next.dev/choosing-your-route/#no-plan-route) or ask [`/flow-next:flow --explain`](https://flow-next.dev/skills/flow/) to choose.

[![](https://flow-next.dev/videos/the-pipeline-poster.jpg)](https://flow-next.dev/videos/the-pipeline.mp4)

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

```mermaid
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`](https://flow-next.dev/autonomy/pilot/) and [land](https://flow-next.dev/autonomy/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.

**Hand it to Flow**

```text
/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
```

**Run it yourself**

```bash
/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
```

**Hand it to the loops**

```bash
/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](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/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](https://flow-next.dev/guides/writing-specs/).

This is where human judgment concentrates. The spec is [handover #1 and #2](https://flow-next.dev/understand/concepts/#handover-object) - 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](https://flow-next.dev/understand/why-flow-next/)). Chart sits **outside** the [`flow --auto`](https://flow-next.dev/autonomy/pilot/) build loop; attended chart decisions terminate `NEEDS_HUMAN` and never self-resolve.

## 2. Optional plan: build a task graph when useful

[`/flow-next:plan`](https://flow-next.dev/skills/plan/) researches the repo (scout subagents, optionally anchored by the [semantic code index](https://flow-next.dev/skills/map/)) 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](https://flow-next.dev/guides/tasks/) 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](https://flow-next.dev/choosing-your-route/#understand-what-changes-the-route)).

[`/flow-next:plan-review`](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/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](https://flow-next.dev/reference/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`](https://flow-next.dev/skills/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`](https://flow-next.dev/skills/resolve-pr/) handles review feedback either way. The opt-in [land](https://flow-next.dev/autonomy/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](https://flow-next.dev/skills/make-pr/#dependent-specs-chains-and-stacks); landing: [land](https://flow-next.dev/autonomy/land/#chains-and-stacks).

## The autonomous tier

Autonomy is the **same pipeline with the human moved to the edges** - judgment concentrates in the spec and the [readiness gate](https://flow-next.dev/guides/writing-specs/#the-ready-flag), and a loop executes the mechanical middle. No gate is skipped; the loops just stop waiting for you between stages.

```mermaid
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](https://flow-next.dev/autonomy/pilot/)** 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](https://flow-next.dev/autonomy/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](https://flow-next.dev/autonomy/land/#several-pull-requests).

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](https://flow-next.dev/autonomy/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`](https://flow-next.dev/skills/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](https://flow-next.dev/skills/flow/), [Chart](https://flow-next.dev/skills/chart/) (optional), [Writing Specs](https://flow-next.dev/guides/writing-specs/), [Capture](https://flow-next.dev/skills/capture/), [Refine](https://flow-next.dev/skills/refine/) |
| Plan         | [Task Graphs](https://flow-next.dev/guides/tasks/), [Plan](https://flow-next.dev/skills/plan/), [Plan Review](https://flow-next.dev/skills/plan-review/), [No-plan route](https://flow-next.dev/choosing-your-route/#no-plan-route) (optional skip)                 |
| Build        | [Work](https://flow-next.dev/skills/work/), [Concurrency](https://flow-next.dev/guides/tasks/)                                                                                                                                                                      |
| Review       | [Review Workflow](https://flow-next.dev/guides/review-workflow/), [Receipts](https://flow-next.dev/reference/receipts/)                                                                                                                                             |
| Hand over    | [Make PR](https://flow-next.dev/skills/make-pr/), [Handover Files](https://flow-next.dev/understand/concepts/#handover-object)                                                                                                                                      |
| Ship         | [Resolve PR](https://flow-next.dev/skills/resolve-pr/), [Land](https://flow-next.dev/autonomy/land/)                                                                                                                                                                |
| Autonomy     | [Going Autonomous](https://flow-next.dev/autonomy/going-autonomous/), [Flow —auto](https://flow-next.dev/autonomy/pilot/)                                                                                                                                           |
| Visual views | [Visual](https://flow-next.dev/skills/visual/)                                                                                                                                                                                                                      |