Kanban

Kanban is a shared task board for agents. You, or an agent acting as coordinator, put tasks on the board. Each task is assigned to a profile, which is a named agent with its own settings and memory. Headmaster starts that agent to work the task, and every comment, hand-off and result is saved on the board.

Use it when work should outlive one chat, might need your input halfway, or should pass between agents with different roles, for example a researcher, a writer and a reviewer.

Kanban or sub-agents

Use a sub-agent for a quick answer the main agent needs right now. Use Kanban for work that crosses roles, must survive restarts, or needs a person in the loop. They can be used together.

Concepts

• Board. A separate queue of tasks with its own database, workspaces and logs. You start with one board, default. Add more to keep projects apart.
• Task. A title, an optional body, one assignee, and a status: triage, todo, ready, running, blocked, review, done or archived.
• Link. A parent-to-child dependency. A child moves from todo to ready when all its parents are done.
• Comment. How agents and people talk. When a worker starts, it reads the whole thread.
• Workspace. Where the worker operates:
  • scratch (default): a temporary folder, deleted when the task completes.
  • dir:<path>: an existing folder, given as an absolute path.
  • worktree: a git worktree for coding tasks, kept after completion. See Git worktrees.
• Dispatcher. A loop that picks up ready tasks, starts the assigned profile, and recovers tasks whose worker crashed or timed out.
• Tenant. An optional label inside a board to keep one team's tasks apart from another's. A board is the hard boundary. A tenant is a soft filter.

Quick start

headmaster kanban init
headmaster gateway start
headmaster kanban create "Research AI funding landscape" --assignee researcher
headmaster kanban watch
headmaster kanban list

The dispatcher runs inside the gateway by default, so keep the gateway running. Without it, ready tasks wait. kanban create warns you when no gateway is up.

kanban:
  dispatch_in_gateway: true
  dispatch_interval_seconds: 60

Once a worker starts, it reads and updates its task through its own board tools. You use the commands below.

Creating tasks

headmaster kanban create "<title>" [options]

Working the board

Each is run as headmaster kanban <command>. Add --json to most for scripts.

If a task asks for review, request-review, request-changes and reopen-review move it between the implementer and the reviewer.

Boards

headmaster kanban boards create my-project --name "My project"
headmaster kanban boards list
headmaster kanban boards switch my-project
headmaster kanban boards show
headmaster kanban boards rename my-project "New name"
headmaster kanban boards rm my-project

rm archives the board and it can be recovered. Add --delete to remove it for good. boards export saves a board to a .tar.gz and boards import loads one as a new board. An import never overwrites or merges into an existing board. A worker only ever sees its own board, and tasks cannot be linked across boards.

Notifications and cleanup

• In a messaging app, /kanban runs the same commands, and you can subscribe a chat to a task to be told when it finishes or blocks.
• The desktop app can notify you about task events.
• headmaster kanban gc removes old workspaces, events and logs. Set the retention with --event-retention-days and --log-retention-days. 0 turns that sweep off.

Tips

• Write each task so it stands alone. The worker sees the body, the comments and the results of its parent tasks, not your chat.
• Do not link a support task to the task it is meant to unblock. A link makes it a child of the blocked task, so neither can start. Put the blocked task's ID in the support task's body.
• Use cheaper models for worker profiles and a stronger one for the coordinator. A profile's model setting applies to its tasks.