Configuration

Flow-Next keeps configuration local and explicit.

Review backend

flowctl review-backend get
flowctl review-backend set codex
flowctl review-backend set rp
flowctl review-backend set none

Backend specs can include model and effort where supported:

codex:gpt-5.5:high
copilot:claude-opus-4.5:high

Actor resolution

FLOW_ACTOR wins, then git email, git name, $USER, then unknown.

Migration flags

FLOW_NO_DEPRECATION=1
FLOW_NO_AUTO_MIGRATE=1

Legacy epic aliases remain through 1.x as thin wrappers around spec.

Team defaults

Set defaults where the team can inspect them. The important policy decisions are:

• Which review backend gates implementation?
• Are plan reviews required for risky specs?
• Which actor name appears in task state?
• Do legacy aliases emit warnings in local scripts?
• Are autonomous Ralph runs allowed in this repo?

Backend policy

Use none only for experiments or disconnected local work. Production workflows should use a real review backend so the implementation model is not the only judge of its own diff.

flowctl review-backend set codex:gpt-5.5:high

Cross-spec plan-sync

Cross-spec plan-sync is opt-in and disabled by default:

flowctl config set planSync.crossSpec true
flowctl config set planSync.crossSpec false

planSync.crossSpec is the canonical key in Flow-Next 1.1.3+. When enabled, plan-sync can scan other open specs for stale references after a task changes shared APIs, naming, or patterns. Keep it off for fast local loops and Ralph runs unless cross-spec drift is a real risk.

The old planSync.crossEpic key remains readable through 1.x. Reading it emits one stderr line:

Warning: planSync.crossEpic is deprecated; use planSync.crossSpec. (Suppress with FLOW_NO_DEPRECATION=1.) Removed in 2.0.

flowctl config get prefers planSync.crossSpec and falls back to planSync.crossEpic only when the canonical key is absent from the raw .flow/config.json file. That raw-file check matters because defaults would otherwise make crossSpec: false appear set even when a repo only wrote the legacy key.

For callers that need disk-state semantics, use raw reads:

flowctl config get planSync.crossSpec --raw --json

Writing planSync.crossSpec does not delete planSync.crossEpic from existing config files. The legacy key stays until the 2.0 removal window.

Tracker sync

The tracker bridge is off by default and writes nothing until the discovery ceremony confirms a transport. See Tracker Sync for the full model.

flowctl config set tracker.enabled true
flowctl config set tracker.type linear        # linear | github | gitlab | jira
flowctl config set tracker.conflictTiebreak always-ask   # flow-wins | tracker-wins | always-ask
flowctl config set tracker.perEvent.plan reconcile       # off | pull | push | reconcile | comment
flowctl config set tracker.readyState "Ready"  # which tracker state means "ready for work" (1.12.0+)
flowctl sync active --json                     # must report active:true once enabled

The bridge is active when raw tracker.enabled == true or raw tracker.type ∈ {linear, github, gitlab, jira}. Each tracker.perEvent.* leaf has a schema default of off, so a bare enabled=true set by hand or a script — without running the discovery ceremony — fires no lifecycle-event sync (the accidental-enable guard). The one exception is make-pr’s unconditional PR↔issue link, which is active whenever the bridge is. But the /flow-next:tracker-sync ceremony activates every lifecycle event by default when you hook the bridge up: it’s opt-out, not opt-in. Turn any off with config set tracker.perEvent.<event> off.

tracker.readyState (default null) names the tracker workflow state that means “ready for work” — a Linear workflow-state name, a GitHub label, a GitLab label (GitLab has no workflow states, so readiness is a label like GitHub), or a Jira status name (matched like Linear, used raw — never through statusMap). When set, every pull-side sync projects that state onto the local spec ready flag — one-way, tracker → local, with the tracker authoritative (a local flowctl spec ready is overwritten on the next sync). Normally written by the discovery ceremony’s optional readiness question; null keeps the readiness gate dormant.

The deterministic plumbing the /flow-next:tracker-sync skill calls:

Command	Purpose
flowctl sync active	Is the bridge enabled for this repo?
flowctl sync get-state <id>	Read the per-spec tracker block
flowctl sync set-tracker-id <id> <uuid> --identifier WOR-17 --url <url>	Link a spec to a tracker issue
flowctl sync set-last-synced <id>	Advance lastSyncedAt on a real reconcile
flowctl sync set-merge-base <id> --flow … --tracker …	Pin the paired merge-base snapshot (both halves required)
flowctl sync list-unsynced / list-stale	Enumerate specs needing a link or a reconcile
flowctl sync check-collisions	Flag any tracker UUID shared by two specs
flowctl sync receipt --status … --event <perEvent-key> / sync defer …	Emit an event-tagged receipt; queue a genuine conflict
flowctl sync check <id> --events <csv> --since <iso>	Read-only lifecycle audit: OK/MISSING per triggered touchpoint — bridge inactive → silent constant-time exit (zero overhead for non-tracker repos)

Environment variables

Variable	Purpose
FLOW_ACTOR	Explicit actor name for task claims and state
FLOW_NO_DEPRECATION	Hide legacy alias warnings
FLOW_NO_AUTO_MIGRATE	Disable automatic migration behavior
LINEAR_API_KEY	Headless Linear GraphQL transport for tracker sync

Keep config boring. Flow-Next state is repo-local so CI, agents, and humans can reason from the same files.