agent-orchestrator/docs/agents/ref-bttask.md

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.

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