Skip to content
GitHub

Core Concepts

Spec

Section titled “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

Section titled “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].

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.

Spec & task ids

Section titled “Spec & task ids”

A spec is referenced by one of two id schemes. fn-NN is the most common form in these docs, but it is not the only form — a spec linked to a tracker is referenced by its tracker key instead.

Flow-first (the default)Tracker-first
canonical spec idfn-NN-slugwor-17-slug
canonical task idsfn-NN-slug.Mwor-17-slug.M
branchfn-NN-slugwor-17-slug
bare aliases that resolvefn-NN, fn-NN.Mwor-17, wor-17.M, and WOR-17 (the tracker display key)
how it is created/flow-next:capture, flowctl spec createflowctl spec create --tracker-first --tracker-identifier WOR-17
linking to a trackerflowctl sync set-tracker-id adds WOR-17 as a resolvable alias — the fn-NN id, branch, and tasks are unchangedalready tracker-keyed at creation

Tracker-first (--tracker-identifier WOR-17) needs an alpha-prefixed KEY-N display key: Linear WOR-17 and Jira PROJ-123 qualify, so those grabs are tracker-first. GitHub #N and GitLab <project>#<iid> are not KEY-N keys, so a GitHub or GitLab issue is grabbed flow-first (create an fn-NN spec, then flowctl sync set-tracker-id to link it). A non-standard Jira Data Center / Server key that can’t slugify into a canonical id (an underscore key like MY_PROJECT-7, or a long alphanumeric one) also links flow-first / display-only.

Both schemes resolve everywhere a spec or task id is accepted. flowctl show wor-17, /flow-next:work wor-17, /flow-next:plan wor-17, and the task form wor-17.1 all resolve, and resolution is case-insensitive — WOR-17 works the same as wor-17.

The two columns are set at creation and never converted into each other. Only a spec created with --tracker-first is canonically wor-17-slug; linking an existing fn-NN spec to a tracker keeps it fn-NN and merely adds the tracker key as an alias.

Three rules keep the two schemes from colliding:

  • Ids never change. There is no rename-on-push. When a fn-NN spec is linked to a tracker, the tracker key is added as a resolvable alias — the existing id, branch, and dependency edges are never mutated. flowctl spec set-title on a tracker-linked spec updates the title only; it does not re-slug the id.
  • The fn- prefix is reserved for the native sequential scheme. Tracker-key resolution is tried only after the fn- path misses, and native fn-N allocation counts fn-* ids only — a wor-9999 never bumps the next fn number.
  • One tracker team per repo. The bridge assumes a single team key so a bare wor-17 resolves unambiguously. Two teams both keyed WOR in the same repo is out of scope.

The tracker key only exists once a spec is linked to a tracker — see Tracker Sync. If you never connect a tracker, every spec stays fn-NN and nothing here changes.

R-ID

Section titled “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

Section titled “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

Section titled “Re-anchoring”

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

Receipt

Section titled “Receipt”

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

Ralph

Section titled “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

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