The Pipeline

Everything in Flow-Next is one pipeline: rough intent hardens into a durable spec, 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.

The pipeline in 30 seconds — every stage below, in motion.

flowchart TD
  subgraph SHAPE["Shape — human judgment up front"]
    Intent["Rough intent"] --> Capture["/flow-next:capture or interview"]
    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 --> MakePR["/flow-next:make-pr\nPR-as-cognitive-aid"]
  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.

1. Shape — rough intent becomes a spec

/flow-next:capture turns a conversation into a spec; /flow-next:interview deepens it in two passes — a business pass (what should exist and why) and a technical pass (how it must fit this repo). 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).

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.

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, and a where-to-look reading path — synthesized from flow state and the diff itself. The reviewer gets focus signal instead of a 10K-line archaeology dig. Autonomous runs always open it as a draft.

6. Ship — gated, never blind

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 → 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	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