docs: add 11 new documentation files across all categories
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)
This commit is contained in:
Hibryda
parent
8251321dac
commit
b6c1d4b6af
11 changed files with 2198 additions and 0 deletions
161
docs/agents/ref-bttask.md
Normal file
161
docs/agents/ref-bttask.md
Normal file
|
|
@ -0,0 +1,161 @@
|
|||
# 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`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue