# Kaban Workflow

> Use when calling TodoWrite with 3+ items, starting multi-step implementation tasks, at session start to check existing board, or when user mentions "board", "kanban", "track progress". Syncs TodoWrite todos with persistent kaban board.

- Skill: `tomevault-io/kaban-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kaban-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kaban-workflow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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:**

```bash
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 |

---
> Source: [kaban-board/kaban](https://github.com/kaban-board/kaban) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-25 -->