Flow v5.0.0

Guide · about 15 minutes of your time

Your first merged PR

From an empty Flow install to one pull request an agent built, CI checked and you merged. Each step ends with what you should see, so you always know it worked.

Before you start

Set up

In your repo, tell your agent:

Set up Flow: getflow.now/start

It asks whether the repo is new or existing, reads your repo, proposes the commands and settings for .flow/config.yml, and asks you to confirm. Nothing is guessed.

You should see
  • New files: .flow/, CLAUDE.md, AGENTS.md and .github/workflows/flow-*.yml.
  • A short list of GitHub settings the agent can’t change for you.

Do those settings now. Two matter on day one: workflow permissions set to Read and write, and the FLOW_PAT secret. The docs list them all.

If you don’t
  • The agent stops and asks a question: that is by design. Answer it; it doesn’t carry on guessing.
  • It can’t fetch the page: paste the contents of getflow.now/start into the chat instead.

Write your vision

Every task has to say which of your goals it serves, so the goals come first. Tell your agent:

Write our VISION.md with vision-writer.

It interviews you: what you want, what you deliberately don’t, and what progress looks like. It writes down your words, not its own.

You should see
  • A pull request titled [vision] … adding VISION.md, with goals numbered G1, G2… and non-goals NG1…

Read it and merge it. Merging is your approval.

Ask for your first task

Pick something small with a visible result. Tell your agent:

Write a task with task-writer: let users export their notes as Markdown.
You should see
  • A new file in .flow/tasks/, e.g. shop-0001-export-notes.md, committed to main, with status: ready.
  • Inside it: the goal it serves, the files it touches, what it deliberately won’t touch, and acceptance criteria, each one something a test can prove.

Read it. This is your first touchpoint. If a criterion is vague or the scope is wrong, say so now and the agent rewrites it before anyone starts.

Start it, and watch

Open a fresh agent session (one task per session keeps it sharp) and say:

Work the next ready task.
You should see
  • A commit on main setting the task to in_progress, with the session as owner.
  • A draft pull request titled [shop-0001] … on a flow/ branch.
  • The agent runs the gate’s commands itself first, and marks the PR ready only once they pass. Then the gate runs in CI (build, lint, tests, coverage, and a scope check against touches) and the task flips to in_review.
  • Once the gate passes, three reviewers (qa, code-review, and security if the diff warrants it) post their verdicts as comments, followed by one guide comment saying where to look. A red gate starts no reviewer.
If you don’t
  • No reviewers appear: they need automation switched on (CLAUDE_CODE_OAUTH_TOKEN plus FLOW_AI=true). The gate still runs without them.
  • The task flips to blocked: the agent hit a decision that’s yours. See answering a blocked task.
  • A check goes red: ask the agent to fix it on the same branch, or turn on auto-fix so it happens without you. See when a reviewer fails a PR.

Merge

Your second touchpoint. Open the PR and read three things:

  • The description: every acceptance criterion ticked, with the test that proves it named beside it. If the change is something you can see, screenshots or a short recording come first; if the agent couldn’t capture it, one line says why.
  • The reviewers’ comments: what they checked and why they passed.
  • The diff, if you want to. The gate already held it to the declared scope.

Merge it. The merge is always yours.

You should see
  • The task flips to done on main, automatically.

Runners that keep the work moving

Flow ships as a set of small GitHub Actions workflows. The gate and task tracking are the core, installed by default. The rest are optional, and the unattended ones (dispatch, triage, review and auto-fix) stay off until you switch them on.

RunnerRunsWhat it does
Gate coreevery pull request out of draftBuild, lint, tests, coverage and scope on every PR, from the moment it leaves draft. It fails loudly, and a failure can’t be talked around. Drafts aren’t gated, so work in progress doesn’t spend your Actions minutes.
Status and done corePR opened, ready, mergedThe task file follows the PR: in progress, in review, done. Your backlog is always accurate without anyone updating it.
Open PRevery push to a task branchOpens the pull request as a draft the moment an agent pushes, so a stalled session can’t strand finished work.
Dispatcha task becomes ready, plus a daily sweepStarts a Claude Code routine on the next ready task, one that runs on the model the task asks for. The agent works in Anthropic’s cloud, so it spends no Actions minutes. At most three tasks are in progress at once unless you change it. It starts nothing until you set up a routine. Set each routine’s model yourself, or it won’t run on the tier you meant.
Reviewafter the gate passesThree independent reviewers on every PR: QA, code review, and security when the change touches sensitive paths. Each runs in a clean session that never saw the code being written. Then one comment tells you where to look.
Auto-fixa review check failsOpt-in. Sends one agent to fix the reviewers’ findings on the same PR, up to three rounds. It never auto-fixes a security failure or weakens a test; anything it can’t fix arrives as one decision card.
Triageweekday morningsReads new issues and posts a proposed task spec on each one. Add an “approved” label, even from your phone, and it becomes a ready task. It only listens to people who can already direct the repo.
Unblockafter a mergePuts a blocked task back to ready once everything it waits on has merged.
RecoverdailyFinds tasks stuck mid-flight, such as a crashed session or a PR with no status, and puts them back where they belong. A task whose run produced nothing moves up a model.
CompassweeklyA read-only audit of recent work against your stated goals. It flags drift before it becomes a direction.
SyncweeklyWhen a new Flow version is out, it opens a PR with the update. You review it like any other change.

If ready tasks need a model you have no routine for, Dispatch opens one issue saying so, and closes it once that routine runs.

The other jobs run on GitHub’s runners. For a private repo, running them on your own servers costs less: recipe.

What next