Pitfalls, examples, and edge cases for Hermes Kanban workers. The lifecycle itself is auto-injected into every worker's system prompt as KANBAN_GUIDANCE (from agent/prompt_builder.py); this skill is what you load when you want deeper detail on specific scenarios.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Pitfalls, examples, and edge cases for Hermes Kanban workers. The lifecycle itself is auto-injected into every worker's system prompt as KANBAN_GUIDANCE (from agent/prompt_builder.py); this skill is what you load when you want deeper detail on specific scenarios.
You're seeing this skill because the Hermes 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> <branch> 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"],
},
)
Research task:
kanban_complete(
summary="3 competing libraries reviewed; vLLM wins on throughput, SGLang on latency, Tensorrt-LLM on memory efficiency",
metadata={
"sources_read": 12,
"recommendation": "vLLM",
"benchmarks": {"vllm": 1.0, "sglang": 0.87, "trtllm": 0.72},
},
)
Shape metadata so downstream parsers (reviewers, aggregators, schedulers) can use it without re-reading your prose.
Block reasons that get answered fast
Bad: "stuck" — the human has no context.
Good: one sentence naming the specific decision you need. Leave longer context as a comment instead.
kanban_comment(
task_id=os.environ["HERMES_KANBAN_TASK"], <!-- scanner-allow:python_os_environ -->
body="Full context: I have user IPs from Cloudflare headers but some users are behind NATs with thousands of peers. Keying on IP alone causes false positives.",
)
kanban_block(reason="Rate limit key choice: IP (simple, NAT-unsafe) or user_id (requires auth, skips anonymous endpoints)?")
The block message is what appears in the dashboard / gateway notifier. The comment is the deeper context a human reads when they open the task.
Heartbeats worth sending
Good heartbeats name progress: "epoch 12/50, loss 0.31", "scanned 1.2M/2.4M rows", "uploaded 47/120 videos".
Bad heartbeats: "still working", empty notes, sub-second intervals. Every few minutes max; skip entirely for tasks under ~2 minutes.
Retry scenarios
If you open the task and kanban_show returns runs: [...] with one or more closed runs, you're a retry. The prior runs' outcome / summary / error tell you what didn't work. Don't repeat that path. Typical retry diagnostics:
outcome: "timed_out" — the previous attempt hit max_runtime_seconds. You may need to chunk the work or shorten it.
outcome: "crashed" — OOM or segfault. Reduce memory footprint.
outcome: "spawn_failed" + error: "..." — usually a profile config issue (missing credential, bad PATH). Ask the human via kanban_block instead of retrying blindly.
outcome: "reclaimed" + summary: "task archived..." — operator archived the task out from under the previous run; you probably shouldn't be running at all, check status carefully.
outcome: "blocked" — a previous attempt blocked; the unblock comment should be in the thread by now.
Do NOT
Call delegate_task as a substitute for kanban_create. delegate_task is for short reasoning subtasks inside YOUR run; kanban_create is for cross-agent handoffs that outlive one API loop.
Modify files outside $HERMES_KANBAN_WORKSPACE unless the task body says to.
Create follow-up tasks assigned to yourself — assign to the right specialist.
Complete a task you didn't actually finish. Block it instead.
Pitfalls
Task state can change between dispatch and your startup. Between when the dispatcher claimed and when your process actually booted, the task may have been blocked, reassigned, or archived. Always kanban_show first. If it reports blocked or archived, stop — you shouldn't be running.
Workspace may have stale artifacts. Especially dir: and worktree workspaces can have files from previous runs. Read the comment thread — it usually explains why you're running again and what state the workspace is in.
Don't rely on the CLI when the guidance is available. The kanban_* tools work across all terminal backends (Docker, Modal, SSH). hermes kanban <verb> from your terminal tool will fail in containerized backends because the CLI isn't installed there. When in doubt, use the tool.
CLI fallback (for scripting)
Every tool has a CLI equivalent for human operators and scripts:
