The Pipeline

Everything in Flow-Next is one pipeline: rough intent hardens into a durable spec (optionally via chart when the idea is still too unclear to capture), the spec breaks into a context-fit task graph, fresh re-anchored workers implement the graph, adversarial reviews gate every handover, and the result ships as a PR built for human review - with receipts. This page is the canonical walk: every stage, the artifact it hands to the next stage, and where the autonomy loops and the optional render lenses attach.

Chart is an optional pre-capture discovery route, not a newly mandatory stage. Clear ideas go straight to capture; oversized unclear ones resolve decisions first and hand a briefing package to capture. Unsure which path fits? /flow-next:guide routes using the smallest-sufficient matrix.

This is the fullest route - the one an epic with many unknowns and real blast radius earns. Smaller shapes of work run shorter routes through the same contracts: Pipeline Variations shows six worked examples, selected by risk and knowns/unknowns rather than size.

The pipeline in 40 seconds - every stage below, in motion, with the two optional routes drawn dashed.

flowchart TD
  subgraph SHAPE["Shape - human judgment up front"]
    Intent["Rough intent"] --> Guide{"Clear enough\nto capture?"}
    Guide -->|yes| Capture["/flow-next:capture or interview"]
    Guide -->|no - 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"]
  end
 subgraph BUILD["Build - the mechanical middle"]
    Plan["/flow-next:plan\ncontext-fit task graph"] --> PlanReview["/flow-next:plan-review\ncross-model gate"]
    PlanReview --> Work["/flow-next:work\nfresh re-anchored workers"]
    Work --> ImplReview["/flow-next:impl-review\nloops until SHIP"]
    ImplReview --> Completion["/flow-next:spec-completion-review"]
    Completion --> QA["/flow-next:qa\noptional live-app pass\n(pipeline.qa, default off)"]
    QA -.-> MakePR["/flow-next:make-pr\nPR-as-cognitive-aid"]
    Completion -.->|gate off| MakePR
  end
  subgraph SHIP["Ship"]
    PR["Draft PR + receipts"] --> Resolve["/flow-next:resolve-pr"]
    Resolve --> Merge["Gated merge"]
    Merge --> Close["Spec close + release"]
  end
  Spec --> Plan
  MakePR --> PR

The stages below run interactively by slash command, or hands-free - pilot drives the build segment, land drives the ship segment, and the quality gates fire identically either way.

Run it yourself

/flow-next:plan fn-52          # spec → context-fit task graph
/flow-next:plan-review fn-52   # cross-model gate before any code
/flow-next:work fn-52          # fresh re-anchored workers
/flow-next:impl-review fn-52   # loops until SHIP
/flow-next:make-pr fn-52       # PR-as-cognitive-aid

Hand it to the loops

/loop 10m /flow-next:pilot # build loop - one stage per tick
/loop 30m /flow-next:land # ship loop - CI, reviews, gated merge

An optional live-app QA stage sits between completion review and make-pr - off by default, enabled with flowctl config set pipeline.qa on. 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, and tagging every line [user], [paraphrase], or [inferred]). /flow-next:interview is the sharpening tool that follows: it deepens an existing spec in two passes - a business pass (what should exist and why) and a technical pass (how it must fit this repo) - and the capture tags make it targetable (“interview me on everything [inferred]”). Capture marks the guesses; interview 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 pilot build loop; attended chart decisions terminate NEEDS_HUMAN rather than self-resolving.

2. Plan: spec becomes a context-fit task graph

/flow-next:plan researches the repo (scout subagents, optionally anchored by the feature 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. Large work becomes a graph that fits the context window on purpose.

/flow-next:plan-review is the first adversarial gate: a second model reviews the spec and its task breakdown - architecture, coverage, ordering - before any code is written.

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

/flow-next:work 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, until SHIP

Two gates, both cross-model:

• /flow-next:impl-review reviews each implementation against the spec and loops - fix, re-review - until the verdict is 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 renders the PR-as-cognitive-aid: TL;DR, the R-ID coverage table, critical changes, decision context, a How-to-review trust frame (what the pipeline already verified vs what needs human judgment) and a risk-bucketed Review plan (Must review ≤~30% / Spot-check / Safe to skim, with the skip reasons named) - synthesized from flow state and the diff itself. The reviewer gets focus signal and skip confidence instead of a 10K-line archaeology dig. Autonomous runs always open it as a draft.

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: per tick it keeps CI green (bounded fix budget), waits out a reviewer patience window, converges review threads, and - only after every gate passes - merges explicitly, closes the spec, and follows your project’s own release process. It is the one place in Flow-Next licensed to merge.

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["pilot - build loop\nplan → plan-review → work → [opt-in qa] → make-pr"]
  PilotLoop --> Draft["Draft PR"]
 Draft --> LandLoop["land - ship loop\nCI → resolve → gated merge → release"]
  LandLoop --> Merged["Merged + released"]

• Pilot ticks the build stages one at a time, driven by your host’s /loop or /goal, ending each tick with a PILOT_VERDICT line.
• Land wakes on a cadence, babysits the PRs the build loop authored, and ends each tick with a LAND_VERDICT line.
• Ralph is the hardened harness for the work segment - fresh session per iteration, hook-enforced guardrails, receipts on disk - for runs that outlast a session.

Run pilot and land concurrently in separate clones and they form the full assembly line: drag an issue to your ready state and come back to a merged release. The topology, the safety model, and how to choose a loop: Going Autonomous.

Render lenses at the human touchpoints

The pipeline has three human touchpoints - spec review, plan review, diff review - and the opt-in HTML artifact mode (2.0.0+) gives each one a render lens: a self-contained HTML page regenerated from the markdown source of truth, never the record itself.

Touchpoint	Stage	Lens
Spec review	after capture/interview	Spec lens, spec-only view - thesis, acceptance criteria, boundaries, decision context
Plan review	after plan	Same lens, regenerated with the plan layer - task dependency DAG, R-ID → task coverage matrix
Diff review	at make-pr	PR lens, a read-only review instrument - churn map, R-ID evidence table, where-to-look checklist

The spec lens optionally opens a Lavish annotation session where feedback maps back to spec edits; the PR lens never does, and autonomous loops generate lenses but never poll for a human. Mode off (the default) means none of this exists: zero steps, zero token cost.

Where to go deeper

Stage	Pages
Shape	Guide, Chart (optional), Writing Specs, Capture, Interview
Plan	Task Graphs, Plan, Plan Review
Build	Work, Concurrency
Review	Review Workflow, Receipts
Hand over	Make PR, Handover Files
Ship	Resolve PR, Land
Autonomy	Going Autonomous, Pilot, Ralph
Lenses	Visual Aids - specs, Visual Aids - review