Flow v5.0.0

Reference · Flow v5.0.0

Configuration

Everything you set when Flow is in your repo. Most of it is one file, .flow/config.yml. The protocol is identical in every repo; this file is the only part that changes per stack.

.flow/config.yml

A complete starting file for your stack. Copy it, then replace every value marked MEASURE or that names your own paths. Your agent does this from the real repo when it follows /start.

project:
  name: "SHOP"                # task ids become SHOP-0001…
  language: "typescript"
  description: "Storefront and checkout"
commands:
  install:  "npm ci"
  build:    "npm run build"
  lint:     "npm run lint"
  test:     "npm test"
  coverage: "npx c8 --check-coverage --lines 80 npm test"
coverage_min: 80              # MEASURE: your current coverage, minus a margin
coverage_runs_tests: true     # coverage already runs every test, so the gate skips its Test step
source_roots:
  - path: "src/"
    check: "npm run lint"
review:
  security_paths: ["src/auth/**", "src/api/**", "package.json", "package-lock.json"]

Every command must exit non-zero on failure. The gate and the reviewers trust exit codes, not output.

project

KeyRequiredDefaultWhat it does
project.nameyes—Short slug. Also the task-id prefix: name: "SHOP" gives SHOP-0001.
project.languageyes—e.g. typescript, python, go. Context for agents and reviewers.
project.descriptionyes—One line on what the project is.

commands

The five commands the gate runs on every pull request, from the repo root. Drafts aren’t gated: the gate runs when a PR leaves draft and on every push after that, and a newer push cancels the run it replaces. The agent runs these same commands before it marks a PR ready. To gate a draft in CI anyway: gh workflow run flow-gates.yml --ref <branch>.

KeyRequiredDefaultWhat it does
commands.installyes—Install dependencies. Prefer a strict install (npm ci, uv sync): a half-updated lockfile passes a lenient local install and fails the gate.
commands.buildyes—Build or type-check.
commands.lintyes—Lint. Errors fail the gate; warnings are noted in the PR.
commands.testyes—Run the tests.
commands.coverageyes—Print a coverage % and exit non-zero under the threshold, e.g. pytest --cov --cov-fail-under=80.

The gate only checks what these commands reach. If the repo has more than one runtime (an app plus edge functions, a frontend plus a worker), cover each one in source_roots.

Limits

KeyRequiredDefaultWhat it does
coverage_minyes80 in the templateCoverage floor. The gate fails below it. A backstop, not the real check: the qa reviewer maps every acceptance criterion to a test. Raise it over time; never lower it to go green.
coverage_runs_testssince 4.2nofalseSet it to true only when commands.coverage runs every test that commands.test runs and fails when a test fails (c8 node --test, vitest run --coverage, pytest --cov). The gate then skips its separate Test step, so the suite isn’t run, and billed, twice. A failing test still fails the gate.
claude_md_maxno50000Byte ceiling on CLAUDE.md plus everything it imports (the protocol counts). Over it fails the gate with a per-file breakdown. Measure yours with node .flow/bin/check-claude-md.mjs and set it with headroom. Removing the key reports the total but enforces nothing.
queue_capsince 3.0nooffAt most this many tasks may be ready at once; the next one is refused before anything is written. Only a human-applied urgent label bypasses it.

source_roots

Every folder that holds source, and the command that parses it. flow-doctor fails a PR if a declared root is missing or has no check, or if a top-level source folder isn’t declared at all, so a new runtime can’t slip in ungated.

KeyRequiredDefaultWhat it does
pathyes—Folder, e.g. "app/".
checkyes—Command that parses or lints it, run from the repo root. Put install steps inside it: "cd mcp && npm ci && npm run build".
runtimenonodenode, deno or none (no setup step; use when the check installs its own toolchain).
versionno22 (node), v2.x (deno)Runtime version to install. Ignored for none.
retryno00 to 3 extra attempts, for a flaky external dependency only. Capped so a broken check can’t pass as flaky.

A check that is already one of the commands isn’t run twice. Any unknown field is an error naming the entry.

source_roots:
  - path: "app/"
    check: "npm run lint"
  - path: "supabase/functions/"
    check: "deno check supabase/functions/**/*.ts"
    runtime: "deno"
    retry: 1
KeyRequiredDefaultWhat it does
source_roots_ignoreno[]Top-level folders that hold source-looking files but are deliberately not gated, e.g. ["docs"]. Bare folder names only. Ignoring a folder is a decision you are recording; prefer a real check.

security

What the security reviewer checks on top of its general review.

KeyRequiredDefaultWhat it does
security.secrets_scannotrueNo credentials, tokens or keys committed.
security.dependency_auditnotrueAudit dependency changes (npm audit, pip-audit).
security.focusnothree generic itemsExtra scrutiny areas for this project, e.g. "row-level security policies", "OAuth token handling".

review

The three reviewers (qa, code-review, security) run as checks on the pull request, never inside the agent’s own session. They are the flow-review job of flow-gates.yml and start only once the gate has passed, so a red or cancelled gate costs no review. The checks are named flow-review / qa, flow-review / code-review and flow-review / security. What they read and when they run is set here. Which models they run on is not: Sonnet for qa, Opus for code-review and security, set by Flow for every repo.

Coming from v3.2 or earlier? Delete review.model, review.code_review_model and review.security_model from .flow/config.yml if they are there, then re-run flow-sync. Until you do, every PR’s plan summary warns once per key.

KeyRequiredDefaultWhat it does
review.modelnoclaude-sonnet-5-5Model for qa and the review guide. Leave it unset: reviewer models come from Flow itself, so a model change reaches every repo with the next sync. Setting it still works, but every PR’s plan summary warns that it overrides the default.
review.code_review_modelsince 3.3noclaude-opus-5-5Model for code-review only. Leave it unset; a set value warns on every PR, like review.model.
review.security_modelnoclaude-opus-5-5Model for security only. Leave it unset; a set value warns on every PR, like review.model.
review.max_diff_bytesno300000How much of the diff the reviewers read. Past it the diff is cut and all three refuse to pass. Raise it only to fit the PRs you actually open: each byte is read up to three times. Max 2,000,000. Read from the base branch, so a PR can’t raise its own limit.
review.auto_fix_roundssince 3.1nooffOpt in to auto-fix: a failed qa or code-review check sends one agent to fix the findings on the same PR, then the reviewers run again from scratch. At most this many rounds per PR; hard maximum 3 (a larger value is clamped, with a warning). Needs FLOW_AI=true and FLOW_PAT. Never auto-fixes a failed security check, never pushes a round that removes a test or an assertion, never merges. The fixing agent never holds FLOW_PAT: a separate job that runs no model checks the round and pushes it. Anything it won’t do posts one decision card and adds the flow:needs-human label; remove the label to re-arm the PR.
review.security_pathsno[]Globs that trigger the security review, e.g. "src/auth/**", "package.json". Otherwise it is skipped, with the reason shown. Empty means it runs on every PR, not that it is off.

dispatch

How many tasks run at once when flow-dispatch starts a Claude Code routine on each ready task. See letting Flow start each ready task for the setup.

KeyRequiredDefaultWhat it does
dispatch.max_in_progresssince 4.0no3Dispatch starts nothing while this many tasks are in_progress. Each run starts at most one task, and each claim starts the next run, so this is how many agents work at once. A value that isn’t a positive whole number fails the run.

git

KeyRequiredDefaultWhat it does
git.base_branchnomainWhere task state lives and PRs merge.
git.branch_prefixnoflow/Branches are flow/<task-id>-<slug>. On a branch you didn’t choose, the [<task-id>] PR-title prefix carries the id instead.
git.protect_mainnotrueNever commit code to the base branch directly. Task-state commits are the only exception.

intents

Optional, and off until you set it. An intent is an outcome you want and why, one file in .flow/intents/, approved by merging its own PR. Once a repo adopts intents, new product tasks name the intent they come from, and the session that writes a task never writes its intent.

KeyRequiredDefaultWhat it does
intents.required_fromsince 3.2nounsetThe day the intent rule starts, "YYYY-MM-DD". A ready task created on or after it that serves anything but maintenance and names no intent gets a flow-doctor warning. Earlier tasks are never asked for one, and nothing is backfilled. Unset: the rule is off. Unset while .flow/intents/ exists: one warning naming this key.
intents:
  required_from: "2026-10-12"

flow-sync never touches your own .flow/tasks/_TEMPLATE.md. When you set this key, add intent: "" to that template too.

Task files

One Markdown file per task in .flow/tasks/, on main. Agents write these with the task-writer skill; you rarely touch the fields by hand.

FieldSet byWhat it is
idagent<project.name>-<number>, allocated first-push-wins so two agents never collide.
titleagentOne imperative line.
statusagent, workflowsready → in_progress → in_review → done, or blocked, or cancelled for work that will never ship. Only the claim and blocked are written by the agent; GitHub workflows set the rest from PR events.
priorityyou1 (drop everything) to 5 (whenever).
project, createdagentThe project slug, and the date the task was written (YYYY-MM-DD).
servesagentThe VISION.md goal ids this advances, or maintenance. A ready task must name one.
intentsince 3.2agentThe id of the intent in .flow/intents/, already on main, that this task derives from. Only in a repo that has adopted intents; otherwise left empty, as it is for maintenance work and tasks older than intents.required_from. flow-doctor fails a ready task naming an id no intent declares, and warns on new product work that names none.
touchesagentPath globs the task may change. CI fails a PR that strays outside them, and two tasks with overlapping touches never run at once.
owner, startedagentSet on claim. started is a full UTC timestamp.
branch, prworkflowsRecorded when the PR opens.
blocked_reason, blocked_byagentThe question for you, and what it waits on (task ids or PR urls). When everything in blocked_by has merged, flow-unblock sets the task back to ready.
cancelled_reasonsince 3.5you, agentRequired when status is cancelled: why the work will never ship.
issuetriageThe GitHub issue it came from, if any.
model, effort, model_reasonsince 3.4agentOptional. The model that builds the task (haiku, sonnet, opus or fable; unset means sonnet) and its effort (low to max; unset means medium). Setting either needs a one-line model_reason. A run that ends without a PR, or a PR closed unmerged, moves the task up one model on its own.
labelsagentOptional tags, e.g. [frontend, infra, spike].
notesanyoneAppend-only log of handoffs and kickbacks, for the next session.
askssince 3.1agentWhat the task needs from you. One string per item, prefixed with its kind: decision: (must carry Recommend:), follow-up: or fyi:. flow-doctor fails a malformed ask. Resolving one removes it and adds a notes line with the answer.
asks:
  - "decision: Store exports in S3 or on disk? Recommend: disk, no new credential"
  - "fyi: the old export endpoint is left in place until SHOP-0014"

The body has four sections: Context, Scope (including what it does not touch), Acceptance criteria (each one observable and testable) and Definition of done (inherited, not edited).

GitHub settings

Flow can’t set these itself. Skipping FLOW_PAT is the dangerous one, because nothing errors.

SettingWhereWhy
Workflow permissions: Read and writeSettings → Actions → GeneralThe status workflows push task state to main. Without it they fail at startup.
FLOW_PAT secretSettings → Secrets → ActionsFine-grained token for this repo only, short expiry, with Contents, Pull requests, Issues and Workflows, each Read and write. Without it, PRs opened by automation skip the gate silently; a token short one permission fails later, at the one step that needed it. Required for auto-fix.
Reusable-workflow accessSettings → Actions → General → AccessOnly if the Flow workflows you call live in a private repo.
CLAUDE_CODE_OAUTH_TOKEN and FLOW_AI=trueSecrets, VariablesOptional. Turns on triage, the PR reviewers, recover, compass and auto-fix. Generate the token with claude setup-token. FLOW_AI=false turns all of them off.
FLOW_ROUTINE_<TIER>_TOKEN secret and FLOW_ROUTINE_<TIER>_ID variableSecrets, VariablesOptional, one pair per model your tasks use (SONNET, OPUS, HAIKU, FABLE). Lets flow-dispatch start a Claude Code routine on each ready task. Without them, nothing starts tasks for you and one issue per model says so. Setup.
Branch protectionSettings → RulesOrg repos: require flow-gates, with GitHub Actions as a bypass actor so state pushes still work. Personal repos: leave it off, because they can’t grant that bypass.

Repo variables

Switches that live in variables rather than in a workflow file, so they survive every sync.

VariableValuesWhat it does
FLOW_AItrue, or unsetMaster switch for everything that spends model quota on GitHub Actions: the reviewers, triage, recover, compass and auto-fix.
FLOW_ROUTINE_<TIER>_IDsince 4.0a routine’s trigger idThe routine flow-dispatch starts for tasks on that model, with its token in the matching secret. Delete it to stop tasks on that model starting on their own.
FLOW_RUNNERsince 3.4a runner label, or unsetRuns every Flow job on that runner instead of ubuntu-latest. Private repos only: a runner you host sees every secret the jobs hold. Recipe.
gh variable set FLOW_AI -b true
gh variable set FLOW_ROUTINE_SONNET_ID -b <trigger-id>
gh secret set FLOW_ROUTINE_SONNET_TOKEN          # paste the routine's token when asked

Workflow permissions in the callers

The flow-*.yml callers carry these grants already. If you hand-edit or hand-repin a caller, keep them: a reusable workflow can’t raise a scope above its caller’s.

CallerMust grantWithout it
flow-gates.yml, job flow-reviewsince 5.0contents: read, pull-requests: write, issues: read, id-token: writeThe reviewers can’t sign in or post their verdicts. This job replaces the old flow-review.yml; delete that file, or the review runs twice on every push.
flow-done.ymlsince 5.0contents: write, pull-requests: readIn a private repo, intents merged before your sync never get their approval stamped. Keep the job’s own permissions: block: without one it gets the repo’s default token.
flow-unblock.ymlcontents: write, pull-requests: readA task blocked on a PR url is never released when that PR merges.
flow-dispatch.ymlcontents: read, issues: writeDispatch can’t open the issue that says a model has no routine.
flow-kickback.ymlcontents: read, pull-requests: write, issues: write, actions: read, id-token: writeAuto-fix can’t tell which review failed or post its card. No contents: write: it never writes to main.

Coming from @v4? Moving to v5 is a deliberate repin, not an automatic sync. Repin flow-sync.yml to @v5 and merge that first, then run gh workflow run flow-sync.yml -f canonical_ref=v5. The PR it opens moves every caller to @v5, adds the flow-review job to flow-gates.yml, grants flow-done.yml its new scope and deletes flow-review.yml. Branch protection doesn’t change: the review checks keep their names. Steps: repinning a consuming repo.

What Flow adds to your repo

CLAUDE.md, AGENTS.md      point every agent at the protocol
VISION.md                 your goals and non-goals; every task names one
.flow/
  config.yml              this page
  PROTOCOL.md             the rules agents follow
  tasks/                  one file per task (lives on main)
  intents/                outcomes you approved, and why
  workstreams/            groups of intents that share a goal (optional)
  bin/                    the helpers CI and agents run
  VERSION                 which Flow release you adopted
.claude/skills/           task-writer, vision-writer, flow-compass, show-me…
.github/workflows/flow-*  thin callers of Flow’s shared workflows
changes/                  one changelog fragment per task (optional)

Updates arrive by pull request from flow-sync; you never edit .flow/bin/ or the flow-* workflows yourself. Full setup steps: getflow.now/start.