Glossary

The canonical vocabulary for these docs. Terms are load-bearing. Skills, docs, and reviews use them in exactly these senses.

Two related things share the name. The repo-root GLOSSARY.md is deliberately much shorter - a twelve-term dictionary of the words whose synonyms cause real ambiguity for contributors and agents working on flow-next itself, each with the aliases to avoid. The GLOSSARY.md that /flow-next:setup seeds into your project (and that survives uninstall) is your project’s vocabulary, unaffected by either. This page is the full reference list for reading the docs.

Jump to a term

Ask stage / question valve · Attended and unattended · Author override · Backlog mode (pilot.autonomy) · Briefing package · Carmack-level review · Chain · Chart · Classification (prime) · completed-blocker rule · Cross-model review · D-ID · Decision log (pilot-log) · Decision record · Decisions list · Declined #<n> line · Delivery shape · dependency projection · discovery ceremony · Doctor · Driver · Fast scout tier · Feature map (code index) · Feature map (user-POV drive map) · features_anchored · Flow (attended conductor) · Frontier (chain) · Frontier (chart) · Frozen-at-handover · Global criterion (G-ID) · Goal log · Goal spec · Green receipt · Handover object · Hard gate · Implementer tier · Integration branch · Land · Layer · Long-horizon run · No-plan route · merge-base snapshot · Open item · Operability ladder · Pilot · PR briefing · Prototype before ask · provenance ledger · QA stage (pipeline.qa) · R-ID · Ralph · Re-anchoring · Reach · Ready · Receipt · Refine · Research scope · Review by risk · Reviewer tier · Routing reference · Spec · Spec-as-PR · Stack · Supersession · Task · Thinking scout tier · Tick · Tier · Tracker · tracker result class · tracker-key handle · Triage skip · Triage stage (backlog mode) · Verdict · why-scout · Worker subagent

Chart

Optional decision-map discovery for one oversized or unclear idea before capture (/flow-next:chart). Lives at .flow/charts/<id>.md + .json. Unit of work is a decision record (D-ID), not a build task. Output is a briefing package handed to capture - never a spec and never a ready flag. Never a stage of flow --auto (its stage set is plan, plan-review, work, qa, make-pr); skip when intent and boundaries are already stateable. /flow-next:flow --explain (Flow) says when it is the smallest sufficient route.

Relates to: Decision record, D-ID, Frontier, Briefing package, Supersession

Decision record

A single chart decision - question body under .flow/charts/<chart-id>/<n>.md plus a JSON sidecar. Carries type (research|probe|eval|prototype|interview|task), attendance (attended|unattended), status (open|resolved|superseded|out-of-scope), edges (blocked_by, depends_on), assets, and answer on close. Sized for one agent session (~100k tokens), same budget as a task. Attended types never self-resolve under unattended drivers (NEEDS_HUMAN).

Relates to: Chart, D-ID

D-ID

Chart-local decision identity, format <chart-id>.D<n> (e.g. fn-140.D3). Allocated sequentially from D1, append-only, never renumbered or reused - the same discipline as R-IDs. Load-bearing across the ledger, dependent records, briefing membership, and eventual spec citations. Human lists always pair title + D-ID + record link.

Relates to: Decision record, R-ID

Frontier (chart)

Open, unblocked, unclaimed decisions on a chart - the same word and shape /flow-next:work uses for the ready task frontier. flowctl chart frontier is the sole selection input for chart work mode. Empty frontier is not completion by itself; briefable requires no open decisions and no parked Open Questions.

Relates to: Chart, Decision record

Briefing package

Immutable versioned handoff from a briefable chart to capture (B-IDs: B1, B2, …). Clusters resolved decisions (default N=1; split only when genuinely disjoint), names multi-cluster decisions once as shared context, and preserves D-ID/evidence links and supersession history. Chart never writes .flow/specs/; capture authors the spec and owns criterion source tags.

Relates to: Chart, Capture

Supersession

When a later decision invalidates an earlier answer: prior answer stays immutable; ledger line is struck-through, never deleted; dependents cascade (open premise-dependents lose claims; resolved dependents get replacement D-IDs unless --keep-dependents). Wrong turns remain visible in the briefing.

Relates to: Chart, Decision record

Spec

The central artefact of flow-next: a specification at .flow/specs/<id>.md (markdown body) plus .flow/specs/<id>.json (metadata sidecar, post-1.0). Reviewable on its own; cross-model-reviewable; verifiable against prior handovers; frozen at handover. Replaces the term epic from the 0.x line.

Ready

A boolean on the spec record, set by you, (default false, toggled via flowctl spec ready / spec unready) marking a spec complete enough to hand to an agent - the entry gate autonomous loops consume. Orthogonal to status (open|done): a ready spec stays open through planning and work. Set by a person or tracker-projected (tracker.readyState pulls the configured tracker state onto the local flag, one-way), never agent-inferred; a goal run also readies the child specs it mints for the goal you named. Opt-in and invisible until adopted: the flag is written lazily, non-adopters see no badge, prompts, or warnings anywhere. Its sibling boolean is no_plan (see No-plan route), with the same lazy, human-owned contract, recording consent to execute a ready zero-task spec directly through Flow-Next work.

Goal spec

An ordinary spec that flow --goal works toward: its acceptance criteria are the bar, its Boundaries hold what no child spec may change, and it stays unready because naming it on --goal is the consent. A goal run measures the bar, mints the next child spec, builds it through flow --auto, and repeats until GOAL_MET or a person is needed. Not a host’s /goal command, which is a driver that can re-invoke a goal run.

Goal log

The ## Goal log section a goal run appends to its goal spec after acting: dated entries for the source, each measurement with its commit, each child minted and why, each child’s outcome, and each open question for the person. It is the run’s only memory across sessions.

Integration branch

The goal/<branch> branch a goal run’s children land on by default, named from the goal spec’s branch. The run merges the default branch into it before each measurement, measures on it, and at the end opens one final pull request from it to the default branch. A sentence in the goal spec opts out, and children then land on the default branch. See Goal mode.

No-plan route

Direct execution through /flow-next:work <spec-id> --no-plan is the default for a ready spec with no tasks and no recorded route. Plan is chosen only on a positive signal: you asked for a plan, separate human owners will implement, or delivery is staged across several PRs. Risk, size, and file count never trigger plan on their own. Design risk routes to plan-review, which reviews a spec with zero tasks; unresolved product or authority choices route to refine. The strong spec remains the implementation contract. One implicit execution owner covers every acceptance criterion and follows the same configured implementation review, coverage, completion policy, and evidence gates. Optional live QA stays opt-in and augments staging and manual QA; a NEEDS_WORK QA finding can accompany the PR and does not authorize merge. Explicit --no-plan, stated intent to work directly, or the spec-level no_plan field selects the route; under flow and flow --auto the rule is applied and recorded on the spec before anything runs (the unattended run records it with spec set-no-plan or clear-no-plan before any task is created). Existing planned tasks keep their route. The rule itself is one file in the routing reference.

Task

An execution unit under a spec, sized to fit one /flow-next:work iteration (~100k tokens fresh context). Tasks declare dependencies (requires:) and may declare which spec acceptance criteria they advance (satisfies: [R1, R3]). A spec with one task is built inline in the conversation; several tasks, a named implementer, a host review mode, or a full context send a task to a worker subagent with re-anchored context.

R-ID

A numbered acceptance criterion in a spec, format **R1:** ..., **R2:** .... Renumber-forbidden after the first review cycle: deletions leave gaps, new criteria take the next unused number. R-IDs are the load-bearing identity of a requirement across the spec, the tasks that satisfy it, the commits that reference it, and the PR body’s coverage lines.

Global criterion (G-ID)

A numbered standing, project-wide acceptance criterion in the user-owned .flow/criteria.md, format - **G1:** ... - the R-ID grammar with a G prefix, lifted from one spec to the whole project. Parsed and validated by flowctl criteria list (unique ids, non-empty prose, gaps allowed); judged agentically by the existing spec completion review, which records per-criterion compliance (met / violated / n/a) in the ordinary review receipt’s additive criteria: [{id, status, note?}] array. No separate auditor, no rule engine. The spec is the unit of compliance; G-IDs are stable identity like R-IDs and are never renumbered. Absence of the file is a silent no-op everywhere. Criteria-less repos pay zero prompt content. Like structured findings, the compliance record is a portable receipt contract that downstream consumers can render without importing Flow-Next internals. See Standing Criteria.

Relates to: R-ID, Receipt

Handover object

A named, reviewable artefact that carries context across a step in the agentic SDLC. flow-next defines six handover states: the spec at business-layer completion (#1) and at full completion (#2) - both the same .flow/specs/<spec-id>.md file at successive layers, NOT two separate specs - then the implementation plan (#3), the working implementation (#4), the cross-model code review (#5), and the PR briefing (#6). Each is reviewable on its own, cross-model-reviewed where the risk calls for it, and frozen at handover. The chain of handovers replaces the standups / refinement / design-review touchpoints that pre-agentic Agile relied on.

Re-anchoring

Re-reading the spec, the task, and git log since branch base before each task starts. Counters context drift in long-running agent sessions per Anthropic guidance. Worker subagents re-anchor on every iteration via a single flowctl anchor <task-id> call - one deterministic bundle whose sections are the verbatim output of the commands they name (task + spec records and bodies, short git state, the memory text index, the glossary entries the task names, dependency done-summaries; about 60 KB per task since 6.1.0); the bundle is a floor, not a ceiling. /flow-next:work re-anchors every loop turn. Session scope has its own verb: a cold session (new chat, a flow --auto run start, benchmark checkpoint) runs flowctl brief first - one deterministic, ~2k-token-bounded workspace picture (open specs, actionable tasks with claim state, recent completions, memory index) with explicit truncation markers and --full/--json forms; unlike anchor it is budgeted, not verbatim.

Tier

What kind of model a job wants: reviewer, implementer, fast scout, thinking scout, or unset (the session model). A tier binds a model to a stage’s execution, never to which stages run - which stages run is decided by what you invoked. The four names are a user-facing interface defined in exactly one place, Orchestration → Tiers; an unrecognized name is treated as unset with one advisory. Written as <tier>: <model> lines (optionally at <effort>) in your own CLAUDE.md / AGENTS.md routing block.

Avoid: pin, model tier, capability level, role map

Relates to: Reach, Cross-model review

Reach

How the active harness obtains a model for a tier: the in-session model, an in-host subagent, shelling out to another CLI, or not available. Documented once per harness and never inside a skill - a skill asks for a tier and names no spawn primitive, CLI flag, or vendor path. An undetectable harness takes the generic row and says so. Every missing mechanism degrades to the session model, stated once; nothing fails closed on routing.

Avoid: dispatch mechanism, availability, probe

Relates to: Tier

Reviewer tier

The tier for anything grading work someone else produced. The only tier carrying a family rule: a reviewer from the writer’s own family is not an independent verdict. The rule is advice, not enforcement - the receipt records what ran, and nothing fails closed on it except the host backend, which refuses to review without a cross-family pin.

Avoid: grader, review model, critic

Relates to: Tier, Cross-model review

Implementer tier

The tier for work handed to another harness - keep judgment on the session model and route implementation to a suitable model when useful. Absent, the session model implements. Replaced the packaged delegate:codex mode in 4.0.0: there is no layer to enable, only a line to write and a bridge recipe to run.

Avoid: bridged worker, executor, delegate

Relates to: Tier, Task

Fast scout tier

The tier for mechanical inventory scanning, where the cheapest model is the correct one.

Avoid: cheap tier, scanner model, fast model, low tier

Relates to: Tier

Thinking scout tier

The tier for analysis that degrades badly on a fast model - requirement analysis and pattern judgment, not scans.

Avoid: judgment tier, smart scout, intelligent scout, deep scout

Relates to: Tier

Cross-model review

A different model reviews the artefact produced by the first model. Applied by risk. Backends: Codex CLI (codex), GitHub Copilot CLI (copilot), Cursor cursor-agent CLI (cursor), Claude Code CLI (claude), host-native fresh-context subagent (host). The disagreement surface between writing model and reviewing model is where the gaps live.

Review by risk

The rule that decides whether a change is reviewed, when a review backend is configured: by risk, not by size. Every change that touches persisted or shared state, concurrency, security, data layout or migrations, and every multi-file feature, is reviewed, with three concurrent reviewers on the first round on every backend. Other changes get one reviewer. A small local fix to output, wording or display is not reviewed; the run records the skip and its reason. Full rule: Review workflow.

Relates to: Cross-model review, Attended and unattended

Attended and unattended

The two ways a run is driven. Attended: a person is in the session, so the run asks only what only that person can answer, takes sensible defaults (a branch, a readiness flag) with one line instead of a question, hands the result back first, reviews in the background, and does one scoped re-review of the fixes. Unattended (flow --auto, with or without --until=merge): nobody is waiting, so the run never asks, decides from evidence, loops fix and re-review until SHIP, and stops only for a call only a human can make or an irreversible action.

Relates to: Driver, Decisions list, Author override, Open item

Declined #<n> line

One line per review finding the author declined (hardening, scope creep, or a problem that existed before the change), written as Declined #<n>: <reason> in the fix commit message. The re-review reads these lines, so the reviewer sees what was declined and why.

Relates to: Author override, Review by risk

Author override

How an unattended review loop may end without SHIP: when the reviewer keeps only findings the author declined, all below Major, the author ends the loop and records each disagreement, with both sides’ reasons, in the Decisions list and the pull request. A finding that shows a stated requirement broken is never overridden, and the verdict stays the reviewer’s.

Relates to: Declined #<n> line, Decisions list, Verdict

Decisions list

The list an unattended run keeps in its final report and the pull request body: each default it chose, finding it declined, and review it skipped on your behalf, with the evidence behind it.

Relates to: Attended and unattended, Author override

Open item

A human call that blocks nothing else in the run, such as refreshing a frozen fixture or a requirement only CI can prove. An unattended run writes it into the pull request as an open item and finishes the rest instead of stopping; a pull request with open items opens as a draft, and one without opens ready for review.

Relates to: Attended and unattended, PR briefing

Feature map (code index)

The .clawpatch/features/*.json index produced by clawpatch map and consumed by flow-next scouts via flowctl repo-map. Semantic feature slices across ~20 languages/frameworks (Zod-validated upstream, schemaVersion: 1). Wrapped by the opt-in /flow-next:map skill; flow-next core (flowctl) never imports or requires clawpatch - when .clawpatch/ is absent, scouts gracefully fall back to grep/glob. Local-per-developer and git-ignored by default.

Relates to: Feature map (user-POV drive map), features_anchored

Feature map (user-POV drive map)

The committed directory at .flow/features/ recording, from the user’s point of view, what each user-facing feature is, how a user reaches it, how an agent drives it, and which traps waste a verification run. An index carrying the operating rules plus one file per feature, each with a **Surface:** identifier and exactly four sections (Sub-features / How to get to it (user POV) / Driving it / Gotchas). Seeded and maintained by /flow-next:features, and updated by /flow-next:work for the routes its own change altered; read by bug intake and by every stage that drives the running app, including /flow-next:qa and Drive, on an existence check, for navigation only. Readers file a feature-map-drift note when a route no longer matches, and flowctl features status reports the map due a maintain pass from those notes and each file’s **Last proven:** age (Keep the feature map current). The spec still supplies what to prove, and live captured evidence is still the only ship basis. Committed, unlike the code index above.

Relates to: Feature map (code index), Doctor, QA stage

Doctor

The one read-only check /flow-next:features runs to answer “is this instance worth driving”: right build/version, port owned by this run, auth valid. It observes and never mutates. All three must pass before a drive, and it re-runs on each fresh session and after any failed drive. Two ownership rules ride with it - never drive an instance this run did not start, and never kill by process name.

Relates to: Feature map (user-POV drive map)

features_anchored

Optional scout output field listing feature slices from the feature map code index that overlap the current scope. Emitted by repo-scout when .clawpatch/features/*.json is present; omitted when absent. Each entry carries a last_mapped timestamp so downstream skills can flag staleness (informational signal, not a block).

Receipt

A review-layer JSON artefact that gates state transitions. flowctl impl-review writes a receipt at .flow/review-receipts/<branch>.json with verdict (SHIP / NEEDS_WORK / MAJOR_RETHINK / NEEDS_HUMAN), confidence anchors, introduced vs pre-existing finding counts, and deferred / suppressed counts. NEEDS_HUMAN records a reviewer request for human adjudication; its receipt and status persist before the workflow exits with ESCALATE:. flow --auto reads review receipts to decide hop progression. A Green receipt is the gate-layer counterpart, not a review-layer receipt.

Relates to: Green receipt

Green receipt

The gate-layer artifact: a per-file JSON record at .flow/tmp/green-receipts/<sha8>-<gate_id>.json proving one exact command passed at one exact commit. Honored only when hash, path, and age match; otherwise the full gate runs. A reuse always leaves a loud GATE_SKIPPED line. Format: Receipts.

Worker subagent

A subagent dispatched by /flow-next:work to implement a single task with fresh context, when a spec has several tasks or a task goes to a named implementer, a host review mode, or a fresh context; a one-task spec is built inline instead. Re-anchors on the spec + task + git state (one flowctl anchor bundle, one call), implements the task, records evidence (commits + tests + done summary), and exits. The fresh context per task is what enables N tasks to run in parallel without context-bleed.

Carmack-level review

The strict cross-model review tier flow-next runs by default. References John Carmack review standard. Five confidence anchors (0/25/50/75/100) gate findings; <75 suppressed except P0 @ 50+; introduced vs pre-existing classification means only introduced findings count toward the verdict.

Triage skip

A deterministic whitelist pre-check that returns SHIP without invoking a review backend, for trivial diffs: lockfile-only / docs-only / release-chore / generated-file-only. flowctl triage-skip is the helper. Opt out with --no-triage.

PR briefing

The pull request body as a reviewer’s briefing. The agent authors one object, the aid artifact, from the spec, task evidence, review receipts, decisions and the diff; flowctl validates, stores and renders it. Sections, each omitted when empty: Why, What changes for a user or operator, Scope (a size line, numbered review steps with what to check and up to ten must-read files each, then requirement coverage), Blast radius, Verification (a checklist that ticks only what passed), Tradeoffs, Open items. Every pull request gets the same form; there is no size threshold. Produced by /flow-next:make-pr.

Ralph

The repo-local autonomous shell harness of earlier releases, removed in 7.0. flow --auto is the one unattended mode; pin flow-next 6.7.x to keep Ralph. Migration: Migrating from Ralph.

Pilot

The unattended build driver’s former name. /flow-next:pilot became an alias for /flow-next:flow --auto --tick in 5.1.0, and 6.1.0 removed the command; the argument mapping is on Migrating from pilot. Not renamed: pilot.autonomy, pilot.gateClasses, flowctl pilot strikes, flowctl pilot-log, .flow/pilot-runs/, and the PILOT_VERDICT name. Full page: flow —auto.

Avoid: pilot as the name of the unattended driver (say flow --auto)

Relates to: Driver, Tick, Long-horizon run

Driver

One of the three things licensed to run pipeline stages: attended flow, flow --auto (the unattended build loop; see Long-horizon run and Tick), and land (the ship loop). Drivers are never nested except for flow invoking land as an authorized stage. Attended flow refuses under any autonomy marker (FLOW_AUTONOMOUS, AUTONOMOUS=1, mode:autonomous); flow --auto has no marker refusal because it sets FLOW_AUTONOMOUS and mode:autonomous for the stages it dispatches; flow invoking land for an explicitly authorized selected item is the sole composition exception; recursive drivers remain forbidden. A host loop (/loop, /goal, a shell script) schedules a driver and is never one itself.

Avoid: harness, loop (for the driver itself), autopilot

Relates to: Flow (attended conductor), Long-horizon run, Tick, Land

Long-horizon run

One /flow-next:flow --auto [<spec-id>] invocation that carries one ready spec hop after hop to a terminal: the PR exists (ADVANCED with make-pr), DEFERRED_TO_LAND, ASKED (backlog mode), BLOCKED, NEEDS_HUMAN, or NO_WORK. Only ADVANCED continues the loop, and the dirty-tree guard re-runs after every hop. Each hop classifies from the flow skill’s routing reference (route-matrix.md, plan-vs-no-plan.md, gate-selection.md), dispatches one stage with mode:autonomous, verifies from observed state, and records the same receipts, evidence echo, and ledger write a tick records, so a run that dies mid-way leaves committed receipts, a ledger entry, and a branch, and the next invocation classifies from disk; nothing is resumed from transcript. The terminal line names every dispatched stage joined by + (stage=work+qa+make-pr) and carries the last hop’s verdict. The default unattended recipe is one such invocation per item.

Avoid: pilot run, auto mode

Relates to: Driver, Tick, Verdict, Routing reference

Tick

One hop of flow --auto under --tick: select, classify one stage from the routing reference, dispatch it with mode:autonomous, verify from observed state, record the receipts and the ledger, print one PILOT_VERDICT line naming that one stage, and stop. This is what a pilot tick was, and it is the shape a host cadence primitive schedules (/loop 30m /flow-next:flow --auto --tick, or a /goal objective). Land keeps its own tick and its own LAND_VERDICT line.

Avoid: iteration, step

Relates to: Driver, Long-horizon run, Verdict, Land

Backlog mode (pilot.autonomy)

flow --auto’s opt-in wide-autonomy behavior, gated by pilot.autonomy in {ready (default), backlog} or forced for one run by --backlog. A backlog run enumerates the full open set (flow specs via flowctl ready --all plus tracker issues at the promoted lane), selects the top dep-ordered actionable item, triages it, and either drives it to a terminal (one hop under --tick) or parks it behind an async question (ASKED). It never authors a spec or sets ready; merge requires separate --until=merge authorization for the selected item; the next invocation selects the next item. Full page: Backlog mode.

Triage stage (backlog mode)

The classify-and-route stage backlog mode runs in front of flow --auto’s own classify, on the selected item only. It reads the spec agentically, never from a computed score: workable advances, dep-unsatisfied sequences behind its blocker, and ready-but-thin is kicked back with a question.

Ask stage / question valve

Backlog mode’s async human-in-the-loop valve: stuck becomes a question rather than a stall, and never an interactive prompt. Each question is written into the spec’s ## Open Questions behind a stable anchor and projected to the tracker when the bridge is active, then the item is parked (ASKED) and the loop moves on.

Decision log (pilot-log)

The per-hop record flow --auto --backlog writes via flowctl pilot-log append, one row per dispatched stage, stored as row files under .flow/pilot-runs/ ({tick, id, action, stage, costTokens}). It is what makes the factory-efficiency readout possible: how much moved with no question, with one async answer, or parked, and at what cost.

Flow (attended conductor)

The attended conductor (/flow-next:flow). It takes whatever the user has (nothing, an idea, a spec or task id, a tracker issue, a branch, a path, a pasted bug report, a how or why question) and routes on content and context, never on input kind. Each hop matches the routing reference, runs the routed stage skill by name (capture, refine, plan, plan-review, work, qa, make-pr, resolve-pr keep their own contracts and receipts), re-evaluates from observed state, and stops at the next decision that is a human’s: the PR exists, merge is the only step left, or a stage surfaced a run-ending decision. --explain prints the recommendation and writes nothing under .flow/. With --until=merge it consumes land for the selected item; otherwise an existing-PR landing offer asks once unless already authorized. It never fabricates a verdict, and refuses under every autonomy marker with NEEDS_HUMAN: /flow-next:flow is attended - run /flow-next:flow --auto for unattended runs. Its --auto switch is the unattended driver (Long-horizon run), which reads the same routing reference; flow and flow --auto are two drivers and are never nested.

Avoid: guide, router skill

Relates to: Routing reference, Driver, Long-horizon run, No-plan route

Routing reference

The flow skill’s reference files, one per rule: the route matrix (starting state to route, with the positive signal, the safe skip, and the skip kind; rarer rows live in a companion file), the spec-count rule, the plan-versus-no-plan rule, gate selection (which review, QA, and completion gate applies and from which key or flag), prototype before ask, the tail rule (where an attended run ends), and the smaller references for defect intake, the no-argument case, the QA stage, backlog mode, and --explain. The shared working rules (scope, tests, attended and unattended, review by risk) apply on every route. Flow’s route step, flow --explain, capture’s closer, plan’s next-steps menu, and work’s zero-task ask read the same files, so the recommendation you read and the route that runs cannot diverge. Router staleness is a defect. Adding or removing a skill updates the matrix in the same change.

Relates to: Flow (attended conductor), No-plan route, Prototype before ask

Prototype before ask

The rule flow and the routed skills apply before any “which approach” question: classify the fork first. An answer that is observable (behaviour, output, timing, layout, a failing case, a measurement) is settled by running the smallest experiment that discriminates the branches, and the run continues with the observed answer. Only a product or preference call no experiment can settle (scope, priority, authority, taste, a business rule) becomes a blocking question, at most one per hop. A prototype is evidence, never a deliverable.

Relates to: Routing reference, Flow (attended conductor), Chart

Refine

The question pass over an existing spec, task, or spec file (/flow-next:refine). It asks, in one pass, only what would change the build, optionally focused by a free-text --scope lens (business, technical, qa, …), plus the read-only research scope. Renamed from interview in 5.0.0; the /flow-next:interview command was removed in 6.1.0. The config key tracker.perEvent.interview keeps its name.

Avoid: interview (as the command name)

Relates to: Research scope, Spec, R-ID

Research scope

/flow-next:refine <id> --scope=research: a read-first pass that asks nothing. It dispatches four read-only scouts in parallel (docs-scout, practice-scout, docs-gap-scout, memory-scout, plus github-scout when scouts.github is on) and writes one ## Resolved via Research section on the spec or task, one sub-block per scout, a source on every bullet, through refine’s read-back. Observably skipped when the section exists or plan’s tasks already carry the scout findings; --force reruns; a spec that newly names a library reruns for that delta only. Plan applies the same rule in reverse, so the pass never runs twice and never by default. Flow routes to it when a spec names a library or API the repo does not already use.

Relates to: Refine, Routing reference

why-scout

A read-only agent that answers a why question about the code (“why was Y built this way”) with evidence. It starts from a pointer (a file, a symbol, a line range, a commit, a PR number, or a spec id), anchors on git blame and the PRs behind the commits, reads the tracker thread only through access the session already has, then the bug and decision memory tracks. Every finding carries one confidence tier the caller may not rewrite: direct (the reason is stated, quoted), supported (linked artifacts point at it), inferred (the scout’s reading of the diff), or unknown (the chain ran out, with what would resolve it). Tool-enforced read-only, no command of its own; flow dispatches it on the investigation route.

Relates to: Flow (attended conductor), Routing reference

Land

The ship loop for one named pull request (/flow-next:land <PR>). One invocation is one tick: it resolves review threads, makes one CI fix or one flake rerun, catches the branch up, and ends with a LAND_VERDICT line. It squash-merges, pinned to the head it judged, only when the merge was authorized in the current session; otherwise it stops at merge-ready; authorization required. It never picks another pull request, keeps no files, and writes nothing to the repository after the merge. It is the only place in flow-next licensed to merge. On a chain or stack it merges only the frontier, one layer per invocation. Full page: Land.

Chain

A dependent PR whose base is the parent spec’s branch instead of the default branch. Exists on any code host because it is only a branch and a base ref. A dependent spec is chain-eligible when its parent is open with every task done and its branch on origin, judged by flowctl spec chain, the one predicate every consumer calls; work then branches from the parent’s remote tip and make-pr targets the parent’s branch. Chains are linear: one open parent, one child at a time. Avoid: stacked branch, dependent branch, branch-on-branch.

Relates to: Stack, Layer, Frontier (chain), Spec

Stack

GitHub’s server-side object over a chain: the linked PRs, the stack map in the merge box, sequential merge, and auto-retarget of the layers above a merged one. An enhancement of a chain, present only when the host is GitHub and make-pr’s link call succeeded; on any other host, or after a failed link, the PR stands as a plain chain layer. Never a local file: no stack extension is required or read. Avoid: gh-stack, stacked diff.

Relates to: Chain, Layer, Frontier (chain)

Layer

One PR in a chain or stack. The bottom layer is the open layer whose base is the chain’s base branch (the default branch, or the branch a human chose); every other layer’s base is the branch of the layer below it, so a reviewer sees only that layer’s own diff. Avoid: sub-PR, child PR, stacked PR.

Relates to: Chain, Stack, Frontier (chain)

Frontier (chain)

The bottom open layer of a chain or stack, the only one that can merge next. Land merges at most one frontier per invocation, from the bottom up; a human merging from GitHub’s stack UI does the same. Distinct from the chart frontier and from the task frontier flowctl ready reports inside one spec.

Relates to: Chain, Stack, Layer

QA stage (pipeline.qa)

The optional live-app QA pass (/flow-next:qa) as a config-gated pipeline stage. pipeline.qa is a string enum off | on | auto (default off; any other value is off). on: one live pass over the complete build at all-tasks-done, before make-pr, on every spec, under attended flow and flow --auto alike. auto: flow and flow --auto both read the gate-selection reference and run the pass when the spec’s acceptance describes UI behaviour on a drivable surface and a target can be started, otherwise record skipped(config: pipeline.qa=auto: <reason>) and advance to make-pr. QA never hard-blocks. NEEDS_WORK and BLOCKED advance to the PR with their findings. flowctl stores the value and never interprets it. Full page: Live-app QA.

Verdict

The structured outcome a loop skill prints for transcript-blind drivers, always the last line of a run or tick: PILOT_VERDICT=, LAND_VERDICT=, CHART_VERDICT=, RESOLVE_PR_VERDICT=. Terminal names are never renamed, because drivers grep them; PILOT_VERDICT keeps its name under flow --auto. A long-horizon run names every dispatched stage joined by + (stage=work+qa+make-pr) and carries the last hop’s verdict; a --tick run names one stage. Grammar and tables: Driving a loop.

Spec-as-PR

A team workflow where the spec is opened as a draft PR for review BEFORE any code lands. Reviewing a 50-line spec is higher-leverage than reviewing a 500-line implementation. Once merged, the spec is frozen on main; implementation PRs reference the merged spec.

Frozen-at-handover

The R-ID invariant. Once a spec has been reviewed once, R5 means the same thing forever. A reviewer reading R5 in a six-month-old commit, a new team member reading R5 in the spec, and /flow-next:make-pr emitting R5 coverage all refer to the same acceptance criterion. Renumber-forbidden after first review cycle.

Tracker

An external issue tracker (Linear, GitHub Issues, GitLab, or Jira) that flow-next projects a spec to via /flow-next:tracker-sync. The tracker is a co-editable mirror: body, status, and comments sync two-way, but it is projection, not coordination. The .flow/specs/<id>.md spec stays the source of truth and the quality layer, and the tracker never drives flow state or spawns agents. The skill owns semantic judgment; flowctl tracker owns deterministic provider operations. Distinct from /flow-next:sync (plan-sync).

merge-base snapshot

The common-ancestor body the tracker-sync 3-way merge compares against - a paired snapshot taken at the last sync point: both a flow-form body and a tracker-form body, plus content hashes (the echo fence). Stored in the spec-JSON tracker block (mergeBaseFlow / mergeBaseTracker / baseHashFlow / baseHashTracker) and written atomically as a unit (a one-sided update is rejected, so neither half pins to a stale sync point). Advances with lastSyncedAt on a real reconcile, never on a no-op echo.

discovery ceremony

The detect, surface, ask, never-assume flow /flow-next:tracker-sync runs before enabling the bridge. It probes destination and credential signals, surfaces what is present and absent, asks the user, and writes tracker.* config only on confirmation, with provenance. flowctl tracker resolve then persists normalized destination metadata and capabilities under tracker.resolved. No signal means nothing written; the bridge stays off. Resolution precedence is env > config > ask.

tracker-key handle

A tracker identifier (e.g. WOR-17) used as a resolvable flow id, the hybrid id model. Tracker-first specs are canonically wor-17-slug (tasks wor-17-slug.M); bare wor-17 / wor-17.M resolve as aliases. Flow-first specs keep fn-NN-slug and store WOR-17 in tracker.identifier as a resolvable display alias. Resolution is case-insensitive (show wor-17, work wor-17 resolve); the native fn- scheme is reserved (fn-N allocation counts fn-* only); one tracker team per repo; ids never rename on link.

dependency projection

Tracker-sync’s projection of a spec’s local depends_on_epics edges into tracker relations through flowctl tracker relate. Linear and Jira use native directional blocked-by relations. GitHub records a sub_issues hierarchy proxy and returns structured degradation because GitHub has no issue-level blocked-by relation. GitLab uses native blocked-by when tracker.resolved.capabilities.blockedBy is true; otherwise it uses a directionless relation plus a provenance-fenced <!-- flow:deps --> body block. Flow stays authoritative, operations are idempotent, and only direct edges project.

tracker result class

The exhaustive failure taxonomy every flowctl tracker invocation returns: invalid_input, inactive, unresolved, auth, rate_limited, transport, not_found, capability, conflict, stale_id, external_action_required, with fixed exit codes 2 through 12. Callers branch on the class, never on provider error text.

provenance ledger

The per-spec depRelations list (in the .flow/specs/<id>.json tracker block, atomic write) records which dependency relations tracker-sync created so projection is idempotent and provenance-aware. Each entry is {key, dep_spec, from_tracker_id, to_tracker_id, type, source, updatedAt}, where key is an opaque hash of the directed issue pair (never a raw issue key inline - trackers auto-linkify keys even inside HTML comments). Projection is additive-only. flowctl never removes tracker relations. A missing ledgered relation that remains declared locally is deferred as a conflict instead of silently recreated. Mirrors the merge-base hash-provenance shape, minus its paired-snapshot constraint.

completed-blocker rule

The tracker-sync semantics for a dependency whose local dep spec is done (its issue Done/Closed): the projected blocked-by relation stays visible on the tracker (preserving the real historical ordering on the board) but does NOT feed back into Flow ready=true gating - readiness already treats done deps as satisfied, and dependency projection must not regress that. Keys off the local dep-spec status (flow is authoritative), never a remote fetch.

Operability ladder

Prime’s tiered measure of whether an agent can actually operate a repo, scored from executed evidence rather than file existence: tier 1 = the build command actually runs, tier 2 = tests are discoverable and run, tier 3 = the app boots to a ready signal. Tiers are per-surface with a min-deployable headline (a monorepo carries per-member tiers, never one repo tier); a shape whose realistic ceiling is tier 1-2 reports “N/N at ceiling” and is offered a sideways move into observability/drivability instead of a fabricated tier bump. The verdict headline names the current operability tier and the single cheapest move up.

Relates to: Hard gate, Classification (prime)

Hard gate

One of prime’s three pass/fail gates that catch the existence-passes-but-execution-fails failure mode: G1 = the detected build command actually runs (or tier >= 1 operability evidence exists), G2 = tests are discoverable when a test framework is claimed, G3 = the agent instruction file’s quoted commands resolve and execute. Any failing gate is NAMED in the verdict headline with its error and caps the computed maturity level at 2, so a repo cannot reach a high “readiness level” on existence checks alone.

Relates to: Operability ladder, Classification (prime)

Delivery shape

Axis 5 of prime’s classification: the multi-valued kind(s) of thing a repo delivers (web-service, CLI, library, desktop app, prose/docs, and so on). The flowctl prime classify emitter emits raw shape markers (bin exports, framework markers, serve/health code, desktop markers, prose ratio); the skill resolves the final shape value(s) from those markers. Delivery shape selects the per-shape playbook and sets the realistic operability-tier ceiling (a library or prose repo honestly tops out below a bootable web service).

Relates to: Classification (prime), Operability ladder

Classification (prime)

Prime’s Phase 0.5 five-axis profile of a repo: lifecycle (greenfield / hybrid / brownfield), topology (two independent bits: monorepo, constellation-member), size/legibility band, stack(s), and delivery shape(s), plus an orthogonal assessment_scope (repository / workspace-member / constellation-home-base). The deterministic signals come from the flowctl prime classify --json emitter (bounded, pure-stdlib, no LLM); the skill layers judgment on top (Axis-5 shape reasoning, final per-axis confidence, bounded clarification asks, playbook selection). Classification parameterizes everything downstream: scout dispatch hints, N/A denominators, report shape, and playbook selection. --classify-only prints just this block for cheap portfolio triage.

Relates to: Operability ladder, Delivery shape, Hard gate