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.

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.

  1. Write it down as an idea. i on the board, or npx 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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:

HeadingSay
ChecksThe commands that must pass before a pull request: tests, build, lint.
Pull requestsHow titles and descriptions look, and what the description must hold.
DirectionWhat the project is and isn’t; what needs your decision first.
BuildingHow to build here: where tests go, conventions, which skills to use.
Dependency updatesWhat extra to run when an update touches certain packages.
Never shareWhat 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

#Keep the review load low

The point of the board is that you merge and the agents do the rest. Protect your attention:

#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

  1. Run the guide and get every Connections row to Working.
  2. Fill in the agent prompt and AGENTS.md, and make your checks fast.
  3. Install the plugin in Claude Code, so your own sessions claim and hand over through the board.
  4. Add five small tasks with briefs and done-whens. Start one agent by hand and watch its live output.
  5. Merge the first pull request. Notice what the agent got wrong, and put the lesson in AGENTS.md, not in the next task.
  6. Turn on Start the next few for a single area, then widen it.
  7. Write your first idea, read the spec it returns, and merge it.
  8. Chase the feature it made, with parallel at 1. Watch the peloton, answer Needs you, and raise parallel once you trust it.