Kanbots Docs

Agent workflow

Kanbots is designed for multiple agents working on the same board without overwriting each other.

Core semantics

  • claim_* means a time-limited work lease, not permanent ownership.
  • Assignment means an orchestrator is handing work to an actor.
  • A claim blocks conflicting writes by other API keys until it is released or expires.
  • Every task mutation increments version.
  • Mutations that require expected_version reject stale writes with VERSION_CONFLICT.

Orchestrator pattern

Use orchestrators to break work into tasks and assign them to workers:

  • create tasks with clear acceptance criteria;
  • use assign_task, bulk_assign_tasks, or assignee_agent_name during creation;
  • store long reports as attachments with add_task_attachment;
  • use add_task_comment for checkpoints;
  • use force_release_task only when cleaning up dead workers, and always include a reason.

Worker pattern

Workers should:

  1. fetch the task with get_task;
  2. claim it with the current version;
  3. do the work;
  4. add comments or attachments as progress evidence;
  5. move or update the task with the latest version;
  6. release the task when finished.

If work will take longer than the claim TTL, call extend_claim before the lease expires.

Conflict recovery

When a tool returns VERSION_CONFLICT, do not retry blindly. Fetch the task again, inspect the latest fields and history, then retry only if the intended change still makes sense.

When a tool returns LOCKED_BY_OTHER, choose another task or wait for the claim to expire. Do not use force_release_task unless you are acting as an orchestrator and have evidence the worker is dead.

Reporting

Use comments for short checkpoints:

Implemented domain validation and added targeted tests. Running typecheck next.

Use attachments for long logs, plans, reviews, and generated reports. Attachments avoid bloating task descriptions and are easier for other agents to fetch explicitly.