kanban

name	kanban
description	Kanban multi-agent task management — orchestrator decomposition playbook, worker lifecycle, pitfalls, and handoff patterns. Use when routing work through Kanban, creating/claiming/completing cards, or debugging stuck workers.
version	1.0.0
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["kanban","multi-agent","orchestration","collaboration","workflow"]}}

Kanban Multi-Agent Task Management

Hermes Kanban is a durable SQLite-based multi-agent work queue. The core worker lifecycle (KANBAN_GUIDANCE) is auto-injected into every dispatched worker's system prompt. This skill covers both roles: the orchestrator who decomposes and routes work, and the worker who claims, executes, and hands off cards.

Orchestrator: Decomposition Playbook

Your job: route, don't execute. Decompose user requests into Kanban cards, assign them to existing profiles, and link dependencies.

Step 0: Discover Available Profiles

Before fanning out, discover what profiles exist on this machine. The dispatcher silently fails to spawn unknown assignees.

hermes profile list

Or ask the user. Cache the result — don't re-discover every turn.

When to Use the Board

Create Kanban tasks when: multiple specialists are needed, work must survive crashes, human-in-the-loop is desired, subtasks can parallelize, review/iteration is expected, or audit trail matters.

If none apply — small one-shot task — use delegate_task or answer directly.

Anti-Temptation Rules

• Do not execute the work yourself.
• For any concrete task, create a Kanban card and assign it.
• Split multi-lane requests before creating cards. Independent workstreams → separate cards.
• Run independent lanes in parallel. Only link true data dependencies via parents=[...].
• Never create dependent work as independent ready cards. A child with unfinished parents starts in todo; the dispatcher promotes when every parent is done.
• If no specialist fits the available profiles, ask the user.

Decomposition Flow

1. Understand the goal — ask clarifying questions if ambiguous.
2. Sketch the task graph — extract lanes, map to profiles, decide dependencies, show the user before creating.
3. Create tasks and link — use kanban_create(title, assignee, body, parents=[...], tenant=...). Create parents first, capture ids, then children with those ids.
4. Complete your own task if you were spawned as one — summarize what you created in kanban_complete.
5. Report back — plain prose describing what cards were created and which profiles own them.

Common Patterns

• Fan-out + fan-in: N research cards, 1 synthesis card with all as parents.
• Parallel implementation + validation: implementer + verifier in parallel, reviewer gates on both.
• Pipeline: planner → implementer → reviewer with parent links.
• Same-profile queue: N tasks, same assignee, no dependencies — dispatcher serializes.
• Goal-mode cards: For open-ended tasks, pass goal_mode=True with explicit acceptance criteria in the body. Worker keeps going in the same session until done or budget exhausted.

Recovery: Stuck Workers

• Reclaim: hermes kanban reclaim <task_id> — abort running worker, reset to ready.
• Reassign: hermes kanban reassign <task_id> <new-profile> --reclaim — switch profiles.
• Change model: hermes -p <profile> model then reclaim.

Orchestrator Pitfalls

• Inventing profile names. Dispatcher silently drops unknown assignees.
• Bundling independent lanes. "Fix blockers AND check variants" → two cards, not one.
• Over-linking. "Finally check X" may be parallel if X is static config/docs.
• Forgetting dependency links. Don't create all cards as independent ready.
• Reassignment vs. new task. Blocked review → create NEW task, don't re-run same card.
• Tenant inheritance. Pass tenant=os.environ.get("HERMES_TENANT") on every create.

---

Worker: Lifecycle, Pitfalls, and Handoffs

You're spawned by the dispatcher with HERMES_KANBAN_TASK set. The lifecycle (orient → work → heartbeat → block/complete) is auto-injected. This section covers deeper detail.

Workspace Handling

Kind	Behavior
scratch	Fresh tmp dir, yours alone, GC'd on archive
dir:<path>	Shared persistent directory — other runs read your output
worktree	Git worktree — commit work here; if .git missing, git worktree add first

Good Handoff Shapes

Coding task → complete:

kanban_complete(
    summary="shipped rate limiter — token bucket, 14 tests pass",
    metadata={"changed_files": [...], "tests_run": 14, "tests_passed": 14, "decisions": [...]},
)

Coding task → review-required (block, don't complete):

kanban_comment(body="review-required handoff:\n" + json.dumps({...}))
kanban_block(reason="review-required: rate limiter shipped — needs eyes on the fallback choice")

Research task:

kanban_complete(summary="3 libraries reviewed; vLLM wins on throughput", metadata={"sources_read": 12, "recommendation": "vLLM"})

Review task:

kanban_complete(summary="reviewed PR #123; 2 blockers found", metadata={"pr_number": 123, "findings": [...], "approved": False})

Claiming Created Cards

Only list ids you captured from successful kanban_create return values. Never invent ids from prose. The gate rejects phantom ids.

# GOOD
c1 = kanban_create(title="fix SQL injection", assignee="security-worker")
kanban_complete(..., created_cards=[c1["task_id"]])

Block Reasons Worth Answering

Bad: "stuck". Good: one sentence naming the specific decision needed. Leave context as a comment.

Heartbeats

Good: "epoch 12/50, loss 0.31", "scanned 1.2M/2.4M rows". Bad: "still working", empty notes. Every few minutes max; skip for tasks under ~2 minutes.

Retry Diagnostics

Check prior runs' outcome via kanban_show:

• timed_out → chunk the work
• crashed → reduce memory
• spawn_failed → profile config issue, block and ask human
• blocked → read unblock comment in thread

Worker Pitfalls

• Task state can change between dispatch and startup. Always kanban_show first.
• Workspace may have stale artifacts. Read the comment thread.
• Don't call clarify — you're headless, no live user. Use kanban_comment + kanban_block.
• Don't use delegate_task as substitute for kanban_create. Different lifecycle.
• Don't complete a task you didn't finish. Block it.
• Don't rely on CLI — use kanban_* tools which work across all terminal backends.