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
- A GitHub repo, new or existing, that you can change settings on.
- A coding agent that can read a web page and run commands in that repo: Claude Code, Codex, Cursor or similar.
- For an existing repo: a test command and a coverage command. Flow’s gate checks your tests; if the repo has none, Flow has nothing to check yet.
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.
- New files:
.flow/,CLAUDE.md,AGENTS.mdand.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.
- 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.
- A pull request titled
[vision] …addingVISION.md, with goals numberedG1,G2… and non-goalsNG1…
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.
- A new file in
.flow/tasks/, e.g.shop-0001-export-notes.md, committed tomain, withstatus: 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.
- A commit on
mainsetting the task toin_progress, with the session as owner. - A draft pull request titled
[shop-0001] …on aflow/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 toin_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.
- No reviewers appear: they need automation switched on (
CLAUDE_CODE_OAUTH_TOKENplusFLOW_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.
- The task flips to
doneonmain, 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.
| Runner | Runs | What it does |
|---|---|---|
| Gate core | every pull request out of draft | Build, 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 core | PR opened, ready, merged | The task file follows the PR: in progress, in review, done. Your backlog is always accurate without anyone updating it. |
| Open PR | every push to a task branch | Opens the pull request as a draft the moment an agent pushes, so a stalled session can’t strand finished work. |
| Dispatch | a task becomes ready, plus a daily sweep | Starts 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. |
| Review | after the gate passes | Three 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-fix | a review check fails | Opt-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. |
| Triage | weekday mornings | Reads 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. |
| Unblock | after a merge | Puts a blocked task back to ready once everything it waits on has merged. |
| Recover | daily | Finds 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. |
| Compass | weekly | A read-only audit of recent work against your stated goals. It flags drift before it becomes a direction. |
| Sync | weekly | When 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
- Turn ideas and bugs into tasks through GitHub issues: recipe.
- Let Flow start each ready task for you: recipe.
- Tune what the gate checks: configuration reference.