Concepts

Spec

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.

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.

Tasks should be sized for one focused work pass. A good task has enough context to be executable, but not so much surface area that review becomes meaningless.

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.

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 technical pass
3	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 cognitive aid	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 Task plan"]
  H3 --> H4["4 Implementation evidence"]
  H4 --> H5["5 Review receipt"]
  H5 --> H6["6 PR cognitive aid"]

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 cognitive aid	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

The worker rereads the spec, task, and branch state before doing work. This counters context drift and survives compaction.

Receipt

JSON proof that a review or Ralph state transition happened. Receipts carry verdicts, confidence anchors, introduced findings, suppressed findings, and evidence.

Ralph

Repo-local autonomous loop, now deprecated. Ralph runs fresh sessions, applies plan and implementation review gates, reads receipts, and iterates until the spec ships or blocks. Existing installs keep working and the Ralph pages stay maintained; new setups get the same overnight loop from /flow-next:pilot and /flow-next:land, driven by a host loop or cron.

The spec, the task graph, review receipts, 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, and RepoPrompt-backed review flows. Flow-Next keeps platform-specific wiring thin so the workflow stays portable.