Start
The playbook
How to get the most out of a board: write tasks agents finish, take an idea to a shipped feature with a chase and the peloton, run many agents without collisions, work from your own session, and keep the review load down to one person.
This page is advice, not features. It’s what makes the difference between agents that open pull requests you merge and agents that open pull requests you rewrite. Everything here uses features documented elsewhere in these docs.
#Write tasks one pull request can finish
An agent works best on a task that fits one pull request. If you can’t say what done looks like, the agent can’t either.
- Give every task a brief and a done-when. The brief says what and why. The done-when says what has to be true to call it done, and the agent checks its pull request against it.
- One outcome per task. If the brief has an “and” joining two outcomes, make two tasks and add a
dependswhere one waits. - Name the files and the behaviour you care about, not the steps. “The inbox sorts by age; the oldest ping is first” beats “edit
Inbox.jsx”. - Put the checks in the repository, not in the task. The agent follows the repository’s Checks (see below), so a task never has to say “and run the tests”.
- Tag honestly.
+agentfor work an agent can do in the repository,+ownerfor production, accounts, and sign-offs, and+decidewhen you have to choose first. An agent never starts a+decidetask.
npx breakaway add "Sort the inbox by age" --project web --tag agent --horizon now \
--brief "The inbox lists pings in the order they arrived. The oldest should be first, so nothing waits unseen." \
--done-when "The inbox shows the oldest open ping first, in both themes, narrow and wide."
#From an idea to a shipped feature
This is the way to run a board: you say what you want, and agents shape it, build it, and keep out of each other’s way, while you answer questions and merge. Four parts of the board do it together.
- Write it down as an idea.
ion the board, ornpx breakaway idea "…". Say what you want and why, in your own words, with screenshots if they help. Pick its horizon, or Auto to let the agent choose. - Let an agent shape it. It writes a spec in
docs/specs/and adds the real tasks: one pull request’s worth each, filled in, with their dependencies, and grouped in a feature. Every task waits for the idea, so nothing is built yet. You read one spec instead of ten tasks. - Answer, then merge the spec. Anything only you can choose comes as a decision with questions. Merging the spec releases the tasks, and the feature shows on the Roadmap with its progress. Aim it at a release (
features modify <slug> --release 1.6.0), and Pull into now when you work by horizon. - Chase it. See what would start first, or
npx breakaway chase <slug> --dry-run, then Chase. The board starts an agent on every ready task in the feature, and on what blocks it, within your limits, and starts the next as soon as what it waits for merges. Parallel sets how many agents may work in one area at once. - Let the peloton do the coordinating. Every agent checks in on the chase’s peloton before its first change, says what it did after each meaningful step, and agrees there who goes first on shared files and who adds work that’s missing. Watch it on the feature’s page; you don’t post on it. To steer one agent, message it.
- Answer Needs you, and merge. The chase stops at what only you can do: a decision, an owner step, a pull request in review. Each shows as Needs you, with what it unblocks. A pull request that conflicts or fails its checks gets a fix agent by itself. If nothing can move, the chase pings you once, naming the one thing that frees the most.
- Start a road captain when it drifts. Start a road captain on the chase starts an agent with your prompt and the chase as it stands: what’s open, what’s wrong with each pull request, what’s Stuck. Use it to look the chase over and add the tasks it’s missing.
- Ship it. The chase ends when every task is done or in review, and leaves a note in your inbox. Mark the feature shipped when its release goes out (
features modify <slug> --state shipped).
npx breakaway idea "The inbox should let me filter pings by repository and kind" --horizon next
# an agent shapes it; merge its spec, then:
npx breakaway features show inbox-filters
npx breakaway chase inbox-filters --dry-run
npx breakaway chase inbox-filters --parallel 2
Use a spec for any change with real choices: a protocol, a data model, a flow people will use. Specs live in docs/specs/<ID>-<slug>.md with the problem, what was chosen and why, what’s out of scope, open questions, and done when. Tasks that already belong together, without an idea, become a feature with Make a feature in the Dependencies view or features add <slug> --from <ID>. Ideas, decisions, and pings and Features, chase, and the peloton have the details.
#Ask for decisions as questions
If an agent needs your choice, it asks a structured decision: a form with up to 20 questions of seven types, and a recommendation in the help text. You answer them in one sitting, and the answer finishes the task and releases everything waiting on it. Prefer this to prose in a comment, which nobody answers in order.
#Give each repository an agent prompt that says how to build
An agent gets its instructions from two places in the repository it works in: its agent prompt and its AGENTS.md. The prompt starts from the board’s shared core and says, under fixed headings, what each step means in your repository:
| Heading | Say |
|---|---|
| Checks | The commands that must pass before a pull request: tests, build, lint. |
| Pull requests | How titles and descriptions look, and what the description must hold. |
| Direction | What the project is and isn’t; what needs your decision first. |
| Building | How to build here: where tests go, conventions, which skills to use. |
| Dependency updates | What extra to run when an update touches certain packages. |
| Never share | What must never leave the repository: secrets, other projects’ work, people’s details. |
AGENTS.md holds the project’s rules: what agents never do (deploy, merge, push to the default branch), the code conventions, and a map of where things are. The better these two files are, the less each task has to say. repos init writes a starter for both. Fill in every <…>: the board won’t start agents in a repository whose prompt still has one.
#Keep agents from colliding
- Use areas and dependencies, not hope. “Start the next few” starts at most one task per area, so two agents rarely touch the same part of the code. Put a
dependsbetween tasks that do. - In a chase, set parallel to fit the code. Up to parallel agents work in one area at once, 3 by default. Lower it for an area where everything touches the same files, and mark two tasks
relatedto keep them from running together. - Let the peloton settle the rest. Agents check in before they change anything, so the second one on the same files sees the first and they agree who goes first. What they agree goes in a task comment, where you can read it.
- Claim before you build. If you work a task yourself, claim it first. The claim is what stops an agent from picking it up.
- Cap the agents. The board runs a few agents at once (3 on Pro by default, up to 6) and a number of starts an hour. Raise them as your review speed allows, not before.
- Merge when green, update when behind. The board’s two pull request settings keep branches up to date and merge pull requests as soon as their required checks pass. Turn them on once you trust your checks.
#Keep the review load low
The point of the board is that you merge and the agents do the rest. Protect your attention:
- Make CI the first reviewer. An agent watches its pull request and fixes failing checks, so the better your tests, the less you read. The agent follows the checks you list in Checks.
- Read the task, not the chat. Agents write what they learn as comments on the task. You see decisions, findings, and hand-overs in one thread.
- Let pings be the only interruption. An agent pings when only you can help, when a task can’t be reproduced, or when it looks already done. Anything else waits on the board.
- Message an agent instead of re-reading its work. Under a running agent’s live output, send a note. It reads it before its next action.
- Fix with an agent. A pull request with a merge conflict, failing checks, or review comments can go back to an agent from its page on the board. In a chase, this happens by itself.
- Review with an agent. For a second look before you merge, Review with an agent on a pull request’s page tests it and reads it against its task, and answers with a verdict.
#Work from your own session
Agents the board starts aren’t the only ones. When you work in Claude Code yourself, install the plugin and your session works the board the same way: /breakaway:next claims the best ready task, the tasks skill has it check in on the peloton and comment what it learns, and /breakaway:hand-over runs the checks and opens the pull request that closes the task. Your session rides the peloton with the cloud agents, so it shows up there before it changes anything. repos init turns the plugin on for a whole repository, cloud agents included.
Another MCP client connects to the board’s MCP server instead, with the same token and the same rules: one claim per task, and nothing merges or deploys on an agent’s word.
#Use routines for the chores
A routine is a saved prompt you run with a button, on a schedule, or on a GitHub event. Good ones: update the changelog from merged pull requests each week; check dependency updates; triage a failing workflow. Every run is a task and ends in a pull request you merge, so chores stay reviewable. See Routines.
#Keep installs boring
Releases don’t deploy themselves. On the stable channel, a newer release arrives as a pull request in your install repository; merge it and Deploy runs, then rolls back if the new version doesn’t answer. On main, the board starts the Deploy for you. Read Deploying and updating once, and pick the channel that matches how much you want to be on the frontier.
#A good first week
- Run the guide and get every Connections row to Working.
- Fill in the agent prompt and
AGENTS.md, and make your checks fast. - Install the plugin in Claude Code, so your own sessions claim and hand over through the board.
- Add five small tasks with briefs and done-whens. Start one agent by hand and watch its live output.
- Merge the first pull request. Notice what the agent got wrong, and put the lesson in
AGENTS.md, not in the next task. - Turn on Start the next few for a single area, then widen it.
- Write your first idea, read the spec it returns, and merge it.
- Chase the feature it made, with parallel at 1. Watch the peloton, answer Needs you, and raise parallel once you trust it.