kanban

name	kanban
description	Manage project tasks in a local SQLite DB (~/.claude/kanban-dbs/{project}.db). Supports task CRUD (add, edit, move, remove), board viewing, session context persistence, and statistics. For pipeline orchestration use /kanban-run, for requirements refinement use /kanban-refine. Run /kanban-init first to create the local DB.
license	MIT

Shared context: read shared.md for DB path, pipeline levels, status transitions, DB operations, error handling, and agent context flow. Safety principles: read principles.md — mandatory, not optional.

Commands

/kanban or /kanban list — View Board

BOARD_JSON=$(sqlite3 -json "$DB" \
  "SELECT id, title, status, priority, level, current_agent FROM tasks WHERE project='$PROJECT' ORDER BY status, rank, id")

Python으로 column별 그룹화 후 markdown table 출력 (ID, Status, Priority, Title).

/kanban context — Session Handoff

Run first when starting a new session. Fetch board and output pipeline state: Implementing / Plan Review / Impl Review / Testing / Recently Done / Next Todo.

BOARD_JSON=$(sqlite3 -json "$DB" \
  "SELECT id, title, status, priority, level, current_agent FROM tasks WHERE project='$PROJECT' ORDER BY status, rank, id")

/kanban context save — Save Session State

Captures current board state + git branch + decisions made this session to .claude/kanban-context.md. Use before ending a session so the next session can resume without context loss.

BOARD_JSON=$(sqlite3 -json "$DB" \
  "SELECT id, title, status, priority, level FROM tasks WHERE project='$PROJECT' ORDER BY status, rank, id")
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
DIRTY=$(git diff --stat 2>/dev/null | tail -1 || echo "")

Write .claude/kanban-context.md with:

1. Saved at: timestamp + branch
2. In Progress: tasks currently in impl / impl_review / test columns (ID, title, status)
3. Pending Review: tasks in plan_review or impl_review (needs human decision)
4. Next Todo: first task in todo column
5. Git State: branch name, dirty working tree summary ($DIRTY)
6. Decisions this session: ask user "Any decisions to note before saving?" and append their answer verbatim

Add .claude/kanban-context.md to .gitignore if not already present.

/kanban context restore — Restore Session State

Loads .claude/kanban-context.md if it exists, then fetches live board to show what changed since save. Use at session start instead of /kanban context when you were mid-task last session.

SAVED=$(cat .claude/kanban-context.md 2>/dev/null || echo "")
BOARD_JSON=$(sqlite3 -json "$DB" \
  "SELECT id, title, status, priority, level FROM tasks WHERE project='$PROJECT' ORDER BY status, rank, id")

Output:

1. Show saved state (what was in progress, decisions noted)
2. Show current live board state
3. Highlight any status changes since the save (tasks that moved columns)
4. Suggest: "Resume task #ID [title]?" for the first in-progress task

/kanban add <title> — Add Task

1. Ask user for priority, level (L1/L2/L3), description, tags (use AskUserQuestion)
2. Use Python sqlite3 for safe insert with user text (see shared.md → JSON Safety)
3. Output confirmation with new task ID

/kanban move <ID> <status> — Move Task

반드시 shared.md → Move Protocol 순서를 따를 것. Step 1(현재 status+level 확인) → Step 2(매트릭스 조회) → Step 3(유효성 검사 후 이동 실행). 유효하지 않은 전환 시 오류 출력, 사용자에게 올바른 다음 상태 안내.

/kanban edit <ID> — Edit Task

Ask user which fields to modify, then update via sqlite3 CLI.

/kanban remove <ID> — Delete Task

sqlite3 "$DB" "DELETE FROM tasks WHERE id=$ID AND project='$PROJECT'"

/kanban stats — Statistics

BOARD_JSON=$(sqlite3 -json "$DB" \
  "SELECT id, title, status, priority, level, agent_log FROM tasks WHERE project='$PROJECT' ORDER BY status, rank, id")
python3 << 'PY'
import json, sys
from collections import defaultdict

rows = json.loads(sys.stdin.read())
board = {}
for row in rows:
    board.setdefault(row['status'], []).append(row)

columns = ['todo', 'plan', 'plan_review', 'impl', 'impl_review', 'test', 'done']

# Column counts
counts = {col: len(board.get(col, [])) for col in columns}
counts['total'] = sum(counts.values())
print("## Column Counts\n")
print("| Status | Count |")
print("|--------|-------|")
for col in columns:
    print(f"| {col} | {counts[col]} |")
print(f"| **total** | **{counts['total']}** |")

# Token stats per agent
agent_stats = defaultdict(lambda: {'entries': 0, 'tokens': 0})
for col in columns:
    for task in board.get(col, []):
        raw = task.get('agent_log')
        if not raw:
            continue
        try:
            logs = json.loads(raw) if isinstance(raw, str) else raw
        except (json.JSONDecodeError, TypeError):
            continue
        for entry in logs:
            agent = entry.get('agent', 'unknown')
            agent_stats[agent]['entries'] += 1
            agent_stats[agent]['tokens'] += entry.get('tokens', 0)

total_tokens = sum(v['tokens'] for v in agent_stats.values())
total_entries = sum(v['entries'] for v in agent_stats.values())

print("\n## Agent Token Usage\n")
if total_tokens == 0:
    print("No token data")
else:
    print("| Agent | Entries | Tokens (est.) |")
    print("|-------|---------|---------------|")
    for agent in sorted(agent_stats):
        s = agent_stats[agent]
        print(f"| {agent} | {s['entries']} | {s['tokens']:,} |")
    print(f"| **Total** | **{total_entries}** | **{total_tokens:,}** |")
PY

Pass BOARD_JSON to stdin: echo "$BOARD_JSON" | python3 - <<'PY' ...

/kanban stats health — Code Health Score

Auto-detects available tools and computes a 0–10 composite code health score. Use when: "health check", "코드 품질 확인", "how healthy is this codebase".

python3 - <<'PY'
import subprocess, json, sys

checks = []

def run(cmd, label, parse=None):
    try:
        r = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
        ok = r.returncode == 0
        detail = parse(r) if parse else ""
        checks.append({"label": label, "ok": ok, "detail": detail})
    except FileNotFoundError:
        pass  # tool not installed — skip silently
    except subprocess.TimeoutExpired:
        checks.append({"label": label, "ok": False, "detail": "timeout"})

# TypeScript
run(["npx", "--no", "tsc", "--noEmit", "--pretty", "false"],
    "TypeScript",
    lambda r: f"{r.stdout.count('error TS')} errors" if r.returncode != 0 else "")

# Python type check (pyright preferred, mypy fallback)
if subprocess.run(["which", "pyright"], capture_output=True).returncode == 0:
    run(["pyright", "--outputjson"], "Pyright",
        lambda r: f"{json.loads(r.stdout).get('summary',{}).get('errorCount',0)} errors" if r.stdout else "")
elif subprocess.run(["which", "mypy"], capture_output=True).returncode == 0:
    run(["mypy", ".", "--ignore-missing-imports"], "mypy",
        lambda r: r.stdout.strip().split('\n')[-1] if r.stdout else "")

# Linter
if subprocess.run(["which", "ruff"], capture_output=True).returncode == 0:
    run(["ruff", "check", "--statistics"], "ruff",
        lambda r: r.stdout.strip().split('\n')[0] if r.stdout else "")
elif subprocess.run(["npx", "--no", "eslint", "--version"], capture_output=True).returncode == 0:
    run(["npx", "--no", "eslint", ".", "--max-warnings=0"], "ESLint",
        lambda r: f"{r.stdout.count('warning') + r.stdout.count('error')} issues" if r.returncode != 0 else "")

# Tests
if subprocess.run(["which", "pytest"], capture_output=True).returncode == 0:
    run(["pytest", "--tb=no", "-q"], "pytest",
        lambda r: r.stdout.strip().split('\n')[-1] if r.stdout else "")
elif subprocess.run(["npx", "--no", "jest", "--version"], capture_output=True).returncode == 0:
    run(["npx", "--no", "jest", "--passWithNoTests", "--silent"], "Jest",
        lambda r: r.stderr.strip().split('\n')[-1] if r.stderr else "")

# Rust
run(["cargo", "check", "--quiet"], "cargo check")

# Shell lint
if subprocess.run(["which", "shellcheck"], capture_output=True).returncode == 0:
    sh_files = subprocess.run(["find", ".", "-name", "*.sh", "-not", "-path", "*/.git/*"],
                               capture_output=True, text=True).stdout.strip().split()
    if sh_files:
        run(["shellcheck"] + sh_files[:20], "shellcheck",
            lambda r: f"{r.stdout.count('SC')} warnings" if r.returncode != 0 else "")

# Score
if not checks:
    print("## Code Health\nNo supported tools found (tsc/pyright/ruff/pytest/jest/cargo/shellcheck).")
    sys.exit(0)

passed = sum(1 for c in checks if c["ok"])
score = round(passed / len(checks) * 10, 1)
grade = "🟢" if score >= 8 else "🟡" if score >= 5 else "🔴"

print(f"## Code Health: {grade} {score}/10  ({passed}/{len(checks)} checks passed)\n")
print("| Check | Status | Detail |")
print("|-------|--------|--------|")
for c in checks:
    icon = "✅" if c["ok"] else "❌"
    print(f"| {c['label']} | {icon} | {c['detail'] or ''} |")
PY

/kanban retro — Retrospective Analysis

Analyzes completed tasks + git history to produce a sprint retrospective report. Use at end of week/sprint: "kanban retro", "주간 회고", "what did we ship this week".

BOARD_JSON=$(sqlite3 -json "$DB" \
  "SELECT id, title, status, priority, level, agent_log, impl_review_count FROM tasks WHERE project='$PROJECT' ORDER BY status, rank, id")
python3 - <<'PY'
import json, sys, subprocess
from collections import defaultdict

rows = json.loads(sys.stdin.read())
board = {}
for row in rows:
    board.setdefault(row['status'], []).append(row)

columns = ['todo', 'plan', 'plan_review', 'impl', 'impl_review', 'test', 'done']
done_tasks = board.get('done', [])

print("## Retrospective\n")

# --- Completed tasks ---
print(f"### Completed: {len(done_tasks)} tasks\n")
if done_tasks:
    print("| ID | Title | Level | Rework |")
    print("|----|-------|-------|--------|")
    for t in done_tasks[-10:]:
        rework = t.get('impl_review_count', 0) or 0
        flag = f"⚠️ {rework}x" if rework > 1 else "✅"
        print(f"| {t.get('id','')} | {t.get('title','')[:45]} | L{t.get('level',1)} | {flag} |")

# --- Rework rate ---
rework_tasks = [t for t in done_tasks if (t.get('impl_review_count') or 0) > 1]
rate = len(rework_tasks) / len(done_tasks) * 100 if done_tasks else 0
print(f"\n**Rework rate**: {rate:.0f}% ({len(rework_tasks)}/{len(done_tasks)} tasks needed re-impl)")

# --- Pipeline snapshot (non-done) ---
snapshot = {col: len(board.get(col, [])) for col in columns[:-1] if board.get(col)}
if snapshot:
    print("\n### Pipeline Snapshot\n")
    print("| Column | Count |")
    print("|--------|-------|")
    for col, count in snapshot.items():
        print(f"| {col} | {count} |")

# --- Agent token spend (done tasks) ---
agent_stats = defaultdict(lambda: {'entries': 0, 'tokens': 0})
for t in done_tasks:
    raw = t.get('agent_log')
    if not raw:
        continue
    try:
        logs = json.loads(raw) if isinstance(raw, str) else raw
    except (json.JSONDecodeError, TypeError):
        continue
    for entry in logs:
        a = entry.get('agent', 'unknown')
        agent_stats[a]['entries'] += 1
        agent_stats[a]['tokens'] += entry.get('tokens', 0)

total = sum(v['tokens'] for v in agent_stats.values())
if total > 0:
    print(f"\n### Token Spend (completed): {total:,} est.\n")
    print("| Agent | Tokens |")
    print("|-------|--------|")
    for a in sorted(agent_stats, key=lambda x: -agent_stats[x]['tokens']):
        print(f"| {a} | {agent_stats[a]['tokens']:,} |")

# --- Git commits ---
git = subprocess.run(
    ['git', 'log', '--oneline', '--since=7 days ago'],
    capture_output=True, text=True
)
commits = [l for l in git.stdout.strip().split('\n') if l]
if commits:
    print(f"\n### Git Activity: {len(commits)} commits (last 7 days)")
PY

Pass BOARD_JSON to stdin. To scope to a custom period (e.g. 14 days), adjust --since=14 days ago in the git subprocess call.

/kanban project — Current Project Context

Fetch the current project's context from the projects table.

sqlite3 -json "$DB" "SELECT * FROM projects WHERE id='$PROJECT'"

Output formatted project context: Purpose, Stack, Brief, Category, task counts by status, linked projects.

If the project is not registered, suggest running /kanban-init to register it.

/kanban project all — Full Project Map

sqlite3 -json "$DB" "SELECT id, name, purpose, status, category FROM projects ORDER BY category, name"

Output: projects grouped by category with names and purposes.

/kanban project brief — View/Update Project Brief

The brief is a compressed context summary (200–500 chars) that agents consume at low token cost.

View current brief:

sqlite3 "$DB" "SELECT brief FROM projects WHERE id='$PROJECT'"

Set brief directly:

sqlite3 "$DB" "UPDATE projects SET brief='...' WHERE id='$PROJECT'"

AI-assisted update (/kanban project brief update):

1. Fetch current project info + recent done tasks
2. Analyze: current state, recent completions, active direction
3. Draft a concise brief (200–500 chars) covering: what exists now, where we're heading, recent key decisions
4. Present to user for confirmation → sqlite3 UPDATE to save

/kanban project update <field> <value> — Edit Project Metadata

sqlite3 "$DB" "UPDATE projects SET purpose='...' WHERE id='$PROJECT'"
sqlite3 "$DB" "UPDATE projects SET status='archived' WHERE id='$PROJECT'"

Supported fields: name, purpose, stack, brief, status, category, repo_url.

/kanban project link — Manage Project Relationships

# Add relationship
sqlite3 "$DB" "INSERT OR IGNORE INTO project_links (source_id, target_id, relation) VALUES ('$PROJECT', 'other-project', 'depends_on')"

# Remove relationship
sqlite3 "$DB" "DELETE FROM project_links WHERE source_id='$PROJECT' AND target_id='other-project' AND relation='depends_on'"

# List links
sqlite3 -json "$DB" "SELECT * FROM project_links WHERE source_id='$PROJECT'"

Relations: extends, serves, depends_on, shares_data.

Setup

Run /kanban-init first to create the local SQLite DB and register the project.

Add to .gitignore:

.claude/kanban.json
.codex/kanban.json
.claude/kanban-context.md

DB is stored at ~/.claude/kanban-dbs/<PROJECT>.db — not in the project directory.