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.
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 toagent, 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.
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).
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.
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.- 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.
- 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.
- 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.
- 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.
- 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.