CLI Reference
flowctl is the deterministic CLI for .flow/ state.
Most users should use /flow-next:* commands. Use flowctl when debugging state, scripting CI, building integrations, or inspecting what the skills wrote.
This page covers the verbs you are most likely to script or inspect. flowctl --help lists every verb, flowctl <verb> --help (and flowctl <verb> <subverb> --help) prints its exact options, and flowctl usage prints the agent guide bundled with the installed plugin. The review dispatch verbs (flowctl codex|copilot|cursor|claude ...) and the bookkeeping verbs the skills call between review rounds are listed there and not repeated here.
Common commands
Section titled “Common commands”flowctl initflowctl specsflowctl tasks --spec fn-1flowctl ready --spec fn-1flowctl show fn-1.2flowctl start fn-1.2flowctl start fn-1.2 --reclaim # resume your own in_progress task; since 5.5.0 a plain start on it refusesflowctl done fn-1.2 --summary-file summary.md --evidence-json evidence.json# evidence.json: {"commits": ["<sha>"], "tests": ["<command>"], "prs": []}flowctl done fn-1.2 --range BASE..HEAD --test "python3 -m unittest" --summary-file - --json # 6.1.0: commits from a contiguous range, summary on stdinflowctl validate --allEditing tasks and their order:
flowctl start fn-1.2 --note "prior session ended" # claim note, recorded with the claimflowctl task set-description fn-1.2 --file desc.md # '-' reads stdinflowctl task set-acceptance fn-1.2 --file acceptance.mdflowctl dep add fn-1.3 fn-1.2 # fn-1.3 depends on fn-1.2flowctl task reset fn-1.2 # back to todo, from done or blockedflowctl task reset fn-1.2 --cascade # also reset the tasks in the same spec that depend on itflowctl validate --spec fn-1 --coverage --json # adds the requirement coverage tablevalidate --coverage (with --spec) adds requirement_coverage, a markdown table rendered from the tasks’ satisfies lists. Plan uses it to replace the spec’s ## Requirement coverage table. A task that satisfies an R-ID the spec does not have, and an R-ID no task satisfies, are warnings.
done checks its evidence (6.1.0). Evidence must carry at least one of commits, tests, or prs; other keys besides base_commit, files, and files_touched print a warning and are not rendered. --range BASE..HEAD derives commits and base_commit from the range and fails naming any unreachable SHA; repeat --test for several commands. Interleaved task histories keep explicit evidence lists. With planSync.enabled not true, done appends the stage: plan-sync - skipped(config: planSync.enabled != true) line to the summary itself.
show <spec> --json is smaller (6.1.0). It omits the review-attempt and tracker ledgers. Read them with flowctl review-rounds attempts <spec> --kind plan|impl --review-type plan|impl|completion and flowctl sync get-state <spec>. Since 9.17.0 it carries plan_review_drift: the paths the spec cites that changed since the commit its SHIP plan review saw, while no task has started, and an empty list when none did or the check does not apply (A SHIP whose cited files changed). Since 9.5.1 it carries completion_review_pending: true when a completion review is configured for the spec (the spec’s own review setting, then FLOW_REVIEW_BACKEND, then review.backend) and its status is not ship or not_required. make-pr leaves such a spec open.
Specs across branches
Section titled “Specs across branches”flowctl specs --refs [--fetch] [--json]Indexes every spec on the base ref (origin/HEAD, then origin/main, main, origin/master, master), on local branches and on remote-tracking refs. Plain flowctl specs is unchanged and still lists only the checkout. Without --fetch the command is offline and writes nothing; --fetch prune-fetches origin first, and a failed fetch still indexes the local refs (fetched: false, with git’s message in fetch_error, exit 0).
Each branch copy whose body differs from base is classified:
- live - merging the branch into base would change the spec body.
conflict: truewhen that merge conflicts. Squash merges are handled: a squash-merged branch’s changes are already in base. - stale - it carries nothing unmerged: an older copy, a merged copy, or a copy of a spec deleted on base.
{ "success": true, "base": "refs/remotes/origin/main", "fetched": false, "fetch_error": null, "refs_scanned": 85, "summary": { "branch_only": ["fn-12-login-flow"], "ahead_of_base": ["fn-9-export"], "concurrent_edits": ["fn-9-export"], "would_conflict": [], "local_branches_upstream_gone": ["refs/heads/old-feature"] }, "specs": [ { "id": "fn-9-export", "title": "Export", "status": "open", "on_base": true, "live": [ {"ref": "refs/remotes/origin/feat/export", "tip_date": "2026-10-06", "conflict": false}, {"ref": "refs/remotes/origin/feat/export-v2", "tip_date": "2026-10-05", "conflict": false} ], "stale_refs": ["refs/remotes/origin/fn-3-old-branch"], "tracker": null } ]}specs covers every spec id seen on base or any scanned ref. Title, status and tracker come from base’s sidecar when the spec is on base, otherwise from the first live ref in sorted order. With no base ref the command fails with success: false, naming the refs it tried, and exits 1.
Consumers: an older flowctl rejects the flag with exit 2 and unrecognized arguments: --refs; treat that as “not supported” and fall back to plain flowctl specs. Hygiene and team shapes: For teams.
flowctl specs --refs --tracker-id <id> [--fetch] [--json]Lists only the specs whose JSON links the durable tracker id <id>: in the checkout, committed or not, and on every local branch and remote-tracking ref. It reads each ref’s spec JSON rather than its body, so it finds a link that only a JSON change on a branch carries, and a spec already on base. Output is {tracker_id, fetched, fetch_error, linked: [{id, checkout, refs[]}]}. A spec JSON it cannot read or parse, such as a missing blob in a partial clone, fails the command instead of reading as “not linked”. The flag needs --refs. flow --auto --from-issue uses it to find a spec that already links the issue.
Deterministic store for optional pre-capture decision-map discovery. Skill page: Chart.
flowctl chart create --title "Multi-tenant billing" --outcome "..." --initial-map-file map.json --jsonflowctl chart show fn-140 --jsonflowctl chart list --jsonflowctl chart frontier fn-140 --jsonflowctl chart add-decision fn-140 --title "Research provider limits" --type research --jsonflowctl chart claim fn-140.D1 --jsonflowctl chart attach-asset fn-140.D3 --asset-file asset.json --jsonflowctl chart resolve fn-140.D1 --answer-file answer.md --sharpen-file sharpen.json --jsonflowctl chart resolve fn-140.D3 --answer-file answer.md --supersedes D2 --jsonflowctl chart out-of-scope fn-140.D4 --reason "Beyond outcome" --jsonflowctl chart release-claim fn-140.D1 --jsonflowctl chart release-claim fn-140.D1 --break-stale --reason "owner session lost" --jsonflowctl chart park-question fn-140 --body-file q.md --jsonflowctl chart remove-question fn-140 --question <key> --jsonflowctl chart wire-decision fn-140.D5 --blocked-by D1 --depends-on D2 --jsonflowctl chart briefing fn-140 --proposal-file proposal.json --jsonflowctl chart locate "https://linear.app/.../stored-url" --jsonflowctl chart link-spec fn-140 --briefing B1 --spec fn-141 --decisions fn-140.D1,fn-140.D2 --jsonflowctl chart abandon fn-140 --reason "deprioritized" --jsonflowctl chart reopen fn-140 --reason "new constraint" --json| Concern | Contract |
|---|---|
| Envelope | {success, schema_version:1, command, result|error} |
| Error classes | not_found, conflict, invalid_state, invalid_graph, stale_claim, validation, io |
| Size ceiling | chart.maxDecisions (default 12); override only via --force-size --reason after consent |
| Stale claims | chart.claimStaleAfter hours (default 24); --break-stale always audited |
| Locate | Local provenance ledger only - no network, no title matching |
| Tracker projection | When bridge active and tracker.charts=on; local commit first; remote failure never rolls back |
Decision types: research|probe|eval|prototype|interview|task. Attendance derived for the first five; task requires --attendance attended|unattended.
Spec commands
Section titled “Spec commands”flowctl spec create --title "Add OAuth" --branch fn-1-add-oauth --jsonflowctl spec create --title "Add OAuth" --plan-file plan.md --json # one-shot create+set-plan (--plan - reads stdin)flowctl spec create --title "Add OAuth" --tracker-parent PROJ-12 --json # 9.13.0: the parent issue its tracker issue is created underflowctl spec skeleton [--json] # print the scaffold spec create writes: templates/spec.md via SPEC.md -> spec.md -> bundled (frontmatter stripped)flowctl task create --spec fn-1 --from-json tasks.json --json # bulk tasks: one call, one lock, all-or-nothingflowctl task create --spec fn-1 --title "implement this spec" --require-empty-spec --json # mint only while the spec has zero tasksflowctl spec set-plan fn-1 --file spec.md --jsonflowctl spec set-branch fn-1 --branch fn-1-new-name --json # rename an existing spec's branchflowctl spec chain fn-2 --json # read-only: may this dependent spec start now, and on which parent's branchflowctl spec close fn-1 --json # close the spec and write every task's final status; the caller commits modified_pathsflowctl spec close fn-1 --retire superseded --by fn-7 --json # close a spec that ends without being built (superseded|moot|delivered-elsewhere)flowctl spec closed-in-range --base origin/main --json # read-only: which specs does this branch closeflowctl spec ready fn-1 --json # mark ready for execution (the consent gate, 1.12.0+)flowctl spec unready fn-1 --json # back to draftflowctl spec set-no-plan fn-1 --json # record direct execution consent on a zero-task spec (refused once tasks exist)flowctl spec clear-no-plan fn-1 --json # clear the field (always allowed)flowctl spec set-completion-review-status fn-1 --status ship --if-current needs_work --json # compare-and-setspec create --tracker-parent <identifier> (9.13.0) records tracker.parent on the new spec: the parent issue, as the tracker displays it, that the spec’s tracker issue is created under. It works with the flow-first and the --tracker-first form. flow-next reads it only when it creates that issue and never sends it again, and an empty value is refused. What each tracker accepts is in Parent issue at creation.
spec set-completion-review-status --if-current <status> writes only when the current completion-review status equals <status>, checked under the spec’s lock. On a mismatch it writes nothing and --json reports written: false. Statuses are ship, needs_work, needs_human, unknown and not_required.
A cold session orients with flowctl brief - session-scope sibling of the task-scope anchor bundle. One pure-read call renders open specs (one-line goals), actionable tasks with claim state, the last five completions with evidence flags, the memory index, and go-deeper pointers, deterministically capped at ~2k tokens with explicit truncation markers (--full lifts the cap, --json is the machine form with identical retained items). No git state, no writes: brief is .flow/-only, so identical state always renders identical bytes.
flowctl brief # cold-session orientation, <=2k tokensflowctl brief --full # same sections, no truncationflowctl brief --json # machine form, per-section truncated flagsflowctl anchor fn-1.2 # one task's bundle as the worker reads it (--md, the default)flowctl anchor fn-1.2 --json # machine form: sections and dependenciesThe ceremony fast path. A spec with a plan plus its full task set lands in two calls instead of about eight, with the same validation, atomicity, and receipts as the granular verbs. --from-json takes a non-empty array of {title, description?, acceptance?, touches?, satisfies?, deps?, priority?}, where deps entries are task ids or 1-based indexes of earlier entries. Since 6.1.0 description_file and acceptance_file may replace the inline strings (paths resolve relative to the JSON file, or the current directory for stdin), and touches is a single line rendered as the task’s Touches line. It rejects the whole batch on any invalid item with zero writes, names every invalid item and the allowed keys in one error, and returns the created ids in input order. The granular verbs remain the editing path. --require-empty-spec refuses, naming the existing task, when the spec already has one; the check runs under the same per-spec lock that allocates ids, so exactly one of N concurrent creates wins. That is the atomic mint behind the no-plan route.
spec ready / spec unready toggle the readiness flag, which you set (a flow --goal run also sets it for a child spec it minted). Both are idempotent (no write and no updated_at bump when the flag already matches; --json reports "changed"). The flag is lazy on disk, so an absent value reads false, but every JSON read surface emits an explicit "ready": <bool> and ready specs carry a [ready] badge in listings. It is orthogonal to status. With tracker.readyState configured the tracker is authoritative and overwrites local toggles on sync (Tracker sync).
spec set-no-plan / spec clear-no-plan toggle the sibling human-owned no_plan boolean, the durable “skip decomposition” consent behind the no-plan route. Same lazy contract as ready: idempotent toggles (--json reports "changed"), absent reads false, and every JSON read surface emits an explicit "no_plan": <bool> (noPlan on ready --all rows). Setting is refused once the spec has any tasks, because a planned spec routes through its tasks; clearing is always allowed (stale-field cleanup). The field is flow-local and never tracker-projected. Two consumers read it: flow --auto classifies a marked zero-task spec straight to the work dispatch, and on a ready zero-task spec with no recorded route it applies the plan-versus-no-plan rule and records the result with these two verbs before any mint; work honors the field as the explicit no-plan instruction.
spec add-dep / spec rm-dep record and remove a dependency between specs (flowctl spec add-dep fn-2 fn-1: fn-2 depends on fn-1). Since 9.7.0 add-dep refuses a dependency that would close a loop, a spec depending on itself included. It writes nothing, exits 1 and names the loop in dependency order:
{"success": false, "error": "Dependency cycle: fn-3 -> fn-1 -> fn-2 -> fn-3", "code": "dependency_cycle", "cycle": ["fn-3", "fn-1", "fn-2", "fn-3"]}validate --all reports every loop already on disk once, as a Spec dependency cycle: <path> error and in spec_cycles, and fails. Deps shows why each stuck spec cannot start.
spec chain is the read-only chain-eligibility predicate for a dependent spec and the one owner of the rule every consumer applies: flow --auto selection in ready and backlog mode, attended flow’s next-item pick, /flow-next:work at branch creation, and flowctl’s own task-admission gate (ready --spec, next, ready --all). It returns {spec, eligible, parent, parent_branch, parent_branch_on_remote, reason}. eligible is true when every dependency is landed (parent is null, reason is no open dependency, no remote read), or when exactly one dependency is unlanded with all of its tasks done, every other dependency is landed, that parent’s branch exists on origin, and no other unlanded spec is already chained on the same parent. A spec now closes on its pull request branch before the merge, so done alone does not mean landed. A locally closed dependency counts as landed when the default base records it as closed. Failing that, flowctl reads the dependency’s spec at the merge-base of its branch and HEAD: a close recorded there means this branch is stacked on unmerged work, and the dependency stays chained. With no close in the shared history it counts as landed, which covers a dependency squash-merged into a non-default integration branch, a deleted branch, and a spec with no recorded branch. A true merge onto a non-default base conservatively stays unlanded. These reads are local and never fetch. Otherwise reason is one of dependency <id> in progress, two open parents: <id>, <id>; chains are linear, parent branch <b> not on origin; push it or land the parent first, dependency <id> closed locally but not recorded at <base>; dependency branch <ref> is in this branch's history; fetch the base or land it, parent <id> already chained by <sibling-id>, base query failed: <error>, or remote query failed: <first stderr line> (parent_branch_on_remote: null; a failed query is never reported as an absent branch). At most one git ls-remote --heads origin per invocation, none when the spec has no dependencies, and never gh. Exit 0 on any evaluation; exit 2 when the spec or a named dependency does not exist. The task-admission gate treats the chain parent as satisfied and still empties the frontier on every other not-done dependency; task-level depends_on is unchanged. Consumers: work, make-pr, land.
spec close closes the spec and writes each task’s final status: done into its tracked JSON file, so a fresh clone reads the finished state. It refuses, before any file changes, when a task is incomplete. It writes files and commits nothing: --json returns modified_paths, naming the spec file and every task file it rewrote, and the caller commits exactly those. make-pr does this as the last commit before the pull request opens. Creating or starting a follow-up task reopens a closed spec and reports the spec file the same way.
spec close --retire <superseded|moot|delivered-elsewhere> [--by <spec-or-PR>]... closes a spec that ends without its own implementation: another spec superseded it, it became moot, or it shipped under other work. The spec records retired: {reason, by}, every task that never ran reads retired instead of done, and completion review records not_required, which every close and merge gate accepts. next stops routing to the spec, show, specs and list print retired: <reason> by <refs>, and land and make-pr count a pull request that retires a task-less spec as carrying it. An unknown reason is refused with the accepted list, --by without --retire is refused, and retiring a closed spec is refused. Creating a task reopens the spec and re-arms completion review.
spec set-plan overwrites the spec body. When the body changes and the plan review reads ship, the status becomes stale (reported as plan_review_stale: true), so work stops and flow runs plan-review again first. Anything that reads plan_review_status should treat stale like needs_work; spec set-plan-review-status accepts it too.
spec closed-in-range --base <ref> lists the specs a branch closes: done at HEAD, absent or not done at the merge base with <ref>, and with task files the range touches. A close that changes only the spec record is excluded, and so is a sibling whose close belongs to the history of its own still-existing branch. Text output prints one id per line; --json returns {"spec_ids": [...]} in the same order. It reads local committed objects only and never writes or fetches. make-pr uses it to write one body for a branch that closes several specs, hosting on the last id when no spec names the branch.
PR briefing artifact
Section titled “PR briefing artifact”pr-cognitive-aid validates, stores, selects and renders the one object behind a make-pr body.
flowctl pr-cognitive-aid validate --file aid.json [--json] # read-onlyflowctl pr-cognitive-aid write <spec-id> --file aid.json --base-sha <sha> --head-sha <sha> [--json]flowctl pr-cognitive-aid current <spec-id> --base-sha <sha> --head-sha <sha> [--json]flowctl pr-cognitive-aid render <spec-id> --base-sha <sha> --head-sha <sha>flowctl pr-cognitive-aid render --file aid.jsonrenderemits one briefing for every diff size. The sections are Why, Review focus, Needs you, Shape, What changes for a user or operator, Reading order, Tradeoffs and Verified, and an empty section disappears. There is no compact or full form, no size threshold, no body line budget and no forge-visible file list or totals. Each review step names its first described file as the place to start; mechanical and generated files close the reading order in one safe-to-skim line. Proof cells with outcomefailorunverifiedrender unticked under Needs you with their note;passcells are ticked under Verified, and a cell with no outcome is a plain item there. Artifact id, base and head ride in one HTML comment.- Input may be sparse.
validate,writeand both--filereaders accept an object that lists only the must-read files and omits each file’s change type, line counts and diff link. flowctl fills those from the diff, appends the remaining files as a rest-of-diff set, and stores the complete artifact. - Mentions are made inert, numbers stay live.
@namein authored prose cannot ping anyone. Issue and pull request numbers, URLs and commit SHAs remain links, sofixes #12still closes that issue on merge. - Several specs.
specIdslists every spec the body covers, requirement ids are qualified (fn-250:R4), and an uncovered requirement is named with its spec (Uncovered: fn-250:R7). - The additions are additive. Five optional authored strings (
userImpact,blastRadius,tradeoffs,openItemsandshape, which must be one fenced code block) and the optionaloutcomeon a verification cell leave the schema version at 1; stored artifacts stay valid. writenever overwrites. It validates and creates one immutable generation under.flow/artifacts/<spec-id>/pr-cognitive-aid/.currentanswerscurrent,absent,stale,unsupportedorinvalid, and exposes no artifact unless it is current. A sparse artifact at an unchanged base and head is reused.- Errors arrive together.
validateandwritereport every independent violation with its field path in stable order and exit 2. A summary that is only whitespace is rejected by field name. html-inputwas removed with the HTML render lenses in 7.0. For a visual view of a diff, run/flow-next:visual.
Next unit selection
Section titled “Next unit selection”Deterministic “what should run now” for scripted drivers. Attended flow reads it as one hint when it picks the next open spec. flow --auto classifies each hop from the flow skill’s routing reference and the spec’s own status fields instead of this verb. Interactive sessions rarely need it; it is the right probe when scripting a loop or debugging why a driver picked (or skipped) a spec.
flowctl next [--specs-file specs.json] [--require-plan-review] [--require-completion-review] [--json]{"status": "plan|work|completion_review|none", "spec": "fn-12", "task": "fn-12.3", "reason": "needs_plan_review|needs_tasks|needs_completion_review|resume_in_progress|ready_task|none|blocked_by_spec_deps", "blocked_specs": {"fn-12": ["fn-3"]}}Selection walks specs in id order and stops at the first actionable unit. A zero-task spec with explicit no_plan: true reports status: work with its spec id and no task id; an explicit --require-plan-review gate still reports needs_plan_review until satisfied. An unmarked zero-task spec reports status: plan with reason: needs_tasks. Direct work creates the single full-spec execution owner; the selector does not mint one. Existing planned tasks retain their normal selection and review gates.
--require-plan-review holds work until the spec’s plan review reaches ship. --require-completion-review gates spec closure. With all tasks done but completion_review_status outside {ship, not_required}, it returns status: completion_review. An unrecognized or absent value satisfies nothing.
Unattended-run commands
Section titled “Unattended-run commands”These verbs serve /flow-next:flow --auto. They keep their pilot spelling; the /flow-next:pilot command itself was removed in 6.1.0.
flowctl pilot snapshot [--spec <id>] --json # 6.1.0: everything one hop needs, in one readflowctl pilot strikes record <spec-id> --stage <stage> --reason "<reason>" [--json]flowctl pilot strikes list [--json] # the two-strike ledger flow --auto writesflowctl pilot strikes clear <spec-id> [--json] # the human clear after a strike 2/2 verdictflowctl pilot strikes clear --all [--json]flowctl pilot-log append --id <id> --action <triaged|advanced|asked|blocked|needs-human> [--stage <stage|->] [--cost-tokens <n>] [--reason "<one line>"] [--json]flowctl ready --all [--json] # backlog-wide eligibility scan for flow --auto --backlogflowctl ready --spec fn-1 --admit --in-flight fn-1.1 --cap 3 --json # 6.1.0: rolling admissionpilot snapshot (6.1.0) bundles the run guards, config, candidates with their chain, claim, strike and plan_review_drift facts, the selected spec, the review backend, lifecycle and PR observation, branch existence, QA freshness, and the task list before dispatch. One PR listing joins branches to their open, merged, and closed pull requests. forge names the origin remote’s forge (github, gitlab, bitbucket, or null when none claims the host); on GitLab, merge requests are listed through glab, and on Bitbucket Cloud pull requests through bkt, in the same row shape, and the open one carries the readiness that land’s GitLab gate or Bitbucket gate reads. A failed probe stays explicit, and the caller ends the hop instead of reconstructing the state.
pilot strikes record (6.1.0) increments one cumulative counter per spec under the ledger lock; at count 2 it unreadies the spec. --json returns count and unreadied, and an unknown spec fails.
ready --admit (6.1.0) adds admitted and held lists to the ready read, with mechanical reasons: dependency closure, missing or overlapping Touches (touches-missing when a task has no Touches line), always-serial surfaces, and the --cap capacity. JSON task rows carry parsed touches and transitive dependency facts. The owner can still hold an admitted task for coupling the Touches lines do not show.
pilot strikes reads and clears the ledger at <git-common-dir>/flow-next/pilot-strikes.json, which flow --auto writes when a hop advances nothing. The ledger lives under the git common dir, so worktrees share it and git add -A can never commit it. list is empty-safe (a missing ledger renders empty at exit 0). clear <spec-id> removes exactly one entry atomically; an unknown id is a not-found exit 3 naming the known entries. Clearing never touches spec readiness in either direction. A strike 2/2 verdict unreadies the spec and names this command in its reason string, because on a repo with tracker.readyState armed the board echo re-grants readiness and cannot clear the strike.
pilot-log appends one decision-log row per dispatched stage under .flow/pilot-runs/ when flow --auto --backlog reaches a terminal (auto-gitignored, and not a receipts/ path). --action is the frozen enum above; a live run logs only terminal actions and triaged is diagnostic-only. --cost-tokens is host-reported; flowctl stores the row and never measures cost. --reason "<one line>" stores the host’s verdict reason verbatim as reason on that row, so a chained dispatch’s row begins chained on <parent-id>; ; rows written without the flag keep the frozen {tick, id, action, stage, costTokens} shape.
ready --all is the deterministic substrate for flow --auto --backlog (or pilot.autonomy=backlog). For every open spec it returns ready, noPlan, readySignal, blockedBy (unsatisfied dependency spec ids; a chain parent per spec chain is not listed), and hasSpec, and never a judgment field. Whether an item is workable, thin, or needs a spec is the skill’s agentic read in the triage stage.
Criteria commands
Section titled “Criteria commands”Thin plumbing for the project’s standing criteria in the user-owned .flow/criteria.md (G-ID grammar: one line-anchored - **G<N>:** <criterion prose> bullet per criterion). Parse and validate only, since judging compliance belongs to spec completion review (and, on a single-task spec, to that task’s implementation review).
flowctl criteria list [--json] # parse + validateflowctl criteria prompt-block # print the completion-review injection block{"success": true, "criteria": [{"id": "G1", "text": "Every route change regenerates the API contract."}], "count": 1, "path": "/abs/path/to/repo/.flow/criteria.md"}An absent or empty file returns an empty list (and empty prompt-block output) at exit 0 - absence costs nothing anywhere. An existing file that is unreadable or invalid fails closed: nonzero exit with the validation errors on stderr and empty stdout, so a careless append cannot inject error text into a prompt file. Ids must be unique, gaps are allowed, and at most 100 active criteria are accepted. path is absolute, and null when the file is absent.
The host completion-review workflow runs criteria prompt-block before reserving a review round, which turns a broken criteria file into a fast validation error instead of a spent round.
Feature map
Section titled “Feature map”Read-only facts about the committed feature map at .flow/features/, so setup, prime, and flow share one recommendation for /flow-next:features. flowctl never validates the four-section shape (the skill does) and never edits the map.
flowctl features status [--repo <path>]... [--json]recommendationisseed(no map),maintain(the map is due), ornone.dueis true when a map exists and at least one open drift note or stale feature file exists;reasons[]names each.features[]has one row per feature file (the indexREADME.mdexcluded):file,state(proven,never-proven, ormalformed),last_proven({date, commit}ornull),measured_from(commit, ordatewhen the recorded commit is not in this clone, such as a squashed branch head),commits_since, andstale.commits_sincecounts default-branch commits (origin/HEAD, thenmainormaster, thenHEAD; reported asbase) after the proof that change at least one path outside.flow/that is not documentation. A row isstalewhen that count reachesfeatures.staleAfterCommits(default 50, reported asthreshold), and always when it is never proven or malformed.--repo <path>(repeatable) names a sibling repo that holds product code in a home-base workspace, relative to the repo that holds.flow/. Each proven row then adds that repo’s product commits since the proof date (measured from its own default branch) tocommits_sinceand reports the split ascommits_since_by_repo("."is the.flow/repo); the output gainsrepos. A path that is not a git repo root, is the.flow/repo itself, or has no default branch that resolves exits2naming it. Without--repothe output is unchanged.open_driftlists active knowledge entries taggedfeature-map-driftas{id, title, path}; it isnullwhen memory is disabled or uninitialised, so only the age condition applies.
Exit 0 (or 2 for a bad --repo). A repository without .flow/ has no map and reads as seed. The command never dispatches /flow-next:features. How the three signals fit together: Keep the feature map current.
Memory
Section titled “Memory”The store behind memory and /flow-next:audit: one Markdown file with YAML frontmatter per entry, under .flow/memory/bug/<category>/ or .flow/memory/knowledge/<category>/. Writing entries and the audit plumbing (memory add, audit-scan, apply) are under Rendered artifacts; search reranking is under Judge.
flowctl memory init [--json] # create the category tree; needs memory.enabledflowctl memory list [--track bug|knowledge] [--category <c>] [--status active|stale|hardened|all] [--json]flowctl memory search "<query>" [--track ...] [--category ...] [--module <m>] [--tags a,b] [--limit N] [--status ...] [--rerank] [--json]flowctl memory read <id> [--json]flowctl memory upsert --track knowledge --category workflow --title "..." --body-file body.md [--json]flowctl memory mark-stale <id> --reason "<why>" [--audited-by <who>] [--json]flowctl memory mark-fresh <id> [--audited-by <who>] [--json]flowctl memory mark-hardened <id> --gate-ref "<path>#<rule-id> -- <note>" [--audited-by <who>] [--json]flowctl memory list-legacy [--json]flowctl memory migrate --dry-run [--json]flowctl memory migrate --yes [--json]- Ids.
readand themark-*verbs accept the full id (bug/runtime-errors/<slug>-<date>), slug plus date, or the slug alone (the latest date wins).readalso accepts legacy flat-file ids (legacy/pitfalls#N); themark-*verbs do not. --statusdefaults toactive, solistandsearchleave out stale and hardened entries. Passstale,hardenedorallto see them.upsertfinds an entry by exact title within the track. No match creates one, one match updates it in place, and two or more fail with the ambiguous ids and write nothing. It takes the same fields asmemory add.mark-stalesetsstatus: staleand records the reason.mark-hardeneddemotes an entry to a pointer at the gate that now enforces the lesson;--gate-refis stored verbatim and the entry’s body stays on disk.mark-freshreturns either kind toactive. All three stamplast_audited.list-legacyandmigrateread the flatpitfalls.md,conventions.mdanddecisions.mdfiles from before the categorized layout and propose a track and category per entry from the file name.migrate --dry-runprints the plan;--yeswrites it. For classification that reads each entry, run/flow-next:memory-migrate.
Glossary and strategy
Section titled “Glossary and strategy”Both files live at the repository root, outside .flow/, so they outlive Flow-Next. /flow-next:strategy writes STRATEGY.md; flowctl only reads it.
flowctl glossary add <term> --definition "One line." [--avoid "alt1,alt2"] [--relates-to "x,y"] [--json]flowctl glossary add <term> --definition-file body.md [--json] # '-' reads stdinflowctl glossary read <term> [--json]flowctl glossary remove <term> [--json]flowctl glossary list [--match "<text>"] [--json]
flowctl strategy status [--json]flowctl strategy read [--section "key metrics"] [--json]glossary addadds or replaces a term in the nearestGLOSSARY.mdabove the current directory, creating one at the repository root when none exists.--avoidrenders an_Avoid_:line naming terms to replace with this one;--relates-torenders a_Relates to_:line.glossary readwalks up from the current directory and returns the first file that defines the term (case-insensitive).removedeletes the term from the file that defines it; removing the last term leaves the file with its# Glossaryheading.strategy statusreports whetherSTRATEGY.mdexists, whether it is an empty husk, and how many of its sections are filled.strategy read --sectionprints one section: target problem, our approach, who it’s for, key metrics, tracks, milestones, or not working on.
Gate receipts
Section titled “Gate receipts”A green receipt lets work skip re-running a full test gate that already passed on the same code. Work writes and checks them; you can too.
flowctl gate receipt --gate unittest --command "python3 -m unittest discover -q" [--json]flowctl gate check --gate unittest --command "python3 -m unittest discover -q" [--json]flowctl gate classify --base <ref> [--json]gate receiptrecords that the exact command passed at HEAD, in.flow/tmp/green-receipts/<sha8>-<gate>.json. It refuses (exit1, nothing written) when the worktree has changes outside.flow/state, because the run tested more than HEAD.gate checkexits0(skip the re-run) only when a receipt matches the command string’s hash, is under 24 hours old, and was written at HEAD or at an ancestor whose diff to HEAD touches only.flow/state, with a clean worktree. Any doubt exits1: run the gate..flow/config.jsonand.flow/bin/count as changes.gate classifyreads the changes since<ref>plus the worktree and exits0(TIER_B) when every changed path is on the safe list (docs/,agent_docs/, rootREADME*,CHANGELOG.md,GLOSSARY.mdandSTRATEGY.md, and.flow/state), so work runs lint and format only. Any code or config extension (.json,.yamland.tomlincluded), a path underscripts/, or anything the safe list does not name exits1(FULL), and so does an empty diff. The path table is fixed and takes no config key; name generated docs your CI checks in your instruction file so the agent runs the full gate for them.
Receipts are local bookkeeping in one checkout. Remote CI never reads them, and a green receipt never means CI can be skipped.
Checkpoints
Section titled “Checkpoints”flowctl checkpoint save --spec fn-1 [--json]flowctl checkpoint restore --spec fn-1 [--json]save writes the spec, its task files and their runtime claim state to .flow/.checkpoint-<spec-id>.json. restore overwrites the current state with that snapshot. Plan review names restore as its recovery when the conversation is compacted mid-review. Checkpoint files are gitignored; delete stale ones by hand.
flowctl judge classifies one supplied state with a bundled TypeSafe Jev preset and applies that preset’s fixed decision rule, so every host computes the same decision from the same answers. The route preset is the exception: it is code only and never sends a request, with or without a key, so routing never asks Jev. It is the plumbing behind Optional Jev judgments; the skills call it, and you can call it to inspect a decision.
flowctl judge --preset <name> --state-file state.json [--json]flowctl judge --preset route --spec <spec-id> --json # the live spec's lifecycle, decided in code; sends nothingflowctl judge --preset tier --task <task-id> --json # 6.1.0: tier inputs from the task; returns tier_line, spawn_model, spawn_effort, implementerflowctl judge --preset tier --task <task-id> --effort-levels low,medium,high,xhigh,max --default-effort medium --json # worker effort facts from the hostflowctl memory search "windows subprocess" --limit 15 --rerank --json # BM25, then one rerank request over the top 15Presets: route, fork-gate, memory-rerank, tier. The retired qa-gate preset is an unknown-preset error: the QA gate never asks Jev. The command reads TYPESAFE_API_KEY from the environment at call time; judge.enabled=false disables it. Requests go to jev-latest with a 10-second timeout and two retries only for HTTP 429 and 529 (after 1 s and 2 s); a request estimated over 32k tokens is rejected without sending. The command never writes state, answers, or credentials to disk.
An available result carries success, available, preset, the returned model, typed answers, decision (value, rule, met), latency_ms, and usage. Tier decisions add the three leading candidates as [option, probability] pairs; memory decisions carry every judged entry id and score, reordered, none dropped. --preset route --spec <spec-id> always reports available: false, reason: routing_is_code, and its decision carries value, rule, met, pr_ref, and startable_target_fact for the tail and QA gates to reuse. It takes --spec only: intake routing is the host’s, so a route --state-file is a command error.
The route decision.value is the first match of:
value | When |
|---|---|
host | The pull request probe failed, the spec is closed with no observed pull request, spec approval is pending, every remaining task is blocked, or the spec is not ready. rule names which; met is false. |
existing_pr_tail | A pull request exists for the spec’s branch. |
all_done_make_pr | Every task is done. |
plan_review | The plan review reads stale, or (9.17.0+) files the spec cites changed since its SHIP plan review while no task has started; rule is then plan review predates changes to cited files: <paths> (details). |
work_planned | The spec has tasks to work. |
work_no_plan_default | The spec has no tasks and either records no_plan or is ready with no recorded route. Since 9.8.0 it no longer reads the spec body for plan signals; whether someone asked for a plan is the flow skill’s reading. |
--preset tier --task <task-id> returns tier_line, spawn_model, spawn_effort and implementer; an unknown task fails. For a worker the caller passes the host’s effort facts: --effort-levels <lowest,...,highest> (the levels the spawn’s effort parameter accepts, or the bridge’s when the implementer goes over one) and --default-effort <level> (what a spawn without one runs at), plus --explicit-effort for an effort the invocation or routing block names and --role-effort when the worker role pins one. Omit the levels when the spawn takes no effort parameter. spawn_effort is the level for the spawn’s effort parameter, or null for the host default; a bridged implementer carries it as <model> at <effort> in implementer. Scouts pass no effort facts. The rule behind the level is in Worker effort.
The model facts come from the host the same way:
| Flag | Fact |
|---|---|
--explicit-model <model> | The implementer the invocation named. It outranks the judge’s answer. |
--fast-model <model> | The host’s configured fast model, used for a task judged mechanical. |
--role-model <model> | A model the dispatched role pins. It wins over the spawn parameter. |
--can-spawn-model | The host can pick a model when it spawns a worker. |
--can-bridge | The host verified that a bridge to another CLI is reachable. |
When the host can reach an explicit model neither by spawn (no spawn-model parameter, or a role pin) nor over a bridge, tier_line reports the session tier and names why.
An unavailable result exits 0 and names the reason so the caller takes its existing fallback. Presets other than route omit the decision:
{"success": true, "available": false, "preset": "fork-gate", "reason": "no_key"}Reasons: no_key, disabled, http_<status>, transport, timeout, bad_answer, over_budget. A failed PR probe adds pr_probe_failed: true so the caller keeps its failure outcome. Unknown presets, unreadable or non-JSON state files, and missing required state fields exit non-zero; one error names every missing field.
memory search --rerank sends up to 15 BM25 hits in one memory-rerank request and reorders them by Jev score (ties retain BM25 order) without dropping any; --limit applies after the reorder. The judge receives each entry’s id, title, track, category, module, tags and snippet, never its path or BM25 score. JSON adds jev_score and jev_rank to reranked matches and top-level rerank: "jev"; an unavailable judge keeps BM25 order and returns rerank: "bm25", and zero hits send no request.
Rendered artifacts
Section titled “Rendered artifacts”Since 6.1.0 a skill hands flowctl its judgment and flowctl renders the artifact around it. flowctl derives ids, dates, counts, and commit and branch facts, validates every field, and writes atomically. An invalid payload reports every error together and writes nothing. --skeleton prints the exact authoring shape.
# One-call state readsflowctl preflight [--spec <id>] --json # planning config plus independent gate probesflowctl setup-status --json # setup's read-only probes and recorded optional answersflowctl setup-status --platform opencode --json # claude-code (default), codex, droid, cursor, grok, opencode, muse
# Artifacts rendered from the host's judgmentflowctl prospect write --skeletonflowctl prospect write --from-json prospect.json --jsonflowctl prospect archive <artifact-id> --json # move to .flow/prospects/_archive/flowctl qa receipt --skeletonflowctl qa receipt --from-json qa.json [--receipt receipt.json] --jsonflowctl memory add --track <track> --category <category> --title "..." --body-file body.md --check-overlap --jsonflowctl memory audit-scan --jsonflowctl memory apply --plan audit.json --json
# Review plumbingflowctl review-prompt impl <task-id|branch> --axis correctness --base <ref> --out prompt.mdflowctl review-prompt plan <spec-id> --axis correctness --out prompt.mdflowctl review-prompt completion <spec-id> --axis correctness --base <ref> --out prompt.mdflowctl review-rounds record <spec-id> --kind plan|impl --review-type plan|impl|completion \ --output-file review.md --reservation-id <id> --backend host [--model <model>] --attach [--task <task-id>] [--json]flowctl review-rounds resume-terminal <spec-id> --review-type completion --json
# Scoped readsflowctl glossary list [--json] --match "<text>"preflightreturns the config snapshot asvalueplus independentprobesfor config, strategy, glossary, decision entries, tracker, review backend, and memory. Each probe carriesstatusandvalue, with an error on failure; each consumer keeps its own fail-open or default behavior.setup-statustreats missing or unreadable setup state as a first run. Setup records the optional questions you declined, so a steady re-run asks nothing again.--platformpicks which plugin manifest supplies the version and which form of the instruction-file snippet theCLAUDE.md/AGENTS.mdcheck compares against (OpenCode’s flat/flow-next-form, Codex’sAGENTS.mdsnippet).prospect writetakes the title, focus, grounding, ranked survivors, and rejected ideas, and derives the artifact id, date, counts, and rejection rate.prospect archivesets the artifact’s status toarchivedand moves it to.flow/prospects/_archive/; it refuses when the archive already holds that artifact.qa receipttakesid,qa_outcome, findings, and R-ID coverage, plus optional mode,BLOCKED/NAreasons and per-scenarioscenariosrows. It derives commit, branch, timestamps, counts, and prior-finding lineage. Live scenarios are stamped with the current head. A row written as{"id": ..., "run": "carried"}copies its outcome, R-IDs, evidence and head from the prior receipt at the same path; a carry from another spec or branch, or of a scenario that did not pass there, is refused. See QA re-check.BLOCKEDorNAnever closes a prior finding nobody observed, and an invalid payload leaves the previous receipt in place.memory add --check-overlapreturns the overlapping entries without writing, so the host can fold a rediscovery into one with--update <id>.memory audit-scanreturns frontmatter, schema errors, recurrence counts, module existence and change evidence, and whether a hardened rule is present.memory applytakes the host’s plan (a list, or{"entries": [...]}); each entry namesidand may carryset,stamp,body,move,remove, andreplacement. Entries apply atomically one by one, moves and replacements update references, unknown ids are reported while the rest proceed, and a decision record can only be superseded.review-promptrenders the dispatch prompt a host review uses, from the same builders and re-review context as backend review.review-rounds record --output-filerequires--backend(host workflows pass--backend host; it no longer defaults torp) and takes an optional--modelnaming the reviewer’s model for the attempt row. It derives the verdict, review text, suppressed and classification counts, and unaddressed R-IDs from the review output; structured findings win over prose. A receipt payload that contradicts the output exits 2 before any state changes.--attachpublishes the journaled receipt in the same call; the matching reservation is still required.resume-terminalreturns{action, status, exit}for completion-review re-entry and rejects unknown persisted states.glossary list --matchreturns only the entries whose term or avoid-alias occurs in the text (whole word, case-insensitive). The worker’s anchor bundle passes it the task’s title and description.
Review commands also need fewer arguments. Codex plan review runs without --files, an omitted --base resolves to the default branch (origin/HEAD, then main or master), except on completion review, which first uses the base work recorded for the spec and then its chain parent’s branch, and plan and completion receipts default to <repo>/.flow/tmp/. Fan-out saves its round identity before dispatch, so an interrupted round recovers the draws that finished.
A malformed .flow/config.json is reported, never reset. Readers name the file and give line and column for a JSON syntax error, config set refuses to overwrite it, and validate reports a root error. A missing file still means defaults.
Traceability
Section titled “Traceability”flowctl trace <spec-id> [--format md|csv] [--json]Prints one row per acceptance criterion: the tests that cover it and each test’s result (from a task’s JUnit report when it has one, matched by the R-ID in the test name), its QA evidence, the review findings that name it, and the spec and implementation approvals. A gap check flags every criterion without evidence and every piece of evidence that names no criterion. Exit 0 means no gaps, 1 gaps, 2 an error such as an unknown spec. It reads the committed evidence folder when evidence.persist wrote one and still runs without it; an unreachable forge shows approvals as unknown with a warning. See Flow-Next in regulated environments.
Tracker commands
Section titled “Tracker commands”flowctl tracker is the deterministic provider boundary for Linear, GitHub, GitLab, and Jira. Skills supply semantic input files and recovery judgment. The CLI owns credentials, provider requests, pagination, retries, normalization, capability checks, mutations, and transaction boundaries.
Resolve
Section titled “Resolve”flowctl tracker resolve \ [--scope destination|destination.statusIds|destination.stateIds|capabilities] \ [--refresh] [--select KEY=VALUE] [--json]resolve populates or refreshes tracker.resolved. Scopes that are already fresh are skipped unless you pass --refresh. --select persists an explicit choice when discovery finds multiple candidates. Consuming verbs fail unresolved rather than guessing when required facts are absent.
Wire verbs
Section titled “Wire verbs”Wire verbs are locator-addressed and return normalized data:
flowctl tracker wire read --locator "$LOCATOR" [--json]flowctl tracker wire update --locator "$LOCATOR" [--title TEXT] [--body-file F] [--json]flowctl tracker wire comment-add --locator "$LOCATOR" --body-file F [--json]flowctl tracker wire comment-list --locator "$LOCATOR" [--json]flowctl tracker wire comment-update --locator "$LOCATOR" <comment-id> --body-file F [--json]flowctl tracker wire comment-delete --locator "$LOCATOR" <comment-id> [--json]flowctl tracker wire label --locator "$LOCATOR" [--add LABEL]... [--remove LABEL]... [--json]flowctl tracker wire assign --locator "$LOCATOR" [--add USER]... [--remove USER]... [--json]flowctl tracker wire list-open [--any-lane] [--unlinked] [--json]flowctl tracker wire list-states [--json]flowctl tracker wire unready --locator "$LOCATOR" [--json]flowctl tracker wire relation-list --locator "$LOCATOR" [--json]flowctl tracker wire question --locator "$LOCATOR" \ --subject-id ID --blocked-stage STAGE --reason-code CODE \ --question-slug SLUG [--reply-settles] --body-file F [--json]flowctl tracker wire attach --locator "$LOCATOR" --file PATH [--json]flowctl tracker wire attach-get <attachment-id> --out PATH [--json]list-states (4.1.0) enumerates the destination’s workflow states read-only -
Linear workflow states or Jira project statuses as {"states": [{"id", "name", "type"}], "complete": bool}. The complete flag distinguishes a provably full
listing from a truncated one, so a caller can refuse instead of trusting a
partial page; GitHub and GitLab have no workflow-state pool and return a typed
capability error. It never writes config - detection stays separate from
tracker resolve, which repairs the mapping and writes.
relation-list returns normalized directed dependency rows for backlog
ordering and fails closed when bounded pagination cannot prove the graph
complete. question computes its marker id from the four stable identity
inputs, reads comments before writing, and skips an existing id; free prose
travels only through the body file and does not affect deduplication. With
--reply-settles, a later comment that is not itself a flow-next question
settles the open round, so a follow-up on the same topic after a plain reply
posts a new round while a rerun of an unanswered round still dedups. Issue
starts pass it.
list-open (9.11.0 flags): without a flag it lists the open issues in the
exact tracker.readyState, unchanged. --any-lane lists every open issue in
the destination on all four trackers, also with tracker.readyState unset;
Linear leaves out completed, canceled and duplicate states, and Jira leaves out
the Done category. --unlinked drops issues a spec in this checkout already
links, from local sync state with no tracker call. Either flag returns compact
rows (id, identifier, title, url, labels, and a 500-character
excerpt of the body) with issues and truncated kept. Backlog mode reads
the ready lane with --unlinked; attended flow’s open-issue
triage reads --any-lane --unlinked.
unready (9.11.0) moves an issue out of tracker.readyState: Linear and Jira
to the resolved backlog state, GitHub and GitLab by removing the ready label.
It reads readiness the same way the projection does and writes only when the
issue is ready, so an issue already out of the ready state returns
changed: false. It needs no linked spec and writes no .flow/ state. It
returns {"issue":{"id","identifier"},"from","to","changed"}. With
tracker.readyState unset it returns unresolved/ready_state before any
call; with no resolved backlog state (allowed on Jira) unresolved/backlog_slot,
and with no Jira transition to it unresolved/transition_unreachable, both
without a write. An issue that still reads as ready after the write returns
transport/readback.
read on Jira (9.15.0) also takes a locator with only display, an issue key
or its /browse/ URL on the configured site (--locator '{"display":"IDEAS-7"}'),
and returns the same shape as a read by durable id, with the id filled in. An
idea still comes back with its idea block. An unknown key or another site’s
URL returns the read’s usual error. Every other verb, and every other tracker,
needs both halves of the locator.
With an idea source configured, every wire write verb refuses an idea’s key
with capability / idea_read_only before any request; since 9.15.0 that
includes unready and question, which read before they write. attach-get
turned down by Jira or GitLab carries the tracker’s reason like every other
rejection.
Wire verbs are useful for integrations and diagnostics. Lifecycle callers use the facade below because granular verbs do not provide create-if-unlinked, semantic marker deduplication, or aggregate receipts.
Lifecycle verbs and facade
Section titled “Lifecycle verbs and facade”flowctl tracker create <spec-id> --title TEXT --body-file F [--event KEY] [--parent ID] [--json]flowctl tracker create-first --title TEXT --body-file F --retry-key <16-hex> [--parent ID] [--json]flowctl tracker persist-external <spec-id> --identifier KEY-N \ [--id DURABLE-ID] [--url URL] --source mcp [--event KEY] [--json]flowctl tracker status <spec-id> \ --to backlog|todo|in_progress|in_review|done|cancelled \ [--reason completed|not_planned|duplicate|reopened] [--event KEY] [--json]flowctl tracker relate <spec-id> --blocked-by <dependency-spec-id> [--event KEY] [--json]flowctl tracker sync-body <spec-id> --flow-file F \ [--tracker-body-file F] [--direction push|pull] [--event KEY] [--json]
flowctl tracker sync <spec-id> --op push --event KEY \ [--flow-file F] [--body-file F] [--comment-file F] [--overwrite-diverged]flowctl tracker sync <spec-id> --op push --status-only --event KEYflowctl tracker sync <spec-id> --op pull --event KEY \ --flow-file F --body-file F --comments-file comments.jsonflowctl tracker sync <spec-id> --op reconcile --event KEY \ --flow-file F --body-file F --source-body-file F \ --comments-file comments.json [--pr-url URL] # --pr-url only with --event makePrflowctl tracker sync <spec-id> --op pull|reconcile --event KEY --prepare # 6.1.0flowctl tracker sync <spec-id> --op comment --event KEY \ --body-file Fcreate uses the spec’s tracker.parent as the parent issue; --parent replaces it and is recorded on the spec with the link. create-first --parent sends the parent and keeps it in the retry record, and a retry whose parent differs from the recorded one refuses with conflict / parent_mismatch. When the final record write fails after the remote create, the pending claim and the failure details carry the parent, so the recovery sync create-first-put keeps it and a retry with the same parent links the existing issue (9.15.0). Pass the same value to spec create --tracker-parent when minting. Both results report parent. On GitLab a numeric epic id counts as set only when the create response carries that epic; otherwise parent is null with degraded kind parent_not_set, a create-first retry reports the same, and no extra request is made. A GitLab parent that is neither ASCII digits nor an epic reference is invalid_input before any request (9.15.0). Jira Cloud, Linear and GitLab (an epic) accept a parent; GitHub and Jira Data Center / Server refuse it with a capability error before any request (Parent issue at creation). Since 9.13.0.
The facade owns create-if-unlinked, lifecycle ordering, marker deduplication, status, readiness and dependency projection, transaction boundaries, and exactly one aggregate receipt. Pull and reconcile receive the already adjudicated final Flow form as an input file; flowctl never authors the semantic merge.
--pr-url is how make-pr links its pull request: every make-pr run with an active bridge calls --op reconcile --event makePr --pr-url <url>, whatever tracker.perEvent.makePr says, and flowctl projects the provider’s native pull request link and records it in the same aggregate receipt. The issue moves to In Review on that call. The flag is refused on every other operation and event.
Since 6.1.0 push renders an omitted body from the spec, and an unchanged spec renders identical bytes; --status-only needs no body. A body-writing push on a linked spec whose tracker body changed since the last sync returns conflict with subtype tracker_diverged and writes nothing. --overwrite-diverged overwrites it and belongs only after a human confirms (Edits made on the tracker). --prepare on pull or reconcile returns the pre-reduction class, the tracker body with dependencies stripped, the base pair, and the genuine comments in one call, excluding marker comments and their hash matches. Its files point to private mode-0600 snapshots that the next facade call consumes; snapshots older than one hour are swept. The agent keeps the conflict and fold decisions.
Idea intake verbs
Section titled “Idea intake verbs”Jira Cloud only, and only with tracker.perTracker.ideaProjectKeys set (Idea intake). <idea> is a key in a listed project, or its URL on the configured site. Since 9.13.0.
# The idea's text, comments and delivery-linked issues; reads only.flowctl tracker idea read <idea> [--json]
# Reuse the idea's delivery-linked parent in the delivery project, or create one# a hierarchy level above tracker.perTracker.issueType (description from F) and# link it to the idea. --use picks one of several linked parents.flowctl tracker idea parent <idea> --body-file F [--use KEY] [--json]
# The delivery link from <parent-key> to the idea, when it is not there yet.flowctl tracker idea link <idea> <parent-key> [--json]| Command | Requests |
|---|---|
idea read | issue read, comment list |
idea parent | link types, issue read, project read; a label search when nothing is linked; create and link only when no parent exists |
idea link | link types, issue read; link only when absent |
read returns the idea’s text and comments without Jira’s colour markup ({color:#97a0af} tags), since 9.14.0. Since 9.15.0 code and {noformat} blocks come back byte for byte. The ordinary issue read keeps Jira markup.
Each verb reads before it writes, so a repeat creates no second parent and no second link. A parent parent creates carries the label flow-next-idea-<idea>. With no delivery-linked parent, a parent-level issue in the delivery project with that label is reused and linked, so a rerun after a failed link creates nothing (9.15.0). A create screen without a Labels field stops with capability / labels and creates nothing, and a label search response that cannot be read completely stops with transport / malformed_body. parent returns parent (key, created), link (created, existing, or error and retry when the link failed) and notReused (linked issues outside the delivery project or not at the parent level). It stops before any write with conflict / several_parents (several linked parents, or several labelled ones when none is linked; the candidates are in details.candidates), or unresolved / delivery_link_type when the site has zero or several matching link types (details.found).
Other errors: no idea project configured is unresolved; a key outside the listed projects is invalid_input; a key Jira now files outside the discovery projects (an idea moved into delivery) is capability / not_an_idea on all three verbs, before any write (9.15.0); another tracker, or Jira Data Center and Server, is capability. tracker wire read of an idea adds an idea block naming the reference that handles the path, and its request is unchanged; it also reads an idea by its key alone (wire verbs).
Result envelope and exit codes
Section titled “Result envelope and exit codes”Success:
{"success":true,"data":{},"degraded":null,"probe":null}Failure:
{ "success": false, "class": "conflict", "subtype": "several_parents", "error": "redacted human-readable summary", "retryable": false, "details": {"normalized": "todo", "candidates": []}}data is verb-specific. degraded records a confirmed capability transition. probe records a capability probe outcome without claiming a transition. Failure details is typed: rate limits include retry_after_s, capability failures include capability and required_plan, conflicts include normalized and candidates, and MCP continuations include action and payload. Branch on class and subtype, never provider error text.
subtype (9.15.0) is present whenever the error has one and names the case within the class that the verb docs branch on (several_parents, delivery_link_type, parent_mismatch, idea_read_only, …). The field is additive, so a caller that ignores it keeps working. error is redacted. On GitLab the redaction also covers GITLAB_ACCESS_TOKEN, OAUTH_TOKEN, glab’s config under GLAB_CONFIG_DIR, and every configured host’s stored token when the host glab used is not known (9.15.0).
| Exit | class | Meaning |
|---|---|---|
| 0 | success | Completed; inspect degraded and probe |
| 2 | invalid_input | CLI input or local contract is invalid |
| 3 | inactive | Tracker bridge is inactive |
| 4 | unresolved | Required tracker.resolved facts are absent or incomplete |
| 5 | auth | Credential is absent or rejected |
| 6 | rate_limited | Provider rate limit; retry only when retryable is true |
| 7 | transport | Provider request failed or returned an unusable response |
| 8 | not_found | Addressed provider object does not exist |
| 9 | capability | Requested operation is unsupported by the resolved capability set |
| 10 | conflict | Durable identity, status mapping, or transaction state conflicts |
| 11 | stale_id | Persisted provider identity is stale |
| 12 | external_action_required | Host must perform the described MCP continuation |
Tracker sync state
Section titled “Tracker sync state”flowctl sync holds the bridge’s local state: which issue each spec links, the paired merge base, receipts, and deferred conflicts. It never calls a provider; flowctl tracker does. It is unrelated to /flow-next:sync, which is plan-sync.
# Bridge and link stateflowctl sync active [--json] # bridge on? (tracker.enabled, or tracker.type set)flowctl sync get-state <spec-id> [--json]flowctl sync set-tracker-id <spec-id> <tracker-id> [--identifier WOR-17] [--url URL] [--force] [--json]flowctl sync set-last-synced <spec-id> [--at ISO] [--json] # defaults to nowflowctl sync set-merge-base <spec-id> --flow-file F --tracker-file F [--json] # or --flow / --tracker textflowctl sync clear <spec-id> [--json] # unlink: wipe the spec's tracker state
# Listings and guardsflowctl sync list-unsynced [--json] # specs with no linked issueflowctl sync list-stale [--older-than-hours N] [--json] # default N: tracker.staleAfterHoursflowctl sync check-collisions [--json] # one issue linked by two specs
# Dependency ledgerflowctl sync list-dep-relations <spec-id> [--json]flowctl sync set-dep-relation <spec-id> --dep-spec <id> \ --from-tracker-id <blocked-issue> --to-tracker-id <blocking-issue> [--type blocks] [--source flow] [--json]
# Create-first recovery recordsflowctl sync create-first-key --type github --title "Fix login" [--body-file b.md] [--parent <id>] [--json]flowctl sync create-first-get --key <key> [--json] # exit 1 when absentflowctl sync create-first-put --key <key> --id ... --identifier ... --url ... --title ... --transport ... \ [--spec-id <id>] [--if-absent | --expect-spec-id <id>] [--json]flowctl sync create-first-clear --key <key> [--json]
# Receipts, audit, deferralflowctl sync receipt <spec-id> --status pushed|pulled|merged|updated|diverged|queued|errored|noop \ [--event KEY] [--tracker-id ID] [--transport T] [--merges-file F] [--note N] [--json]flowctl sync check <spec-id> --events capture,makePr --since <iso> [--json]flowctl sync defer <spec-id> --summary "..." [--suggested "..."] [--reason "..."] [--branch B] [--json]set-tracker-idstores the durable issue id (the dedupe key), the display identifier and the URL. It refuses an id another spec already links unless you pass--force. Withtracker.perTracker.ideaProjectKeysset, it refuses an idea’s key in any letter case, and given only a durable id it asks for--identifier, so a spec is never linked to an idea as its own issue (9.15.0).clearwipes the spec’s tracker state, its recorded parent included, and changes nothing in the tracker.set-merge-basetakes both halves together, the Flow form and the tracker form, so the three-way merge base never mixes two sync points. A one-sided write is refused.list-dep-relationsreads the spec’sdepends_on_epicsand, for each dependency, its linked issue, its local status, and whether the edge is already recorded.set-dep-relationrecords a projected blocked-by edge in the spec’sdepRelationsledger.--from-tracker-idis the blocked issue,--to-tracker-idthe blocking one. Re-recording an edge changes nothing. Creating the relation on the tracker isflowctl tracker relate.- The
create-first-*verbs keep the recovery record for an issue created before any local spec exists, at.flow/create-first/<key>.json(gitignored). The key is the first 16 hex characters of a hash of tracker type, title and body, so a retried run finds the issue it already created and links it instead of creating a second.--parent(9.13.0) adds the parent to the hash, so the same work under another parent gets its own key; without it the key is unchanged.put --if-absentrecords the minted spec id only while none is recorded; the loser of a race exits10with subtypespec_already_mintednaming the winner.--expect-spec-idupdates a claim you already own. A laterputkeeps the parent the record already holds and, for the same issue, a recordeddegraded(a GitLabparent_not_set), so a retry compares and reports them as the first create did (9.15.0). checkis the read-only audit the lifecycle skills run at the end: for each event that fired,OK:<event>orMISSING:<event>when itsperEventleaf is on, the bridge is active, and no receipt with that event tag exists since--since. With the bridge off it exits at once. It always exits0.deferqueues a conflict to the deferred-findings file (.flow/review-deferred/<branch>.md) instead of asking, which is what an unattended run does.
Tracker operations explains when the skills call each of these.
State layout
Section titled “State layout”.flow/├── meta.json├── config.json├── specs/├── charts/ # optional chart discovery maps + decision records├── tasks/├── memory/├── features/ # optional user-POV feature map├── prospects/ # optional ranked idea lists├── templates/ # optional spec template (spec.md)├── criteria.md # optional standing criteria├── artifacts/ # PR briefing source generations├── review-receipts/ # review receipt copies├── pilot-runs/ # gitignored backlog-mode decision log├── bin/└── usage.mdAgents should use flowctl for writes instead of hand-editing state JSON.
CLI responsibility
Section titled “CLI responsibility”| Responsibility | Why it lives in flowctl |
|---|---|
| ID allocation | Must be deterministic and merge-safe |
| State transitions | Must be machine-readable |
| Validation | Must run in CI and local shells |
| Receipts | Must survive chat context |
| Migration | Must preserve repo-local state |
Judgment stays in the host agent. flowctl should not decide whether a spec is good, whether an architecture is right, or whether a finding is product-important.
Agent usage pattern
Section titled “Agent usage pattern”Agent-facing commands follow the sequence at the top of this page, with --json on the reads. Direct CLI usage is for automation and debugging; the docs teach the slash-command workflow first because that is the product surface.