kanban-worker

Kanban Worker — Pitfalls and Examples

You're seeing this skill because the Kanban dispatcher spawned you as a worker with --skills kanban-worker — it's loaded automatically for every dispatched worker. The lifecycle (6 steps: orient → work → heartbeat → block/complete) also lives in the KANBAN_GUIDANCE block that's auto-injected into your system prompt. This skill is the deeper detail: good handoff shapes, retry diagnostics, edge cases.

Workspace handling

Your workspace kind determines how you should behave inside $HERMES_KANBAN_WORKSPACE:

Kind	What it is	How to work
scratch	Fresh tmp dir, yours alone	Read/write freely; it gets GC'd when the task is archived.
dir:<path>	Shared persistent directory	Other runs will read what you write. Treat it like long-lived state. Path is guaranteed absolute (the kernel rejects relative paths).
worktree	Git worktree at the resolved path	If .git doesn't exist, run git worktree add <path> ${HERMES_KANBAN_BRANCH:-wt/$HERMES_KANBAN_TASK} from the main repo first, then cd and work normally. Commit work here.

Tenant isolation

If $HERMES_TENANT is set, the task belongs to a tenant namespace. When reading or writing persistent memory, prefix memory entries with the tenant so context doesn't leak across tenants:

• Good: business-a: Acme is our biggest customer
• Bad (leaks): Acme is our biggest customer

Good summary + metadata shapes

The kanban_complete(summary=..., metadata=...) handoff is how downstream workers read what you did. Patterns that work:

Coding task:

kanban_complete(
    summary="shipped rate limiter — token bucket, keys on user_id with IP fallback, 14 tests pass",
    metadata={
        "changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
        "tests_run": 14,
        "tests_passed": 14,
        "decisions": ["user_id primary, IP fallback for unauthenticated requests"],
    },
)

Coding task that needs human review (review-required):