b6c1d4b6af
New reference docs: - agents/ref-btmsg.md: inter-agent messaging schema and CLI - agents/ref-bttask.md: kanban task board operations - providers/ref-providers.md: Claude/Codex/Ollama/Aider comparison - config/ref-settings.md: (already committed) New guides: - contributing/dual-repo-workflow.md: community vs commercial repos - plugins/guide-developing.md: Web Worker sandbox API and publishing New pro docs: - pro/features/knowledge-base.md: persistent memory + symbol graph - pro/features/git-integration.md: context injection + branch policy - pro/marketplace/README.md: 13 plugins catalog Split files: - architecture/data-model.md: from architecture.md (schemas, layout) - production/hardening.md: from production.md (supervisor, sandbox, WAL) - production/features.md: from production.md (FTS5, plugins, secrets, audit)
161 lines
5 KiB
Markdown
161 lines
5 KiB
Markdown
# 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`.
|