# bttask Reference

bttask is the kanban task board for Agents Orchestrator. It provides structured
task tracking for multi-agent workflows, with optimistic locking to prevent
concurrent update conflicts.

## Overview

Tasks are stored in the shared `btmsg.db` SQLite database at
`~/.local/share/agor/btmsg.db`. The `bttask` CLI (Python, installed at
`~/.local/bin/bttask`) gives agents direct access. The Rust backend
(`src-tauri/src/bttask.rs`) provides read/write access for the Tauri frontend.

## Task schema

| Column | Type | Description |
|--------|------|-------------|
| `id` | TEXT PK | UUID |
| `title` | TEXT | Short task title |
| `description` | TEXT | Detailed description |
| `status` | TEXT | Current column (see below) |
| `priority` | TEXT | `low`, `medium`, or `high` |
| `assigned_to` | TEXT | Agent ID (nullable) |
| `created_by` | TEXT | Agent ID that created the task |
| `group_id` | TEXT | Group this task belongs to |
| `parent_task_id` | TEXT | Parent task for subtasks (nullable) |
| `sort_order` | INTEGER | Display order within column |
| `version` | INTEGER | Optimistic locking version (default 1) |
| `created_at` | TEXT | ISO timestamp |
| `updated_at` | TEXT | ISO timestamp |

### Task comments

| Column | Type | Description |
|--------|------|-------------|
| `id` | TEXT PK | UUID |
| `task_id` | TEXT FK | Parent task |
| `agent_id` | TEXT | Commenting agent |
| `content` | TEXT | Comment body |
| `created_at` | TEXT | ISO timestamp |

## Kanban columns

Tasks move through 5 statuses:

```
backlog -> todo -> in_progress -> review -> done
```

The frontend (`TaskBoardTab.svelte`) renders these as columns in a kanban board,
polling every 5 seconds for updates.

## Operations

### list_tasks

Returns all tasks for a group, ordered by `sort_order` then `created_at DESC`.

### create_task

Creates a new task with the given title, description, priority, and optional
assignment. Returns the created task with its generated ID.

### update_task_status

Moves a task to a new status. Uses optimistic locking: the caller must provide
the current `version` value. If the version in the database does not match, the
update is rejected with a conflict error. On success, the version is
incremented.

```
update_task_status(task_id, new_status, expected_version)
```

### delete_task

Removes a task by ID.

### add_comment

Adds a comment to a task. Any agent can comment regardless of role.

### task_comments

Returns all comments for a task, ordered by `created_at ASC`.

### review_queue_count

Returns the number of tasks currently in `review` status for a group. Used by
the health store to calculate reviewer attention scoring (10 points per review
task, capped at 50).

## CLI usage

Agents interact with bttask through shell commands. The `BTMSG_AGENT_ID`
environment variable identifies the calling agent.

```bash
# List all tasks
bttask list

# Create a task
bttask create --title "Fix auth bug" --priority high \
  --description "Token refresh fails after 24h"

# Move a task to in_progress
bttask status --id T-42 --status in_progress --version 1

# Add a comment
bttask comment --id T-42 --content "Root cause identified: expired refresh token"

# Delete a task
bttask delete --id T-42
```

## Role permissions

| Capability | Manager | Reviewer | Others |
|------------|---------|----------|--------|
| List tasks | Yes | Yes | Yes |
| Create tasks | Yes | No | No |
| Update status | Yes | Yes | Read-only |
| Delete tasks | Yes | No | No |
| Add comments | Yes | Yes | Yes |

The Manager role has full CRUD. The Reviewer can change task status (to move
items through the review pipeline) and add comments. Other roles have read-only
access to tasks but can add comments.

## Review queue integration

When a task moves to `review` status, the system auto-posts a notification to
the `#review-queue` btmsg channel. This triggers the Reviewer agent's attention
scoring. The `ensure_review_channels` function creates `#review-queue` and
`#review-log` channels idempotently on first use.

The `review_queue_count` is polled every 10 seconds by ProjectBox for reviewer
agents and fed into the health store's `setReviewQueueDepth()` for attention
scoring. Review tasks contribute to the reviewer's attention score:

- 10 points per task in review status
- Capped at 50 points total
- Priority rank: between `file_conflict` (70) and `context_high` (40)

## Optimistic locking

Every task has a `version` field starting at 1. When an agent updates a task's
status, it must pass the expected version. If another agent modified the task
since it was read, the version will not match and the update fails with a
conflict error. The calling agent should re-read the task and retry.

This prevents race conditions when multiple agents attempt to move the same task
simultaneously.

## Frontend

The kanban board is rendered by `src/lib/components/Workspace/TaskBoardTab.svelte`,
available in the Tasks tab for Manager-role agents. It polls `list_tasks` every
5 seconds and supports drag-style status transitions between columns.

IPC adapter: `src/lib/adapters/bttask-bridge.ts`.