Task board

Every branch in ReasonOS has a task board: a kanban board of the work being done on that branch. It appears in the ReasonOS editor’s 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. High-level epics and roadmaps live outside ReasonOS.

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 Tasks view 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:

Tool	What the agent does with it
`task_list` / `task_get`	Read the board — agents check it when starting a session, since the work they were asked to do is often already a card with context and comments
`task_update`	Move a card between columns, check off completed steps
`task_comment`	Leave a progress note, record a decision, ask a question
`task_create`	File follow-up work it discovered but is not doing now

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

task_config(
    states = [
        state(id = "backlog", name = "Backlog",   category = "todo",        color = "#a9b1d6"),
        state(id = "doing",   name = "Doing",     category = "in_progress", color = "#7aa2f7", wip_limit = 3),
        state(id = "review",  name = "In Review",                           color = "#bb9af7"),
        state(id = "done",    name = "Done",      category = "done",        color = "#9ece6a"),
    ],
    default_state = "backlog",
)

Because the file is committed, the board layout is shared by everyone on the branch — and by every branch cut from it.

`state(...)`

Parameter	Meaning
`id`	Column id stored on cards (required)
`name`	Display name (defaults to the id)
`category`	What the column means: `"todo"`, `"in_progress"`, or `"done"`. “Run with agent” moves cards to the first `in_progress` column. Uncategorized columns are plain lanes.
`color`	Column dot and card accent color
`wip_limit`	The column count renders red above this (0 = unlimited)

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

`task_config(...)`

Parameter	Meaning
`states`	Columns, in display order (required)
`default_state`	Column for new cards (defaults to the first state)
`agent_prompt`	Template for the prompt an agent receives when it picks up a card; empty uses the built-in default

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.

task_config(
    states = ["todo", "doing", "done"],
    agent_prompt = """You are picking up task {{id}}: {{title}} (branch: {{branch}}).

{{description}}

Steps:
{{steps}}

Follow the team style guide in docs/style.md before writing any code.
{{tool_instructions}}""",
)

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.

Getting Started

Build

Languages

Containers & Deploy

Infrastructure

CI & Remote Builds

Team Workflow

Tasks travel with the branch

Working the board in the editor

Run a task with an agent

Mention the agent in a comment

Agents read and write the same board

Lifecycle: the board reconciles with git

Configuring the board: `.reasonos/tasks.rbs`

`state(...)`

`task_config(...)`

Customizing the agent prompt

​Tasks travel with the branch

​Working the board in the editor

​Run a task with an agent

​Mention the agent in a comment

​Agents read and write the same board

​Lifecycle: the board reconciles with git

​Configuring the board: .reasonos/tasks.rbs

​state(...)

​task_config(...)

​Customizing the agent prompt

Tasks travel with the branch

Working the board in the editor

Run a task with an agent

Mention the agent in a comment

Agents read and write the same board

Lifecycle: the board reconciles with git

Configuring the board: `.reasonos/tasks.rbs`

`state(...)`

`task_config(...)`

Customizing the agent prompt