# Configuration Source: https://flow-next.dev/flowctl/configuration/ The complete .flow/config.json reference - every key, generated from the published schema. All project configuration lives in one file: `.flow/config.json`. Read and write it through flowctl so writes stay validated and atomic: ```bash flowctl config get --json # one key (dotted path) flowctl config get --json # the whole tree flowctl config set # validated write ``` A missing file means defaults. An unreadable, malformed, or non-object file is reported and never reset (6.1.0+): readers warn once per process naming the file, with line and column for a JSON syntax error, `config set` refuses to overwrite it, and `flowctl validate` reports a root error. Fix the file by hand, then rerun. Every key below comes from the published JSON Schema at `plugins/flow-next/schema/flow-config.schema.json` - the same schema `/flow-next:setup` stamps into the file’s `$schema` field, and the one the repo’s drift test holds flowctl to. A key flowctl accepts that the schema does not document fails the suite. This page is the human rendering of that contract. `/flow-next:setup` walks you through the everyday choices (review backend, live QA, spec ids when a tracker is configured, project docs, standing criteria). Everything else here is set directly with `flowctl config set` - opt-in features, autonomy tuning, and per-tracker plumbing that only matters once you use the subsystem. Keys marked *machine-written* are maintained by ceremonies and resolvers; read them freely, but let the tooling write them. ## Core pipeline Always-relevant knobs for the default spec-to-PR flow. Every optional layer here is off or conservative by default; this page states what each key does. | Key | Type | What it does | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `review.backend` | enum | Default review backend (rp, codex, copilot, cursor, claude, host, none) or spec form backend\[:model\[:effort]], e.g. `codex::high`. cursor folds effort into the model name (no :effort rung); claude takes the full grammar with the CLI’s efforts (low, medium, high, xhigh, max); rp, host, and none are bare-only. copilot accepts no none/minimal effort. If unset, review commands require —review or FLOW\_REVIEW\_BACKEND. Default: `null`. | | `review.maxIterations` | integer | Cumulative review-round cap per scope (default 8, minimum 1 - the cap can never be disabled). The env var MAX\_REVIEW\_ITERATIONS takes precedence over this key. In an autonomous run (flow —auto) this key may only lower the cap, so an autonomous agent cannot extend its own review gate. Default: `8`. | | `planSync.enabled` | boolean | Enable plan-sync after task completion. Off by default; run /flow-next:sync manually when a task invalidates a downstream assumption. Default: `false`. | | `planSync.crossSpec` | boolean | Cross-spec plan-sync: scan other open specs for stale references after each task (opt-in; increases sync time). Default: `false`. | | `memory.enabled` | boolean | Enable the memory system: skills capture and search categorized learnings under .flow/memory/. Default: `true`. | | `judge.enabled` | boolean | Enable the optional judge when TYPESAFE\_API\_KEY is present in the environment. Default true; false disables requests. Invalid non-boolean values warn and behave as true. See [Optional Jev judgments](https://flow-next.dev/guides/jev-judge/). Default: `true`. | | `scouts.github` | boolean | Enable github-scout during planning (requires the gh CLI). Default: `false`. | | `makePr.derivedPaths` | object | Optional derived-file classification rules for the make-pr export: bucket names (dualCopy, mirror, state) mapped to arrays of rules ({path\|prefix, source}). A configured value fully replaces flow-next’s built-in default shapes; never required and not part of the seeded defaults. | | `pipeline.qa` | enum | Optional live QA stage. String-enum off \| on \| auto, NOT a bool; any other value, including bool true, is OFF. off: QA runs only when you invoke /flow-next:qa. on: one live /flow-next:qa pass at the all-tasks-done juncture before make-pr on every spec. auto: attended /flow-next:flow and /flow-next:flow —auto both read the key through the flow skill’s gate-selection reference and run the pass only when the spec’s acceptance describes UI behaviour on a drivable surface and a target can be started; otherwise the stage records `skipped(config: pipeline.qa=auto: )` and the route advances to make-pr. QA never hard-blocks a run: NEEDS\_WORK and BLOCKED advance to the PR, and their findings become open items on a draft PR. flowctl stores the value and never interprets it; drivability is the skill’s judgment. Optional: flow-next runs fully without it. It costs a live-app drive pass per spec plus a running deploy and a configured driver. Values: `off`, `on`, `auto`. Default: `"off"`. | ## Autonomy: flow —auto & land The build loop (`/flow-next:flow --auto`) and the ship loop (`/flow-next:land`). All off/conservative by default. The `pilot.*` keys keep their spelling; they configure `flow --auto`, which replaced the `/flow-next:pilot` command (removed in 6.1.0). | Key | Type | What it does | | ------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pilot.autonomy` | enum | Backlog mode for `/flow-next:flow --auto` (the key keeps its `pilot.` spelling). Scalar string-enum (ready \| backlog), NOT a bool. ready = `flow --auto` selects only already-ready specs. Only the literal backlog widens selection to the whole open backlog; the per-run `--backlog` flag forces it for one run; any other value stays ready. In long-horizon mode a backlog run drives its one selected item to a terminal and stops, and the next invocation selects the next item. Backlog mode never authors a spec or sets ready. It grants no merge authority by itself; `--until=merge` separately authorizes land for the selected item. Values: `ready`, `backlog`. Default: `"ready"`. | | `pilot.gateClasses` | enum | Backlog-mode force-gate for `flow --auto --backlog` (the key keeps its `pilot.` spelling): class names (e.g. risky, prod-config) that force surfacing before action - a matching item is parked with a question (`ASKED`) instead of advanced full-auto. Empty = full-auto for every workable item. Default: `[]`. | **`land.*`** - settings for [`/flow-next:land`](https://flow-next.dev/autonomy/land/), which handles one named pull request. Two keys remain. | Key | Type | What it does | | -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `land.patienceMinutes` | integer | Minutes since the last push that land waits before merging, so review bots can post, when the calling flow, not a human in the session, authorized the merge. The window is for bots, not people; raise it if your bots are slower. A human’s current merge authorization waives the wait. When GitHub reports no push time, land uses the head commit’s earliest check-suite creation time, then its committer date. Default: `10`. | | `land.mergeVerdictCommand` | string \| null | Opt-in repo merge gate: a shell command land runs once per invocation, only after every other merge gate passes, with a 600-second bound. Exit 0 allows the merge; any non-zero exit, a missing or unexecutable command, or a timeout blocks it with `NEEDS_HUMAN`. It runs from the repository where land was invoked without changing the checkout, so it must judge the remote `FLOW_HEAD_SHA`, not local HEAD. The environment also supplies `FLOW_BASE_REF`, `FLOW_PR_NUMBER`, `FLOW_SPEC_ID` (empty when several specs match) and space-separated `FLOW_SPEC_IDS`. Never executed under `--dry-run`. Unset, null, and an empty string all mean off. Default: `""`. | **Retired `land.*` keys.** A config file that still carries them loads normally. Land prints one notice naming the ignored keys and leaves the file unchanged; delete them when convenient. | Retired key | Use instead | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `land.release` | Run releases separately from your project’s release instructions. | | `land.reviewSignal`, `land.automatedReviewers`, `land.cleanReviewCommentPattern` | The default gate is green checks, a nonblocking GitHub review decision, and zero unresolved threads. Tighten it in your instruction file, with branch protection, or with `land.mergeVerdictCommand`. See [the merge gate](https://flow-next.dev/autonomy/land/#the-merge-gate-precisely). | | `land.reviewTrigger`, `land.requestReviewers` | Request reviewers outside land. | | `land.ciFixBudget` | Land makes one focused fix or one flake rerun per failure and reports `BLOCKED` naming the check. It keeps no ledger and sets no label. | | `land.patienceMinutesAfterReview` | `land.patienceMinutes`, anchored to the last push. | ## Deprecated in 7.1.0: `review.backend` `review.backend` leaves in 8.0.0. From 8.0.0 the reviewer is chosen in the model-routing block of your `CLAUDE.md` or `AGENTS.md`, the one `/flow-next:setup` proposes, the same way implementers and scouts already are. Until then the key works exactly as the table above describes, and a reviewer named in the prompt still wins. Its `rp` value (RepoPrompt) is deprecated on the same schedule; set another backend to move off it now. See [Review backends](https://flow-next.dev/reference/review-backends/#deprecated-in-710). ## Removed in 7.0.0: `pipeline.chainStages` `pipeline.chainStages` is gone from the schema. A config that still sets it keeps working: flowctl ignores the key and prints a one-line note. Under `flow --auto --tick`, make-pr now runs on the next tick; a long-horizon `flow --auto` run already runs QA and then make-pr as consecutive hops. Delete the key from `.flow/config.json` when convenient. ## Removed in 7.0.0: the HTML render lenses `artifacts.html.enabled` is gone from the schema. A config that still sets it keeps working: flowctl ignores the key and prints a one-line note. For a visual view of a spec, a plan or a diff, run [`/flow-next:visual`](https://flow-next.dev/skills/visual/), or ask the agent for an HTML page. ## Removed in 4.0.0: routing moved into prose The `work.delegate*` keys (packaged codex delegation) and the `models.*` block (the role map and its `verifiedAt` / `verifiedWith` staleness stamps) are gone from the schema and from flowctl. Routing lives in the [routing block](https://flow-next.dev/guides/model-routing/#the-routing-block) in your `CLAUDE.md` / `AGENTS.md` instead, and implementation offload is the [implementer tier plus a bridge recipe](https://flow-next.dev/guides/model-routing/#implementation-offload-the-bridge-route). **Leftover keys are inert, not dangerous.** A `.flow/config.json` still carrying them keeps working: flowctl ignores them entirely and prints **one** non-blocking advisory naming what it found, on the config surfaces and the work entry points, to stderr so a `--json` read stays parseable. Delete them when convenient. ## Chart (pre-capture discovery) Bounds for the optional decision-map stage. | Key | Type | What it does | | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chart.maxDecisions` | integer | Charting-time decision ceiling (default 12). chart create with an initial-map refuses past this count without —force-size —reason. Later sharpening may grow past it. Default: `12`. | | `chart.claimStaleAfter` | number | Stale-claim age threshold in hours (default 24). release-claim —break-stale —reason is allowed only after a claim is at least this old; always audited (actor, prior owner, age, reason). Default: `24`. | ## Feature map The due threshold for the optional [feature map](https://flow-next.dev/skills/features/). | Key | Type | What it does | | ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `features.staleAfterCommits` | integer | Due threshold (default 50). `flowctl features status` reports the feature map due a maintain pass when a feature file’s `**Last proven:**` commit is at least this many default-branch commits old, counting only commits that change a file outside `.flow/` and documentation. Values below 1 or non-integers read as the default. See [Keep the feature map current](https://flow-next.dev/guides/keep-feature-map-current/). Default: `50`. | ## Tracker bridge Projection to Linear / GitHub / GitLab / Jira. Inactive unless enabled. **`tracker.*`** - Tracker-sync bridge settings (Linear / GitHub / GitLab / Jira). See docs/tracker-sync.md. | Key | Type | What it does | | -------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `tracker.version` | integer | Tracker config schema version. Default: `1`. *(machine-written)* | | `tracker.enabled` | boolean | Enable the tracker-sync bridge. The bridge is active iff raw tracker.enabled == true OR raw tracker.type is one of linear/github/gitlab/jira. Optional: flow-next runs fully without it. It costs a bidirectional round-trip per enabled lifecycle event plus a conflict policy and a second place state can be wrong; enable it when other people need to read or edit status where they already work, or run /flow-next:tracker-sync manually and leave the bridge off in between. Spec-only is a first-class mode. See docs/running-lean.md. Default: `false`. | | `tracker.type` | enum | Tracker backend: linear, github, gitlab, or jira. Values: `linear`, `github`, `gitlab`, `jira` (or null). Default: `null`. | | `tracker.provenance` | string \| null | Free-form provenance written by the discovery ceremony on confirmation (who/when/signals). Default: `null`. *(machine-written)* | | `tracker.perEvent.capture` | enum | Sync op fired when a spec is captured: off \| pull \| push \| reconcile \| comment. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.interview` | enum | Sync op fired after a refine pass updates a spec (the key keeps its historical name): off \| pull \| push \| reconcile \| comment. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.plan` | enum | Sync op fired after planning: off \| pull \| push \| reconcile \| comment. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.work.firstClaim` | enum | Sync op fired on a task’s first claim: off \| pull \| push \| reconcile \| comment. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.work.done` | enum | Sync op fired when a task completes: off \| pull \| push \| reconcile \| comment. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.makePr` | enum | Sync op fired when make-pr opens a PR: off \| pull \| push \| reconcile \| comment. The PR link + In Review push is unconditional whenever the bridge is active. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.resolvePr` | enum | Sync op fired after resolve-pr: off \| pull \| push \| reconcile \| comment. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.completionReview` | enum | Sync op fired after the spec completion review: off \| pull \| push \| reconcile \| comment. The ceremony seeds comment (verdict + R-ID coverage; never terminal Done). Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.perEvent.qa` | enum | Post the /flow-next:qa ship verdict as a tracker comment: off \| comment only. comment is the only sensible verb for a verdict; the QA skill treats any non-off value as comment. Not switched on by the ceremony’s default-on set - QA-specific opt-in. Values: `off`, `comment`. Default: `"off"`. | | `tracker.perEvent.land.merged` | enum | Post-merge touchpoint for /flow-next:land. After a confirmed merge, land moves each matching spec’s issue to its terminal status through the tracker API whenever the bridge is active; this leaf does not gate that status write. Land writes no local sync receipt, timestamp, or verdict comment. A failed touchpoint keeps `MERGED` and names the merge commit; running land again on the merged pull request retries only the touchpoint. A closed spec on an open pull request stays In Review. Values: `off`, `pull`, `push`, `reconcile`, `comment`. Default: `"off"`. | | `tracker.charts` | enum | Optional chart lifecycle projection. String-enum off\|on, NOT a bool: only the literal on projects charts as parent issues with decision children through the tracker facade. Local chart operations always succeed when off or when the bridge is inactive. Values: `off`, `on`. Default: `"off"`. | | `tracker.perTracker.teamId` | string \| null | Linear team id. Default: `null`. | | `tracker.perTracker.projectId` | string \| null | Linear project id. Default: `null`. | | `tracker.perTracker.labelMap` | object | Label linkage map (tracker-specific shape). Default: `{}`. | | `tracker.perTracker.priorityMap` | object | Priority linkage map (tracker-specific shape). Default: `{}`. | | `tracker.perTracker.repo` | string \| null | GitHub repo as owner/name, written by the discovery ceremony (machine-written; not part of the seeded defaults). *(machine-written)* | | `tracker.perTracker.project` | string \| null | GitLab group/subgroup/project path (URL-encoded once for the API, never double-encoded). Default: `null`. | | `tracker.perTracker.host` | string \| null | Self-managed GitLab base URL. null resolves from glab config / CI\_SERVER\_URL; gitlab.com is never assumed. Default: `null`. | | `tracker.perTracker.baseUrl` | string \| null | Jira site base URL (Cloud or DC/Server). The JIRA\_BASE\_URL env var overrides it at runtime. Default: `null`. | | `tracker.perTracker.projectKey` | string \| null | Jira project key (the JQL / listOpenIssues scope). Default: `null`. | | `tracker.perTracker.authScheme` | enum | Jira auth shape decided once at the discovery ceremony: cloud-basic (Cloud HTTP-basic email:API\_TOKEN) or bearer-pat (DC/Server bearer PAT). Credentials still read from env each run, never stored here. Values: `cloud-basic`, `bearer-pat` (or null). Default: `null`. | | `tracker.perTracker.apiVersion` | integer \| null | Jira REST API version. null until the resolver pins 2; migration converges a legacy 3 to 2. Default: `null`. | | `tracker.perTracker.owner` | string \| null | GitHub repository owner (discovery-fingerprint input; dynamic per.get read via \_FINGERPRINT\_KEYS). | | `tracker.perTracker.issueType` | string \| integer \| null | Jira issue type (name or id) for created issues; a configured value that does not resolve against the live project is an error. | | `tracker.perTracker.blocksLinkType` | string \| null | GitLab link type used for blocks relations (e.g. blocks); probe and mutation use the same resolved name. | | `tracker.perTracker.preferredTransport` | string \| null | Linear transport preference (mcp routes through the MCP continuation; anything else uses HTTP). | | `tracker.perTracker.transport` | string \| null | Legacy alias for preferredTransport (read second). | | `tracker.perTracker.sslVerify` | boolean | Verify TLS certificates against Jira. false is an explicit opt-out for a self-hosted internal-CA / self-signed cert (JIRA\_SSL\_VERIFY env overrides). Default: `true`. | | `tracker.perTracker.statusMap` | object | Legacy normalized-status to Jira status map ({name}/{id}; id preferred - names are project-renamable). Live entries migrate into tracker.resolved.destination.statusIds; dead entries are dropped with a warning. Default: `{}`. | | `tracker.staleAfterHours` | integer | Staleness threshold (hours) consumed by sync list-stale. Default: `24`. | | `tracker.conflictTiebreak` | enum | Status who-wins tiebreak: flow-wins \| tracker-wins \| always-ask. Strict enum: invalid CLI writes are rejected; malformed persisted values fail before status work. In autonomous mode always-ask resolves to queue, not prompt. Values: `always-ask`, `flow-wins`, `tracker-wins`. Default: `"always-ask"`. | | `tracker.readyState` | string \| null | Readiness projection: the tracker workflow state meaning ready for work (a Linear state name, Jira status name, or a GitHub/GitLab label). When set, pull-side sync projects it onto the local spec ready flag - one-way, tracker is authoritative. null = projection off. Default: `null`. | | `tracker.specIds` | enum | Id scheme for new specs when a tracker bridge is active: flow (native fn-N) or tracker (tracker-keyed KEY-N-slug / synthetic gh-N / gl-N). Strict enum on write; malformed on-disk values fail closed to flow. Not materialized at init so setup can detect never-asked via a raw null read. Values: `flow`, `tracker`. Default: `"flow"`. | | `tracker.transport.timeoutS` | number \| null | Per-request timeout in seconds (0-600). | | `tracker.transport.maxRetries` | integer \| null | Retry attempts per call. | | `tracker.transport.backoffCapS` | number \| null | Backoff cap in seconds. | | `tracker.transport.concurrency` | integer \| null | Max concurrent tracker calls. | | `tracker.resolved.destination.statusIds` | object | Normalized status slots (todo, in\_progress, done; optional provider slots) mapped to provider status ids. *(machine-written)* | | `tracker.resolved.destination.stateIds` | object | Normalized state slots mapped to provider state ids (Linear). *(machine-written)* | | `tracker.resolved.capabilities._source` | object | Machine-written capability provenance (which probe/endpoint established each flag); GitLab’s resolver persists it alongside the boolean capability keys. *(machine-written)* | | `tracker.resolved.scopeResolvedAt.destination` | string | ISO timestamp of the last successful destination resolution. *(machine-written)* | | `tracker.resolved.scopeResolvedAt.destination.statusIds` | string | ISO timestamp of the last successful destination.statusIds resolution. *(machine-written)* | | `tracker.resolved.scopeResolvedAt.destination.stateIds` | string | ISO timestamp of the last successful destination.stateIds resolution. *(machine-written)* | | `tracker.resolved.scopeResolvedAt.capabilities` | string | ISO timestamp of the last successful capabilities resolution. *(machine-written)* | | `tracker.resolved.resolvedAt` | string \| null | Non-null only when all required destination fields, required normalized slots, and capability booleans are present. *(machine-written)* | ## Environment overrides A few knobs are runtime environment variables rather than config keys: | Variable | Effect | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FLOW_ACTOR` | Actor identity for claims/receipts. Wins over git email, git name, `$USER`. | | `FLOW_REVIEW_BACKEND` | Per-invocation review backend override (bare or `backend:model:effort` spec form). | | `MAX_REVIEW_ITERATIONS` | Session override for `review.maxIterations` (the config key is the durable form). | | `FLOW_PR_CREATE_CMD` | make-pr’s PR-create seam for App/bot-authored PRs. | | `FLOW_AUTONOMOUS=1` | Question-suppression for autonomous drivers. | | `TYPESAFE_API_KEY` | Turns on the [optional Jev judgments](https://flow-next.dev/guides/jev-judge/); read at call time only, never written to config or receipts. `judge.enabled=false` forces them off. | | `JIRA_BASE_URL` / tracker tokens | Tracker transport credentials and endpoint overrides. | | `FLOW_NO_DEPRECATION=1` / `FLOW_NO_AUTO_MIGRATE=1` | Silence deprecation notices / disable auto-migration of legacy layouts. | Precedence where both exist: explicit CLI flag → environment → `.flow/config.json` → built-in default. ## Team defaults Set policy where the team can inspect it - the config file is committed, so `flowctl config set` IS the policy record. The decisions worth making explicitly as a team: the review backend (cross-family beats same-family), `review.maxIterations`, whether `planSync.crossSpec` is worth the reconciliation time at your spec volume, the tracker `perEvent` map (which lifecycle moments project), and the autonomy posture (`pilot.autonomy`, and `land.mergeVerdictCommand` on repos with no branch protection). Everything else has a sane default.