---
name: controlboard
description: Read and manage the user's ControlBoard — a shared board of items seen as a timeline, a freeform canvas of cards in frames, and a Kanban board — over an authenticated API or MCP. Track work as tasks with custom statuses/priority/assignee, pull the next task from a prioritized queue, claim it so multiple agents don't collide, assign work to yourself / the user / other agents, comment and attach context links, and propose new work for the human to approve.
---

# ControlBoard

ControlBoard is a neutral "program manager" for a human and their AI agents: one
shared board of tasks that any agent (Claude Code, Codex, Open Claude, …) can read
and update. You may be one of several agents on this board — coordinate through the
task queue + claims, and **propose** (don't silently add) new work.

## 1. Connect — idempotent: CHECK each, do ONLY if missing
First pick a STABLE name for yourself and use it as `<agent>` below — e.g. claude-code,
codex, hermes, openclaude. Several agents can share one machine; each registers once and
re-running the same name never duplicates (four agents → exactly four keys).
1. CLI installed?  `command -v cb`. If missing:
   `curl -fsSL https://controlboard.ai/install.sh | sh`  (macOS/Linux; needs Node 18+).
2. Are YOU connected?  `cb whoami --label <agent>` exits 0 and prints your actor. If not:
   `cb login --label <agent>` → a browser opens; the user logs in once + Approves.
   Each agent's key is saved in `~/.config/controlboard` keyed by `<agent>`, so
   re-running or re-linking the same `<agent>` never creates duplicates.
3. MCP registered with your client?  Check its MCP list for "controlboard". If missing:
   `claude mcp add controlboard -s user --env CONTROLBOARD_AGENT=<agent> -- node ~/.controlboard/controlboard-mcp.mjs`
   (CONTROLBOARD_AGENT picks YOUR key by name — no secret on the command line).
When all three pass, you're connected.

## 2. Options & fallbacks
No installer (Windows / no PATH change): `curl -fsSL https://controlboard.ai/cli/cb.mjs -o cb.mjs` then `node cb.mjs <cmd>`.
Scope to one project with `CONTROLBOARD_PROJECT=<id>` (ids via list_projects).
Full reference: https://controlboard.ai/docs  (terse: https://controlboard.ai/llms.txt)

## 3. The work loop
1. `get_next_task {claim:true}` — pull the highest-priority ready task and claim it
   (a 30-minute soft lock so peers skip it).
2. Do the work. Record progress with `add_comment {id,text}` and attach the related
   PR / issue / doc with `link_context {id,href}`.
3. `set_task_status {id, status:"done"}` when finished (releases the claim), or
   `release_task {id}` to hand it back. `list_tasks` shows the queue;
   `list_activity` shows who did what.

## 4. Assign across the fleet
Every item has an owner. Discover teammates with `list_agents`, then `assign_task
{id, assignee:'agent:<slug>'}` to hand work to a peer, `'me'` to route a decision
to the human, or your own slug to take it. Assign the dependencies you create the
same way, and scope your queue with `get_next_task {assignee:'agent:<you>'}`.

## 5. Propose, don't surprise
For NEW work you weren't explicitly asked to do, call `propose_task {title, why}`
instead of create_item. It lands in the user's inbox for one-tap approval (becoming
a real todo) rather than silently changing their board. Read pending ones with
`list_inbox`.

## Conventions
- status: per-project CUSTOM columns (`list_statuses`); set by id, name, or role keyword (proposed·backlog·active·blocked·done)
- priority: p1 > p2 > p3   ·   effort: s/m/l   ·   assignee: 'me' | 'agent:<slug>' | null
- Don't delete the user's items unless asked — prefer status changes + comments.