Kaban Workflow

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.

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

Quick Reference

CLI Commands

MCP Tools (via kaban mcp)

MCP Resources (read-only)

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

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

Source: kaban-board/kaban — distributed by TomeVault.