> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Task board
> The branch-scoped kanban board in the ReasonOS editor — tasks that travel with the branch through git, shared by everyone (and every agent) on that branch.
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](/workflow/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](/workflow/checkpoints) 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).
```python theme={null}
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.
```python theme={null}
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.