# Concepts Source: https://flow-next.dev/understand/concepts/ The vocabulary behind Flow-Next - spec, task, R-ID, route, conductor, handover object, re-anchoring, receipt, harness. ## Spec The central artifact. Markdown at `.flow/specs/.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. ## Task 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](https://flow-next.dev/reference/spec-schema/#spec-and-task-ids). 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. ## R-ID 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. ## Route 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](https://flow-next.dev/skills/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 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`](https://flow-next.dev/skills/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 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/.md` | | 2 | Full technical spec | Same spec, after `refine --tech` settles any open technical fork | | 3 | Optional implementation plan | `.flow/tasks/.M.md` | | 4 | Working implementation | Done summary + evidence commits | | 5 | Cross-model review | `.flow/review-receipts/.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. ```mermaid 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 | 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 * 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 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 JSON proof that a review or a state transition happened. Receipts carry verdicts, confidence anchors, introduced findings, suppressed findings, and evidence. ## Ralph The repo-local autonomous loop that 7.0 removed. [`/flow-next:flow --auto`](https://flow-next.dev/autonomy/pilot/) and [`/flow-next:land`](https://flow-next.dev/autonomy/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](https://flow-next.dev/releases/compatibility/#70-ralph-and-the-html-lenses-removed) 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 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.