Kaban Workflow

Overview

Persistent Kanban board for AI agent coordination. Tasks survive sessions, sync with TodoWrite, and track sub-agent assignments.

Core principle: TodoWrite for session visibility, Kaban for persistence and delegation.

CLI Availability Check

ALWAYS check CLI first before any kaban operation:

which kaban  # Must return path like /usr/local/bin/kaban

If not installed → inform user: "kaban CLI not found. Install instructions: TBD"

NEVER:

• Check .kaban/board.db directly with ls or file existence checks
• Run source code via bun run packages/cli/src/index.ts
• Use npx ts-node or similar development commands

ALWAYS use:

• kaban status - check board status
• kaban list - list tasks
• kaban add - add tasks
• kaban mcp - for MCP tool integration

When to Use

Session Start:

• Run kaban status to check for existing board
• If board exists → auto-resume in-progress tasks

During Work:

• Multi-step features (3+ tasks)
• Delegating to sub-agents
• User says "plan", "track", "board"

Not for:

• Single trivial tasks
• Pure research/questions
• Throwaway explorations

Session Start Flow

1. Check CLI: which kaban
   ├─ Not found → Inform user, proceed without kaban
   └─ Found → kaban status
              ├─ No board → Proceed normally
              └─ Board exists
                 ├─ In-progress tasks assigned to you?
                 │   └─ Yes → "Resume [task title]?" (require confirmation)
                 └─ No in-progress → Show status summary only

Task Sync (TodoWrite ↔ Kaban)

Mirror Pattern: Changes sync bidirectionally.

| Action | TodoWrite | Kaban | |--------|-----------|-------| | Create task | todowrite | kaban_add_task | | Start work | status: in_progress | kaban_move_task → in-progress | | Complete | status: completed | kaban_complete_task |

Sync on:

• TodoWrite creation → mirror to Kaban
• Kaban task move → update TodoWrite status
• Task completion → sync both

Sub-Agent Delegation

When delegating via Task tool:

1. kaban_add_task OR kaban_update_task
   - assignedTo: "{subagent_type}"  # e.g., "frontend-ui-ux-engineer"
   - labels: ["delegation", "{domain}"]

2. Task tool delegation prompt includes:
   - Kaban task ID
   - "Mark kaban task [ID] complete when done"

3. Sub-agent completes → kaban_complete_task

Agent naming convention:

assignedTo: "frontend-ui-ux-engineer"  # matches subagent_type
assignedTo: "oracle"                   # for architecture consults
assignedTo: "user"                     # human action required

Label Conventions

| Category | Labels | |----------|--------| | Type | bug, feature, refactor, docs, test | | Priority | p0 (critical), p1 (high), p2 (medium), p3 (low) | | Domain | frontend, backend, infra, database | | Status | blocked, delegation, review |

Quick Reference

CLI Commands

| Action | Command | |--------|---------| | Init board | kaban init | | Board status | kaban status | | Add task | kaban add "title" [--column backlog] [--agent claude] | | List tasks | kaban list [--column todo] [--agent claude] [--blocked] | | Move task | kaban move <id> <column> [--force] | | Mark done | kaban done <id> | | Start MCP | kaban mcp |

MCP Tools (via kaban mcp)

| Tool | Parameters | |------|------------| | kaban_add_task | title (required), column?, agent?, dependsOn?, labels?, files? | | kaban_move_task | id, column | | kaban_update_task | id, title?, description?, assignedTo?, labels?, files? | | kaban_complete_task | id | | kaban_delete_task | id | | kaban_block_task | id, reason | | kaban_unblock_task | id | | kaban_list_tasks | columnId?, agent?, blocked? | | kaban_get_task | id | | kaban_get_board | - | | kaban_get_columns | - | | kaban_get_blocked_tasks | - | | kaban_get_dependencies | id |

MCP Resources (read-only)

| Resource | Description | |----------|-------------| | kaban://board | Full board state | | kaban://tasks | All tasks | | kaban://task/{id} | Single task by ID | | kaban://blocked | All blocked tasks |

Workflow: Feature Planning

User: "Add dark mode to the app"

1. Confirm: "Create Kaban board for this feature?"
   └─ If yes → kaban_init (if no board)

2. Break down:
   kaban_add_task: "Create theme context"        → backlog
   kaban_add_task: "Add toggle component"        → backlog, labels: [frontend]
   kaban_add_task: "Implement dark styles"       → backlog, labels: [frontend]
   kaban_add_task: "Persist preference"          → backlog, labels: [backend]

3. Mirror to TodoWrite (user sees progress)

4. Start first task:
   kaban_move_task → in-progress
   todowrite status: in_progress

Workflow: Delegation

Task: "Add toggle component" needs frontend expertise

1. Update task:
   kaban_update_task:
     assignedTo: "frontend-ui-ux-engineer"
     labels: ["frontend", "delegation"]

2. Delegate via Task tool:
   prompt: |
     Task ID: abc123
     Create dark mode toggle component...
     When complete, call kaban_complete_task(id="abc123")

3. Sub-agent completes → task moves to Done

Workflow: Session Resume

Session start with existing board:

1. kaban_status → 
   {
     "columns": [
       {"name": "In Progress", "count": 2},
       {"name": "Done", "count": 5}
     ]
   }

2. kaban_list_tasks(columnId: "in-progress") →
   [
     {"id": "abc123", "title": "Implement auth", "assignedTo": "claude"}
   ]

3. Prompt user:
   "Found in-progress task: 'Implement auth'
    Resume this task?"

4. If yes → continue work
   If no  → show full board status

Default Columns

| Column | ID | WIP Limit | Purpose | |--------|-----|-----------|---------| | Backlog | backlog | - | Future work | | To Do | todo | - | Ready to start | | In Progress | in-progress | 3 | Active work | | Done | done | - | Completed (terminal) |

WIP Limit Awareness

Before kaban_move_task to in-progress:

• Check column count vs WIP limit
• If at limit → warn user, suggest completing existing tasks
• Use force: true only with user confirmation

Blocked Tasks

kaban_update_task:
  id: "abc123"
  blockedReason: "Waiting for API endpoint from backend team"

kaban_list_tasks(blocked: true) → shows all blocked tasks

Checklist: Board Setup

• [ ] kaban_init with meaningful board name
• [ ] Break feature into atomic tasks (1-2 hour chunks)
• [ ] Add labels for categorization
• [ ] Set dependencies if tasks have order
• [ ] Mirror initial tasks to TodoWrite

Checklist: Task Completion

• [ ] Work completed and verified
• [ ] kaban_complete_task called
• [ ] TodoWrite status updated to completed
• [ ] Dependent tasks unblocked (if any)
• [ ] Next task moved to in-progress (if continuing)

Common Mistakes

| Mistake | Fix | |---------|-----| | Using Kaban without TodoWrite | Always mirror - user needs session visibility | | Forgetting to sync on completion | Update both: kaban_complete_task + TodoWrite | | Checking .kaban/board.db with ls | Use kaban status CLI command instead | | Running source code directly | Use installed kaban CLI, never bun run or npx ts-node | | Force-moving past WIP limit silently | Warn user, get confirmation before force: true | | Not including task ID in delegation | Sub-agent can't mark task complete without ID | | Creating board for trivial tasks | Only for 3+ step features or cross-session work |