Issue types

In Bonsai, a project’s issues are notes too, at <project>/Issues/<number>.md. Each card on the board is one of these notes.

Which states an issue goes through, who acts at each state, and what its body looks like when it’s created aren’t written into every issue. They come from the issue’s type, and a type is a plain Markdown note. You can read it, and agents follow it.

What works today. The Issue types page in the account menu manages your types: edit states, and pick a role, runtime, next and round limit for each Agent’s turn state. It can also create Goal, Feature, Bug and Task from the built-in templates. As soon as an issue reaches an Agent’s turn state, Bonsai sends that row’s role to your own computer and hands the issue on when it’s done; see Automation. Dispatch by flow on an issue’s page still sends one step by hand.

Three notes, three jobs

That keeps issues light. An issue records facts, not “which model this time” or “which machine”. To change a model, edit the role note. To change the process, edit the type note. Every issue of that type follows.

What a type note looks like

This is the built-in Feature type, at 7_Self/_Templates/Issue/Feature.md. The file name, Feature, is the value an issue writes in its front matter as type:.

# Feature

## Workflow

| Todo | Agent's turn | Your turn | Closed |
| --- | --- | --- | --- |
| Backlog, Blocked, Ready | Developing, Reviewing, Revising, Deploying to Staging, Deploying to Production | Review PR, Verify Staging, Needs Decision | Done, Canceled, Duplicate |

## Automation

| state | action | runtime | next | limit |
| --- | --- | --- | --- | --- |
| Developing | writer | | Reviewing | |
| Reviewing | reviewer | | Review PR, Revising | 3 |
| Revising | writer | | Reviewing | |
| Deploying to Staging | deployer | | Verify Staging | |
| Deploying to Production | deployer | | Done | |
| Done | distill | | | |

## Template

## Description

<Links to the notes a worker must read: [[…]]>

### Goal

<What to do and where the boundary is>

...

Three sections, read top to bottom.

Workflow: the states

A table with a single row. The headers are the four built-in Turns: Todo, Agent’s turn, Your turn and Closed, which say whose move it is. Each cell lists this type’s states under that Turn, in order, separated by commas.

Name states however you like. A Bug can start in Triage and be closed as Won’t Fix. The Turns are what line different types up on one board: whatever the states are called, the board’s columns follow these four, with Your turn on the left.

Automation: who acts at each step

Each row says: when an issue reaches state, send the role named in action to work on it.

Read out loud, the table above says: when development starts, send writer to write the code and open a PR. In Reviewing, send reviewer, for at most three rounds; if it passes, the PR comes to you, and if not, back to writer. Once you merge, deployer ships to staging, waits for you to check it, then ships to production. When it’s done, distill writes what’s worth keeping back into the project’s notes.

Every Agent’s turn state has a row; Todo and Your turn states can’t have one. On your turn, agents don’t go further: they wait for you. A Closed state may have a row, such as distill on Done, but its next is empty: once work is closed it goes nowhere else.

There’s no model column. Models belong in role notes, because the role is the description of who does the work and how.

Template: where a new issue starts

Everything from ## Template to the end of the note is the skeleton of a new issue of this type. When an agent creates a Feature with create_issue and gives no body, this is the body. You edit this section in the note editor; the Issue types page covers the two above.

The built-in template has four sections:

• Description: links to the notes to read first, what to do, why now, and testable acceptance criteria. The acceptance criteria are your spec for the agents: the reviewer checks them one by one, and agents can’t rewrite them.
• Decisions: what needs your call. One heading per decision, a few options under it, the agent’s recommendation marked, and always a last option, Other. Picking an option on the issue page is your decision.
• You should know: a few lines the agent leaves you after each run. Mark one “worth remembering” and distill writes it back into the project’s notes.
• Log: who did what in each round, append only. Review rounds go here too.

Roles

The name in action points at a role note, such as 7_Self/_Agents/reviewer.md:

---
harness: codex
model: gpt-5.4
---

# reviewer

You review the PR of this issue. Read the issue and the PR diff, run the
tests in the workspace, and judge each acceptance criterion with evidence…

The heading is the role’s name, the body is the instruction to the agent, and the front matter can name a harness and a model. Bonsai ships four templates: writer, reviewer, deployer and distill. If you have no roles yet, click Create the built-in roles in the dispatch panel on an issue’s page. Once created they’re your own notes: change them freely, or add new roles.

Writing code and reviewing it can go to different models. That’s one line in each of two role notes.

People stay in the loop

Type notes hand the repetitive steps to agents, but some things always stay with you:

• Approval. A Goal’s plan starts only after you approve it.
• Reviewing the PR and checking staging. Review PR and Verify Staging are on your turn. After writing, reviewing and deploying to staging, agents stop until you’ve looked.
• Judgement calls. When an agent needs your call, it writes it under Decisions and moves the issue to Needs Decision. If writer and reviewer can’t agree within limit rounds, that step stops being sent and the next move is yours.
• Closing. The workflow never cancels an issue or marks it a duplicate for you.
• The rules. Type notes and role notes live in folders that start with _. No agent permission can write there; only you can, on the web.

An issue’s owner is one person, and stays the same; a new issue without one takes the project note’s owner. The “whose turn” shown on a board card is computed: the row’s role on the agent’s turn, the owner on yours.

Why types live in your own space

Types are global. Every project and area you see, your own or shared with you, reads its issues through the same set of types. A type stands for a fixed way of working, so it shouldn’t be copied into every project.

They live in 7_Self because what they point at is already yours: action names your roles, and runtime names your computers.

It also means that in a shared project, two people with different types each see the board according to their own set.

When there are no type notes

Until you create a type note, Bonsai looks for a Workflow table in the project’s Issues/Issues.md, and failing that uses a built-in set of default states. Create built-in types on the Issue types page adds Goal, Feature, Bug and Task, which are ordinary notes from then on.

Older type notes that still use the five columns Backlog, Todo, In Progress, Done and Canceled are mapped onto the four Turns when Bonsai reads them, so they don’t need editing.

Not in the sidebar

Issues, types and roles are notes used as data, and each has its own entry point: issues on the board, types on the Issue types page, roles in an issue’s dispatch panel. So the note tree on the left doesn’t list project and area Issues/ folders, or any template: a note with a path segment starting with _ (7_Self/_Templates/, 7_Self/_Agents/) or named Template.md. Search and direct links still open them.