How work gets proven
Agents generate. Flow-Next proves.
Every stage of the pipeline leaves an artifact that the next stage, or a human six months later, can audit. That is one system with one bias: verification. This page names its parts and explains why it is built this way. The measured problem it answers, and the thinking it comes from, are on Why Flow-Next.
It starts inside the loop
Section titled “It starts inside the loop”The gates below are handover checkpoints - proof that changes hands between stages. But verification does not wait for a handover: it starts while the implementation agent is still typing.
Every spec carries numbered acceptance criteria (R1, R2, …), and every task declares which ones it satisfies (satisfies: [R1, R3]). That is not paperwork - it is the target the worker verifies against. Before it edits a single line, the worker runs the spec’s own commands to establish a green baseline, so “it passed” later means this change passed, not that it inherited a suite that was already broken. It fixes anything it breaks mid-implementation before continuing. And before it is allowed to claim the task done, it re-runs that exact suite itself - a fresh worker, re-anchored on the criteria, proving its own work with evidence, not asserting it in a summary.
This is the bias in its earliest form: the harness makes the implementer verify as it builds, against criteria written down before the build started. Everything below is the second line of defence.
Which commands, and how often: you decide
Section titled “Which commands, and how often: you decide”“The spec’s own commands” is a literal block in the spec (## Quick commands), authored by you or by the planning skill, and it is the one place the tiering lives. The convention the bundled scaffold ships with: per-task commands name the focused suites for the files that task touches, and the full suite runs once at the final gate before the PR. Two mechanisms stop that from becoming a whole-suite run per task - a green receipt keyed to the exact commit and the exact command string skips a re-run at unchanged HEAD, and a docs-only diff drops to lint and format only.
That is a project decision, not a framework one. Want narrower per-task runs? Author narrow commands and keep the full-suite entrypoint as the final-gate command. Want the full suite every task? List it, and it runs. Projects with strong opinions state them in their conductor instructions (CLAUDE.md / AGENTS.md), which the host agent reads.
One honest boundary: this selection is authored, never computed. Nothing infers that a change in one module should pull in a distant suite. It keeps needless full runs out of the loop; it does not pick the right tests for you - which is why the full suite before the PR, and your CI, stay in the table below.
One system, six vertebrae
Section titled “One system, six vertebrae”Each stage’s proof is a file on disk, not a sentence in a transcript:
| Stage | What must be proven | Artifact |
|---|---|---|
| In-loop implementation | A green baseline held; the change passes the spec’s own commands | captured suite output → evidence JSON |
| Implementation review | A cross-model reviewer issued SHIP | .flow/review-receipts/<branch>.json |
| Task completion | Commits, tests, and a done summary exist | evidence JSON required by flowctl done |
| Live-app QA | The running app actually behaves | qa_verdict receipt; PASS by reading source is forbidden |
| Merge | CI green, reviews converged | land’s gate tree - evidence over narration |
| Quality gates | The exact suite passed at the exact commit | green receipts keyed to commit SHA + command hash |
Two of those artifacts are worth knowing by name. The review receipt at .flow/review-receipts/<branch>.json carries the verdict, confidence anchors, introduced-versus-pre-existing finding counts, and deferrals; autonomous loops read it to decide progression, and so can you. The green receipt proves one exact command passed at one exact commit, and a reused one leaves a loud GATE_SKIPPED line rather than a silent pass. Both formats are documented in Receipts.
Two principles hold it together
Section titled “Two principles hold it together”Evidence is self-run; the verdict never is. The implementer verifies its own work mechanically - it runs the suite, checks the baseline, gathers the evidence. What it never does is grade it: the model that wrote the diff never issues its own SHIP. Reviews are cross-model by construction - a different model family reads the change blind, so the writer’s blind spots and the reviewer’s blind spots do not overlap. QA goes further: the skill is structurally forbidden from marking PASS by reading source code, because an implementer’s narration of correctness is exactly the thing that needs checking. Running the tests is evidence; declaring the work good is a judgment - and only the first is the author’s to make.
Evidence over narration. Agents narrate confidently; the pipeline is built to ignore that. flowctl done rejects completion without evidence JSON. Land merges on CI state and converged review threads, never on an agent’s summary of them. Where a claim can be a file, Flow-Next makes it a file.
That matters most where nobody is watching. On autonomous loops the spine is the safety: pilot advances on verdicts, Ralph transitions on receipts, land merges on evidence. The dial changes who is present, never what is proven.
Where to go next
Section titled “Where to go next”- Receipts - the artifact formats in detail
- The Pipeline - the end-to-end walk, every stage and gate
- Evidence-first recipes - putting the spine to work day-to-day
- Why Flow-Next - the measured problem and the lineage this system comes from