Kanban Worker — Pitfalls and Examples
> 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: | 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 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
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):
For most code-changing tasks, the work isn't truly done until a human reviewer has eyes on it. Block instead of complete, with reason prefixed review-required: so the dashboard surfaces the row as needing review. Drop the structured metadata (changed files, test counts, diff/PR url) into a comment first, since kanban_block only carries the human-readable reason — comments are the durable annotation channel. Reviewer either approves and runs hermes kanban unblock (which re-spawns you with the comment thread for any follow-ups) or asks for changes via another comment.
import json
kanban_comment(
body="review-required handoff:\n" + json.dumps({
"changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
"tests_run": 14,
"tests_passed": 14,
"diff_path": "/path/to/worktree", # or PR url if pushed
"decisions": ["user_id primary, IP fallback for unauthenticated requests"],
}, indent=2),
)
kanban_block(
reason="review-required: rate limiter shipped, 14/14 tests pass — needs eyes on the user_id/IP fallback choice before merging",
)
Use kanban_complete only when the task is genuinely terminal — e.g. a one-line typo fix, a docs change with no functional consequences, or a research task where the artifact IS the writeup itself.
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},
},
)
Review task:
kanban_complete(
summary="reviewed PR #123; 2 blocking issues found (SQL injection in /search, missing CSRF on /settings)",
metadata={
"pr_number": 123,
"findings": [
{"severity": "critical", "file": "api/search.py", "line": 42, "issue": "raw SQL concat"},
{"severity": "high", "file": "api/settings.py", "issue": "missing CSRF middleware"},
],
"approved": False,
},
)
Shape metadata so downstream parsers (reviewers, aggregators, schedulers) can use it without re-reading your prose.
Claiming cards you actually created
If your run produced new kanban tasks (via kanban_create), pass the ids in created_cards on kanban_complete. The kernel verifies each id exists and was created by your profile; any phantom id blocks the completion with an error listing what went wrong, and the rejected attempt is permanently recorded on the task's event log. Only list ids you captured from a successful kanban_create return value — never invent ids from prose, never paste ids from earlier runs, never claim cards another worker created.
# GOOD — capture return values, then claim them.
c1 = kanban_create(title="remediate SQL injection", assignee="security-worker")
c2 = kanban_create(title="fix CSRF middleware", assignee="web-worker")
kanban_complete(
summary="Review done; spawned remediations for both findings.",
metadata={"pr_number": 123, "approved": False},
created_cards=[c1["task_id"], c2["task_id"]],
)
# BAD — claiming ids you don't have captured return values for.
kanban_complete(
summary="Created remediation cards t_a1b2c3d4, t_deadbeef", # hallucinated
created_cards=["t_a1b2c3d4", "t_deadbeef"], # → gate rejects
)
If a kanban_create call fails (exception, tool_error), the card was NOT created — do not include a phantom id for it. Retry the create, or omit the id and mention the failure in your summary. The prose-scan pass also catches t_ references in your free-form summary that don't resolve; these don't block the completion but show up as advisory warnings on the task in the dashboard.
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"],
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 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:
kanban_show ↔ hermes kanban show --jsonkanban_complete ↔ hermes kanban complete --summary "..." --metadata '{...}'kanban_block ↔ hermes kanban block "reason"kanban_create ↔ hermes kanban create "title" --assignee [--parent ]etc.
Use the tools from inside an agent; the CLI exists for the human at the terminal.
Advanced Techniques (2025-2026)
When downstream workers or orchestrators rely on your metadata shape, version it so parsers can handle evolution gracefully:
kanban_complete(
summary="shipped rate limiter",
metadata={
"_schema": "v2", # bump when you change the structure
"changed_files": [...],
"tests_passed": 14,
"decisions": [...],
},
)
Downstream parsers check _schema before accessing fields. If a future revision adds "coverage_pct" or renames "tests_passed" → "test_summary", old parsers can branch on the version instead of crashing on a missing key.
Pre-flight workspace verification
For dir: and worktree workspaces, verify the workspace exists and is writable before starting work:
import os, json
workspace = os.environ.get("HERMES_KANBAN_WORKSPACE", "")
if not workspace or not os.path.isdir(workspace):
kanban_block(reason=f"Workspace {workspace} missing or not a directory — cannot proceed")
For dir: workspaces, check write access
test_file = os.path.join(workspace, ".kanban-write-test")
try:
with open(test_file, "w") as f:
f.write("ok")
os.remove(test_file)
except OSError:
kanban_block(reason=f"Workspace {workspace} is not writable — check ownership/permissions")
This prevents silent failures where a worker spends its entire budget on I/O errors it didn't check for.
Incremental checkpointing
For long-running tasks (compilations, data processing, multi-file edits), write incremental checkpoints to the workspace so that a retry or reclaim doesn't start from zero:
import json, os
workspace = os.environ["HERMES_KANBAN_WORKSPACE"]
checkpoint_path = os.path.join(workspace, ".checkpoint.json")
def save_checkpoint(step, data):
with open(checkpoint_path, "w") as f:
json.dump({"step": step, "data": data}, f)
def load_checkpoint():
if os.path.exists(checkpoint_path):
with open(checkpoint_path) as f:
return json.load(f)
return None
On startup
cp = load_checkpoint()
if cp:
start_step = cp["step"] + 1 # resume after last completed step
else:
start_step = 0
On retry, the next worker picks up from the checkpoint instead of repeating hours of work.
Timeout hints for orchestrator
If your task has a known expected runtime, communicate it via metadata so the orchestrator can set an appropriate max_runtime_seconds:
kanban_create(
title="train model on dataset X",
assignee="ml-worker",
body="Train for 50 epochs on dataset X.",
metadata={"expected_runtime_minutes": 120}, # hint for timeout
)
The orchestrator (or dispatcher) can use expected_runtime_minutes to compute a max_runtime_seconds deadline, preventing the task from hanging indefinitely if the worker crashes mid-run.
Idempotency guards
If your task might be retried or reclaimed, make file writes and external API calls idempotent:
import hashlib, os
def idempotent_write(path, content):
"""Only write if content has changed."""
content_hash = hashlib.sha256(content.encode()).hexdigest()
if os.path.exists(path):
with open(path) as f:
existing_hash = hashlib.sha256(f.read().encode()).hexdigest()
if existing_hash == content_hash:
return # no change — skip write
with open(path, "w") as f:
f.write(content)
This prevents duplicate git commits, double-sends on webhooks, and blanking out files that were correctly written by a previous attempt.
Edge Cases / Pitfalls
Task ownership race condition (15min heartbeat TTL) — The dispatcher grants a worker a 15-minute claim TTL (heartbeat). If your task takes longer than 15 minutes between heartbeat calls, the dispatcher may revoke your claim and reassign. Long-running workers must call kanban_heartbeat regularly — at least every 10 minutes. If you're in a tool call that blocks for >10 minutes, the TTL can expire mid-execution, and a second worker may start the same task. Use incremental checkpointing (above) so the second worker can resume from a known-good state.
Scratch workspace GC race — Scratch workspaces are garbage-collected after task archival. If you write results to a scratch workspace and then immediately try to read them back (e.g., for a final verification), there's a narrow window where the GC may have already cleaned the directory if the orchestrator archived the task quickly. For results that need post-completion access, write them to a dir: workspace or include them directly in kanban_complete metadata.
Kanban AI Worker 2025
AI-driven enhancements to the Kanban worker lifecycle — from LLM-assisted status transitions to automated summarization and workload balancing.
AI-Powered Task Status Transitions
Use LLM analysis of completed work to automatically determine the next card state, reducing manual triage:
# After completing a task, let the LLM assess follow-up actions
completion_metadata = kanban_complete(
summary="implemented rate limiter — token bucket with user_id keys, 14/14 tests pass",
metadata={
"changed_files": ["rate_limiter.py"],
"tests_passed": 14,
"has_open_pull_request": True,
"breaking_changes": False,
"deployed_to_staging": True,
},
)
The orchestrator or a post-completion hook can use metadata to auto-transition:
- has_open_pull_request=True → create review card automatically
- breaking_changes=True → create migration card
- deployed_to_staging=True → create smoke-test card
Pattern: Encode transition logic in metadata so the orchestrator's dispatcher can make data-driven decisions without another LLM call. Reserve LLM-based classification for ambiguous cases where structured metadata alone isn't sufficient.
Automated Card Summaries
Instead of requiring workers to craft summaries manually, generate them from workspace artifacts when the worker forgets or provides sparse output:
# Worker-provided summary (sparse)
kanban_complete(summary="did the thing", metadata={...})
Orchestrator post-process: generate rich summary from artifacts
1. Read the workspace diff / changed files
2. Feed to LLM with context: "Summarize these changes in 2-3 sentences"
kanban_comment(
task_id=task_id,
body=f"[Auto-summary] {llm_generated_summary}\n\nSource: workspace diff analysis",
)
When to auto-summarize:
Worker summary is under 20 characters or generic ("done", "completed")metadata.changed_files is non-empty but summary doesn't mention any of themRetry runs where context from previous failures needs consolidation
Workload Balancing Suggestions
Analyze the kanban board state to recommend task distribution across workers:
# Query board state for balancing
board_state = kanban_board_stats() # hypothetical or derived from list/show
LLM-assisted workload analysis prompt:
analysis_prompt = """
Given the current kanban board state:
In-progress tasks: {in_progress_count}
Blocked tasks: {blocked_count}
Per-worker task counts: {worker_task_counts}
Average task age: {avg_age_hours}
Suggest:
Which workers are underutilized and can take more tasks
Which tasks are at risk of timeout based on age and priority
Whether to create new tasks or redistribute existing ones
"""
Heuristics for balancing:
Workers with 0 in-progress tasks for >15 minutes → flag as underutilizedTasks blocked for >24 hours → surface for human attentionTasks approaching max_runtime_seconds without heartbeat → flag for preemptionWorkers averaging <2 minute task completion → consider consolidating their queue into batch tasks
Natural Language Task Updates
Allow non-technical stakeholders to update card state via natural language, parsed by the worker or orchestrator:
# Natural language input from a non-technical reviewer
human_comment = "Looks good to me, ship it but keep an eye on the dashboard metrics"
LLM parses into structured updates
parsed = parse_nl_update(human_comment)
{
"status_transition": "approved",
"follow_up_actions": ["create monitoring card for dashboard metrics"],
"priority_adjustment": None,
"blocking_reason": None,
}
Apply structured updates
kanban_comment(task_id=task_id, body=f"Reviewer: {human_comment}")
kanban_complete(
summary=f"Approved by reviewer — {parsed['status_transition']}",
metadata={"nl_source": human_comment, "parsed_actions": parsed["follow_up_actions"]},
)
Create follow-up cards from parsed actions
for action in parsed["follow_up_actions"]:
kanban_create(title=action, assignee="monitoring-worker")
Implementation notes: Natural language parsing is best done by the orchestrator (not the worker) so task state transitions remain deterministic within worker runs. Workers should only process NL if explicitly assigned a parsing task.