Concepts
The central artifact. Markdown at .flow/specs/<id>.md, with metadata sidecars in the 1.x layout. A spec carries goal, architecture, boundaries, decision context, and numbered acceptance criteria.
Specs are written for both humans and agents. Humans need to see the tradeoffs and non-goals. Agents need stable acceptance criteria, constraints, and enough context to avoid inventing product decisions.
An execution unit under a spec. Tasks hang off a spec id with a .M suffix (fn-N-slug.M, or wor-17-slug.M for a tracker-linked spec), declare dependencies, and may declare satisfies: [R1, R3]. Both id schemes, and the rules that keep them from colliding, are in Spec schema.
Planned tasks should fit one focused work pass. Direct work uses one minimal execution owner covering the whole spec; the spec remains the implementation and review contract. Add a task graph when coordination or execution constraints make decomposition useful.
Numbered acceptance criterion: R1, R2, R3. R-IDs are frozen after review. Deletions leave gaps. New requirements get the next unused number.
R-IDs are the traceability spine. They appear in specs, task frontmatter, review output, PR bodies, and evidence summaries.
The stage sequence a starting state maps to, with its positive signal, its safe skip, and the skip kind (signal absent or despite unresolved risk). Routes live in the shared route matrix the Flow skill owns; flow --explain prints one without running it. For a ready spec with no tasks the route is recorded on the spec (no_plan) before any stage runs.
Conductor
Section titled “Conductor”The driver that reads a starting state, picks the route, runs the routed stage skills by name, re-evaluates after each hop, and stops at the next human decision. /flow-next:flow is the conductor. By default, attended flow ends when the PR exists and offers landing when you return to an existing PR. --until=merge authorizes the selected item upfront; otherwise it asks once before invoking land. With --auto the same conductor runs unattended: it never asks, decides from evidence, and carries one ready spec to a PR that opens ready for review, or as a draft when a human call that blocks nothing else is left as an open item. It stops only for a call only a human can make. It re-implements no stage.
Handover object
Section titled “Handover object”A reviewable artifact passed between lifecycle stages. Flow-Next names six handovers from idea to merge, each reviewable alone, verifiable against the previous artifact, and frozen once handed off.
| # | Handover | Artifact |
|---|---|---|
| 1 | Business-layer spec | .flow/specs/<id>.md |
| 2 | Full technical spec | Same spec, after refine --tech settles any open technical fork |
| 3 | Optional implementation plan | .flow/tasks/<id>.M.md |
| 4 | Working implementation | Done summary + evidence commits |
| 5 | Cross-model review | .flow/review-receipts/<branch>.json |
| 6 | PR briefing | PR body rendered by /flow-next:make-pr |
Each handover is reviewable alone, verifiable against the previous artifact, and frozen once handed off.
flowchart LR H1["1 Business spec"] --> H2["2 Technical spec"] H2 -.-> H3["3 Optional task plan"] H2 -->|direct work| H4 H3 --> H4["4 Implementation evidence"] H4 --> H5["5 Review receipt"] H5 --> H6["6 PR briefing"]
Each artifact should answer the next person’s first question without relying on the original chat.
What each reviewer asks
Section titled “What each reviewer asks”| Handover | Reviewer asks |
|---|---|
| Business-layer spec | Is this the right outcome, user, and boundary? |
| Technical spec | Can this be implemented safely in this repo? |
| Implementation plan | Are tasks complete, ordered, and reviewable? |
| Working implementation | Which acceptance criteria did this satisfy and what evidence proves it? |
| Cross-model review | Are introduced findings addressed or explicitly deferred? |
| PR briefing | Can a human review the right files in the right order? |
What belongs in handover text
Section titled “What belongs in handover text”- Concrete IDs: spec ID, task IDs, acceptance IDs, commit hashes when available.
- Decisions and alternatives.
- Evidence commands and results.
- Open questions and explicit deferrals.
- Links or paths to the next artifact.
Do not write “done” without evidence. The next actor should be able to verify the state from files in the repo.
Re-anchoring
Section titled “Re-anchoring”Before doing work the conversation (for a single task) or the worker (for each of several tasks) rereads the spec, task, and branch state. This counters context drift and survives compaction.
Receipt
Section titled “Receipt”JSON proof that a review or a state transition happened. Receipts carry verdicts, confidence anchors, introduced findings, suppressed findings, and evidence.
The repo-local autonomous loop that 7.0 removed. /flow-next:flow --auto and /flow-next:land are the one unattended mode, run once per item or driven by a host loop or cron. To keep running Ralph, pin flow-next 6.7.x; the upgrade notes list what to delete.
The strong spec, configured review, evidence, and handover discipline are the core, and they hold whether a loop drives them or you do. Start an autonomous loop only when those artifacts are strong enough to bound it.
Harness
Section titled “Harness”A host environment that can run Flow-Next skills and agent work: Claude Code, OpenAI Codex, Factory Droid, xAI Grok Build, Cursor, OpenCode, and Meta Muse Code. Flow-Next keeps platform-specific wiring thin so the workflow stays portable.