Automation

An issue type’s Automation table says who to dispatch at each state. Automation is the part of Bonsai that acts on that table. You don’t click Dispatch by flow at every step: as soon as an issue enters an Agent’s turn state, Bonsai sends that row’s role to your computer. When the role is done and hands the issue to the next state, the next role goes out, until the issue reaches Your turn and waits for you.

Before it can run

Automation needs three things. Without any one of them, nothing moves:

• A type note. The issue’s type: matches a note in 7_Self/_Templates/Issue/ with an Automation table. Create built-in types on the Issue types page (account menu) adds Goal, Feature, Bug and Task.
• Role notes. Every name in the table’s action column needs a note in 7_Self/_Agents/. With no roles at all, the dispatch panel on an issue’s page says “No roles yet”; Create the built-in roles adds writer, reviewer, deployer and distill. Only you can write these two folders, from the web; agents can’t.
• A runtime. A connected computer that has the project’s repository. Your personal space can use every project on it; another space needs it enabled for that space on the Runtimes page.

When it dispatches

Only two events make Bonsai check whether a next step is due:

1. You change the state: drag a card on the board, change it on the issue page, or answer a decision.
2. A run ends: the runtime reports that a run on this issue has stopped.

The check is the same every time:

• The issue still has an unfinished run → nothing. One issue has at most one run at a time, because two agents can’t write to the same worktree.
• The state is in Agent’s turn and has a row in the Automation table → dispatch that row’s role.
• You just moved the issue into a Closed state that has a row (Done → distill) → dispatch it, so what’s worth keeping is written back to the project notes.
• Anything else (Todo, Your turn, no row, no type note) → nothing; it waits for a person.

Changing the status on the web, from a board card or from the field header on the issue page, triggers the check right away. An AI changing the state with update_issue from a chat does not trigger a dispatch. Approving and handing back are clicks on the web.

Done, off track, or out of rounds

When a run ends, Bonsai looks only at the resulting state. It doesn’t judge the quality of the work:

“Handed to a person” means the type’s Your turn state named Needs Decision, or Needs Human, or failing both the first Your turn state. The reason is the last line of the issue’s ## Log. Bonsai wrote that line on your behalf, so like any other AI change its summary sits at the top of the issue and under You should know in your Inbox until you mark it seen.

Automatic dispatch and Dispatch by flow take the same path: same role, same round count, and the run record shows who dispatched it.

A Goal drives its children

A Goal has child issues (their front matter says goal: <Goal number>). The Goal writes no code itself; automation does three things for it:

1. Start on approval. A Goal counts as approved once it leaves its type’s first state (for the built-in Goal, Draft → Approved). It then moves to In Progress.
2. Start children that aren’t blocked. A child in Todo whose blocked_by issues are all closed moves to its type’s first agent state (Developing for Feature) and its role is dispatched. Lowest number first, with at most max_parallel children on an agent’s turn at once, 2 by default. Each time a child moves on, Bonsai checks again whether another one can start.
3. Close when the children are closed. When every child is closed, the Goal moves to its first Closed state (Done).

A few details:

• A child sitting in a state named Blocked is held by something outside the project; automation never moves it for you.
• Write blocked_by as comma-separated numbers: blocked_by: 21, 22. A number that points to no issue counts as still blocking.
• max_parallel lives in the Settings table of the project’s Issues/Issues.md:

## Settings

| key | value |
| --- | --- |
| max_parallel | 3 |

To split a Goal into children, see Planner.

Where you step in

Automation only moves forward during an agent’s turn. It never:

• approves a Goal for you;
• moves an issue out of Your turn (PR review, staging checks and decisions are yours);
• sets an issue to Canceled or Duplicate;
• retries a failed run on its own.

Each of these shows up as an item in your Inbox, or simply stays in the leftmost Your turn column of the board.