Kanban

The kanban board is the shared coordination layer between you, other agents, and the human. It is a local, project-scoped board (stored in the project database) with swimlanes (workstreams) and columns that carry a semantic state. Agents read the board, claim work, do it, report back, and move the task — the board stays the source of truth for task state.

Model

Concept	Meaning
Board	A named project board. A project can have several.
Lane	A swimlane / workstream within a board.
Column	A state bucket. Each has a semantic state: backlog, ready, active, review, blocked, done.
Task	A work item with a title, description, owner, priority, tags, due date, and an optional scheduled_at.
Comment	A note on a task, authored by a human or an agent. Human comments outrank every other instruction.

Column states

State	Meaning
backlog	Parked, not yet ready to work
ready	Eligible for the dispatcher to pick up and run
active	Currently being worked on
review	Awaiting a human decision or approval — never auto-re-dispatched
blocked	Stuck; a comment names the blocker — never auto-re-dispatched
done	Complete and verified

WIP limits

Any column can carry a WIP limit (set via set_wip_limit, or the wip_limit parameter on add_column; null clears it). Moves, task creation, and claims into a full column are refused until space frees up — unless force: true is passed (task moves only). This keeps work from piling up in one stage.

The dispatcher

A dispatcher watcher runs tasks in ready columns automatically. It is concurrency-limited and exactly-once — a task can never run twice in parallel. When it dispatches a task to an agent, the agent's completion report is posted to its channel and added as a task comment automatically.

• One-off future work — pass scheduled_at (a millisecond timestamp) on create_task/update_task to make a task run no earlier than that time. It sits in ready with a "scheduled" marker until then. Use this for "do X tomorrow at 9am" style requests.
• Recurring work is not kanban's job — for "every weekday at 9am", the user should ask TF Manage to create a routine.

Workflow policy

Agents follow a fixed policy every time:

1. Read the board first (list_boards, get_board) and read a task's comments before acting on it.
2. Human comments outrank every other instruction — if a human commented how a task should be done, do exactly that.
3. Never silently pick up a task owned by another agent — claim it first. claim is atomic and refuses tasks in review/blocked/done columns, which prevents stale re-dispatch of finished work.
4. Do the work, then report with a comment describing what was done and where the output lives.
5. Move the task when done — to a review column if a human must decide/approve, to a done column if complete and verified, to blocked with a comment naming the blocker if stuck.
6. Use pending to find tasks where the latest comment is a human decision waiting to be routed or acted on.

Tool

The kanban tool manages boards. It is available to the TF Manage agent (and perk-inherited agents).

Action	Description
list_boards	List all boards
get_board	Read a board with its lanes, columns, tasks, comments
create_board	Create a board (template: default or empty)
remove_board	Delete a board
add_lane	Add a swimlane
rename_lane	Rename a swimlane
remove_lane	Remove a swimlane
add_column	Add a column with a semantic state and optional WIP limit
rename_column	Rename a column
set_wip_limit	Set or clear a column's WIP limit
remove_column	Remove a column
create_task	Create a task (owner, priority, tags, due, scheduled_at)
get_task	Read a task
update_task	Update a task's fields
move_task	Move a task to a column/lane position (force to bypass WIP)
claim	Atomically claim a task for an agent
delete_task	Delete a task
comment	Add a comment to a task
delete_comment	Remove a comment
pending	List tasks awaiting a human decision

Configuration

The kanban config section tunes the dispatcher:

{
  "kanban": {
    "dispatch": true,
    "concurrency": 1,
    "agent": "build",
    "wake_on_message": true
  }
}

Key	Default	Description
dispatch	true	Enable the dispatcher that watches boards and runs ready tasks with agents
concurrency	1	Max kanban/agent runs in parallel process-wide (kept low to protect the host OS)
agent	"build"	Default agent for ready tasks with no owner. Tasks owned by a human never auto-run
wake_on_message	true	Wake an agent (a bounded run) when a human posts in its channel