Recipes
Everyday jobs
Short, one job each. New to Flow? Start with the guide.
Turn an issue into a task
You have a bug or an idea, and no time to write a spec.
- Open a GitHub issue. A sentence is enough.
- With automation on, the triage sweep (weekdays) reads it and posts a complete draft task as a comment, labelled
proposed. Without automation, tell your agent:Triage issue #12 with task-writer. - Read the draft. Change the label to
approved. The next sweep creates the task asready. - For genuinely mechanical work (typos, dependency bumps) label the issue
auto-okand it skips the proposal step. Only you apply that label.
Answer a blocked task
A task shows blocked.
- Open the task file.
blocked_reasonis the question, in a sentence, and the same question sits inasksas adecision:with the agent’s recommendation.blocked_bylists what it waits on, if anything. - Decide. Write the answer into the task’s
notes, or tell your agent the answer. - Set the task back to
readyonmain. The next session picks it up with your answer in front of it.
When a reviewer fails a PR
A qa, code-review or security check is red.
- Read the reviewer’s comment on the PR. It says what failed and why.
- Tell your agent:
Address the review on PR #34.It fixes every finding on the same branch, runs the gate’s commands, and then pushes once. Each push to a ready PR runs the gate and the reviewers again, so batching the fixes saves runs. - The checks run again on the new commit, and the reviewers start once the gate passes. You don’t re-review anything until they’re green.
- If the agent can’t fix it without a decision, it marks the task
blockedinstead.
To skip step 2 for qa and code-review, set review.auto_fix_rounds: an agent fixes the findings on the same PR, up to three rounds. A red security check is never auto-fixed. Anything it won’t fix arrives as one decision card with the flow:needs-human label.
Asking for changes on a PR
The work passed, but it’s not what you wanted.
- Comment on the PR, as you would to a colleague. That is a kickback.
- Tell your agent:
Address the comments on PR #34.It works on the same branch. - If the ask is outside the task’s declared
touches, the agent won’t silently expand. It will say a new task is needed.
Let Flow start each ready task
You trust the loop and want tasks worked without starting each one.
- In Claude Code, create a cloud routine on this repo for each model your tasks use (Sonnet is the default). Attach no connectors, and save the three-line prompt from the routines runbook. The claude.ai routines page has no duplicate button, so make each routine with New routine and paste the same prompt.
- In each routine, add an API trigger and generate its token. The token is shown once.
- Store the token as the secret
FLOW_ROUTINE_SONNET_TOKENand the trigger id as the variableFLOW_ROUTINE_SONNET_ID. UseHAIKU,OPUSorFABLEfor the other models. Set each routine’s model to the tier in its variable name: Haiku 5.5, Sonnet 5.5, Opus 5.5 or Fable 5.2. A routine with no model set does not run on the tier you meant. - From then on, flow-dispatch starts the routine whenever a task becomes
ready, plus a daily sweep. It runs at most three tasks at once; change that withdispatch.max_in_progress. - To start one now: Actions → flow-dispatch → Run workflow. To pause, delete the
FLOW_ROUTINE_…_IDvariable; ready tasks then wait, and one issue says why.
Use the runbook prompt as it is. flow-dispatch sends only the bare task id, for example flow-0145, as the run’s text. A prompt written to expect <owner>/<repo> <task-id> stops without doing anything.
Run Flow’s GitHub jobs on your own servers
Your repo is private, and its Actions minutes cost too much.
- Check the repo is private. Public repos get GitHub’s runners free, so keep them there. Never point a public repo at a runner you host: anyone’s pull request could run code on it.
- Register self-hosted runners for the repo and give them a label of your choice, such as
hetzner. Any Linux server works. - Give each job a fresh runner that is deleted afterwards. Register with GitHub’s
--ephemeraloption, for example one new container per job. A reused runner lets a PR job leave files behind, and a later job that holds secrets will run them. - Install what your gate commands need.
ubuntu-latesthad a lot preinstalled: database clients, browsers for Playwright, enough memory or swap for type-checking. Check therun:steps in your workflows. - Set the repo variable:
gh variable set FLOW_RUNNER -b <label>. Every Flow job now runs on your runners. To undo, delete the variable, and jobs go back toubuntu-latest.
If you script runner registration, every GitHub API call from your servers counts against your personal rate limit of 5,000 an hour. Poll slowly and send conditional requests with an ETag, or CI stops for everyone. The token your servers register with needs Administration: Read and write on the repo. If it expires, runners stop registering and jobs wait in the queue. They don’t fail, and waiting costs nothing. FLOW_RUNNER reference.
Update to a new Flow release
A new version of Flow is out.
- Within your major version, do nothing. flow-sync runs weekly and, if your repo is behind, opens a pull request with the update.
- Review it like any other PR, and merge it. It never merges itself or pushes to
main. - To check now: Actions → flow-sync → Run workflow.
FLOW_PATneeds Workflows: Read and write for this to work. - A new major (
@v4to@v5) never arrives on its own. Repinflow-sync.ymlto@v5and merge that first, then rungh workflow run flow-sync.yml -f canonical_ref=v5. Merge the PR it opens: it updates every caller and deletesflow-review.yml. Details.