Skip to main content
Every branch in ReasonOS has a task board: a kanban board of the work being done on that branch. It appears in the editor’s Branch tasks view, it is shared live by everyone connected to the branch’s node — humans and agents alike — and its cards travel with the branch through git. The board is deliberately narrow in scope. It tracks “work on this branch” — the steps to finish the feature the branch exists for — not company-level project management. Project issues and cycles, and organization initiatives, live in the managed platform’s Work area.
Branch task cards and project Work issues are separate records. The task_list / task_update tools below operate on the branch board; get_task / move_task and the other ReasonOS Work tools operate on project issues. Running an agent on an issue does not copy it into a branch card. If a managed branch already has cards, see Moving existing branch cards into Work.

Tasks travel with the branch

ReasonOS runs one server per branch: each active branch gets its own branch node, and the editor connects to it. Task cards are stored in the committed .reasonos/ tree — one folder of JSON files per branch — so they move through git with the branch itself:
  • Push the branch, and a teammate who joins its node sees the same board.
  • Merge the branch, and its task history lands in trunk as a durable record of the work.
  • Each branch node naturally serves its own branch’s tasks; the board is scoped by construction, not by filtering.
Tasks are rarely created outside a branch; the occasional branchless card goes to a shared backlog folder instead.
This is the opposite arrangement from checkpoints, which are per-node disposable state. Tasks are part of the branch’s durable, committed record.

Working the board in the editor

The branch task board is the primary surface. There you can:
  • Create cards with a title, description, an ordered checklist of steps, and an assignee.
  • Move cards between columns as work progresses. Columns, their colors, and their WIP limits are configurable per workspace (see below).
  • Comment on cards — plain comments or questions — so decisions and context stay attached to the work rather than buried in a chat transcript.
  • Link cards to the plans, memories, and agent chat sessions that produced or concern them.

Run a task with an agent

Every card has a Run with agent action. It starts an agent session seeded with the card — title, description, steps, branch — moves the card to the first “in progress” column, sets the assignee to agent, and links the session to the card. The run then streams through the normal AI chat pane, and the session stays attached to the card so you can reopen it later. While it works, the agent keeps the board truthful using its task tools: checking off steps as it finishes them, moving the card between columns, and commenting when it needs clarification — everyone on the branch sees the updates live.

Mention the agent in a comment

Writing @agent in a card comment has the agent respond in that comment thread. If the mention asks for actual work, the agent does the work first (taking a checkpoint beforehand, so it’s revertible) and then replies summarizing what it did. Ask a question, get an answer; ask for a fix, get the fix and a comment.

Agents read and write the same board

Agent sessions on the branch carry task tools that operate on the very board the editor renders — there is no second source of truth:

Lifecycle: the board reconciles with git

Beyond its column, every card has a lifecycle that ReasonOS derives from git rather than asking you to maintain:
  • active — the branch exists and hasn’t merged; normal state.
  • merged — the branch’s commits are in the default branch. The card records the merge commit.
  • abandoned — the branch is gone (locally and on the remote) without merging.
Reconciliation runs automatically when the board loads, so cards for finished branches close themselves instead of lingering.
Merge detection is ancestry-based: a branch that was squash-merged is not recognized as merged (its original commits never become ancestors of trunk), so its cards stay active until you close them yourself.

Configuring the board: .reasonos/tasks.rbs

The board’s columns and agent behavior are configured by a committed .rbs file at the workspace root: .reasonos/tasks.rbs. With no file, you get the default three-column board (To Do / In Progress / Done).
Because the file is committed, the board layout is shared by everyone on the branch — and by every branch cut from it.

state(...)

Plain strings work as shorthand: states = ["todo", "doing", "done"].

task_config(...)

Customizing the agent prompt

agent_prompt lets a team put its own instructions in front of every agent-run task. Placeholders: {{id}}, {{title}}, {{description}}, {{branch}}, {{steps}} (the checklist with current statuses), and {{tool_instructions}} — the standard block that teaches the agent to keep the board current with the task tools. Include {{tool_instructions}} unless you have a reason not to.
A broken tasks.rbs never takes the board down: the branch node falls back to the default columns and the editor surfaces the configuration error so you can fix it.

Moving existing branch cards into Work

Most managed projects plan in Work from the start and never need this. If a managed branch already has cards on its board, Branch tasks offers Move N cards into Work, once. Each card becomes a project Work issue. Nothing is deleted.
  1. Choose Move N cards into Work. ReasonOS asks first: the board becomes read-only as the move starts. Choose Keep working here to back out, or Move into Work to go ahead.
  2. When every card has moved, the board shows the new issue keys and Open Project work. The Branch tasks tab then goes away for that branch.
  3. If the move stops partway, the board says the move is not finished. It lists the issues already in Work, and names each card that hasn’t moved with the reason. The board stays read-only. Choose Retry the move to finish the same cards; a card that already moved is not moved twice. ReasonOS never retries on its own.
  4. If the branch server refuses to start or finish the move, for example because the workspace isn’t on the branch the cards belong to, the board shows its reason.
  5. If ReasonOS can’t confirm whether the move happened, it says so. Refresh the board before trying again: it then shows either the finished move or the unfinished one with Retry the move.
An older branch server can’t move cards safely. Its board says the workspace needs updating instead of offering the move, and its cards keep working until then. The local editor keeps its file board and never offers the move. Each issue keeps its card’s description, checklist steps and comments, and its links to agent sessions, plans and memory notes. An unfinished move survives a branch server restart, and Retry the move sends the same frozen cards again. An issue that already moved is left as it is, including any edits made to it in Work since.
Don’t edit the frozen card files or delete the pending move record to unlock the board. Changes made outside the board can stop the move from finishing. If a card was imported earlier from a snapshot ReasonOS can’t verify, the move stops on that card and asks for your project operator; there is no self-service repair. You can keep working on the card’s existing Work issue meanwhile.
The app, the control plane and the branch server must all support the move. Publishing a newer app doesn’t update a branch server that is already running; follow the board’s update note before moving. Boards that have already moved stay readable.