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"]
project:
name: "API"
language: "python"
description: "Billing API"
commands:
install: "uv sync --frozen"
build: "uv run python -m compileall -q src"
lint: "uv run ruff check ."
test: "uv run pytest"
coverage: "uv run pytest --cov=src --cov-fail-under=80"
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: "uv run ruff check src"
runtime: "none" # uv brings its own Python
review:
security_paths: ["src/auth/**", "pyproject.toml", "uv.lock"]
project:
name: "SVC"
language: "go"
description: "Ingest service"
commands:
install: "go mod download"
build: "go build ./..."
lint: "go vet ./..."
test: "go test ./..."
coverage: "go test -coverprofile=c.out ./... && go tool cover -func=c.out | awk '/^total:/ { if ($3+0 < 80) exit 1 }'"
coverage_min: 80 # MEASURE: your current coverage, minus a margin
source_roots:
- path: "cmd/"
check: "go vet ./cmd/..."
runtime: "none"
- path: "internal/"
check: "go vet ./internal/..."
runtime: "none"
review:
security_paths: ["internal/auth/**", "go.mod", "go.sum"]
project:
name: "APP"
language: "typescript"
description: "Next.js app with Supabase edge functions"
commands:
install: "npm ci"
build: "npm run build"
lint: "npm run lint"
test: "npm test"
coverage: "npm run coverage"
coverage_min: 80 # MEASURE: your current coverage, minus a margin
source_roots:
- path: "app/"
check: "npm run lint"
- path: "supabase/functions/" # a second runtime the app build never parses
check: "deno check supabase/functions/**/*.ts"
runtime: "deno"
retry: 1 # remote module fetches can be flaky
review:
security_paths: ["app/api/**", "supabase/**", "package.json", "package-lock.json"]
Every command must exit non-zero on failure. The gate and the reviewers trust exit codes, not output.
project
| Key | Required | Default | What it does |
|---|---|---|---|
project.name | yes | — | Short slug. Also the task-id prefix: name: "SHOP" gives SHOP-0001. |
project.language | yes | — | e.g. typescript, python, go. Context for agents and reviewers. |
project.description | yes | — | 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>.
| Key | Required | Default | What it does |
|---|---|---|---|
commands.install | yes | — | Install dependencies. Prefer a strict install (npm ci, uv sync): a half-updated lockfile passes a lenient local install and fails the gate. |
commands.build | yes | — | Build or type-check. |
commands.lint | yes | — | Lint. Errors fail the gate; warnings are noted in the PR. |
commands.test | yes | — | Run the tests. |
commands.coverage | yes | — | 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
| Key | Required | Default | What it does |
|---|---|---|---|
coverage_min | yes | 80 in the template | Coverage 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.2 | no | false | Set 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_max | no | 50000 | Byte 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.0 | no | off | At 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.
| Key | Required | Default | What it does |
|---|---|---|---|
path | yes | — | Folder, e.g. "app/". |
check | yes | — | Command that parses or lints it, run from the repo root. Put install steps inside it: "cd mcp && npm ci && npm run build". |
runtime | no | node | node, deno or none (no setup step; use when the check installs its own toolchain). |
version | no | 22 (node), v2.x (deno) | Runtime version to install. Ignored for none. |
retry | no | 0 | 0 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
| Key | Required | Default | What it does |
|---|---|---|---|
source_roots_ignore | no | [] | 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.
| Key | Required | Default | What it does |
|---|---|---|---|
security.secrets_scan | no | true | No credentials, tokens or keys committed. |
security.dependency_audit | no | true | Audit dependency changes (npm audit, pip-audit). |
security.focus | no | three generic items | Extra 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.
| Key | Required | Default | What it does |
|---|---|---|---|
review.model | no | claude-sonnet-5-5 | Model 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.3 | no | claude-opus-5-5 | Model for code-review only. Leave it unset; a set value warns on every PR, like review.model. |
review.security_model | no | claude-opus-5-5 | Model for security only. Leave it unset; a set value warns on every PR, like review.model. |
review.max_diff_bytes | no | 300000 | How 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.1 | no | off | Opt 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_paths | no | [] | 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.
| Key | Required | Default | What it does |
|---|---|---|---|
dispatch.max_in_progresssince 4.0 | no | 3 | Dispatch 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
| Key | Required | Default | What it does |
|---|---|---|---|
git.base_branch | no | main | Where task state lives and PRs merge. |
git.branch_prefix | no | flow/ | 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_main | no | true | Never 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.
| Key | Required | Default | What it does |
|---|---|---|---|
intents.required_fromsince 3.2 | no | unset | The 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.
| Field | Set by | What it is |
|---|---|---|
id | agent | <project.name>-<number>, allocated first-push-wins so two agents never collide. |
title | agent | One imperative line. |
status | agent, workflows | ready → 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. |
priority | you | 1 (drop everything) to 5 (whenever). |
project, created | agent | The project slug, and the date the task was written (YYYY-MM-DD). |
serves | agent | The VISION.md goal ids this advances, or maintenance. A ready task must name one. |
intentsince 3.2 | agent | The 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. |
touches | agent | Path globs the task may change. CI fails a PR that strays outside them, and two tasks with overlapping touches never run at once. |
owner, started | agent | Set on claim. started is a full UTC timestamp. |
branch, pr | workflows | Recorded when the PR opens. |
blocked_reason, blocked_by | agent | The 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.5 | you, agent | Required when status is cancelled: why the work will never ship. |
issue | triage | The GitHub issue it came from, if any. |
model, effort, model_reasonsince 3.4 | agent | Optional. 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. |
labels | agent | Optional tags, e.g. [frontend, infra, spike]. |
notes | anyone | Append-only log of handoffs and kickbacks, for the next session. |
askssince 3.1 | agent | What 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.
| Setting | Where | Why |
|---|---|---|
| Workflow permissions: Read and write | Settings → Actions → General | The status workflows push task state to main. Without it they fail at startup. |
FLOW_PAT secret | Settings → Secrets → Actions | Fine-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 access | Settings → Actions → General → Access | Only if the Flow workflows you call live in a private repo. |
CLAUDE_CODE_OAUTH_TOKEN and FLOW_AI=true | Secrets, Variables | Optional. 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 variable | Secrets, Variables | Optional, 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 protection | Settings → Rules | Org 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.
| Variable | Values | What it does |
|---|---|---|
FLOW_AI | true, or unset | Master switch for everything that spends model quota on GitHub Actions: the reviewers, triage, recover, compass and auto-fix. |
FLOW_ROUTINE_<TIER>_IDsince 4.0 | a routine’s trigger id | The 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.4 | a runner label, or unset | Runs 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.
| Caller | Must grant | Without it |
|---|---|---|
flow-gates.yml, job flow-reviewsince 5.0 | contents: read, pull-requests: write, issues: read, id-token: write | The 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.0 | contents: write, pull-requests: read | In 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.yml | contents: write, pull-requests: read | A task blocked on a PR url is never released when that PR merges. |
flow-dispatch.yml | contents: read, issues: write | Dispatch can’t open the issue that says a model has no routine. |
flow-kickback.yml | contents: read, pull-requests: write, issues: write, actions: read, id-token: write | Auto-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.