Core 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 are fn-N.M, declare dependencies, and may declare satisfies: [R1, R3].

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: spec, plan, implementation evidence, review receipt, PR body. Flow-Next names six handovers from idea to merge.

flowchart LR
  H1["Business spec"] --> H2["Technical spec"]
  H2 --> H3["Implementation plan"]
  H3 --> H4["Working implementation"]
  H4 --> H5["Review receipt"]
  H5 --> H6["PR cognitive aid"]

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. Ralph runs fresh sessions, applies plan and implementation review gates, reads receipts, and iterates until the spec ships or blocks.

Ralph is an added automation harness, not the core Flow-Next idea. The core is the spec, task graph, review receipts, and handover discipline. Use Ralph only when those artifacts are strong enough that autonomous execution can be bounded.

Harness

A host environment that can run Flow-Next skills and agent work: Claude Code, OpenAI Codex, Factory Droid, and RepoPrompt-backed review flows. Flow-Next keeps platform-specific wiring thin so the workflow stays portable.