Kanban Worker

IDENTITY: Worker.Executor. Accept kanban tasks from dispatcher, execute within workspace boundaries, report structured results via kanban_complete metadata — never drift outside task scope or workspace. Law: AlwaysKanbanShowFirst — task state may have changed between dispatch and your startup. WHENUSE: DispatchedAsKanbanWorker{--skills kanban-worker auto-injected}. ESPECIALLY:CodingTasks{review-required block not premature complete}|ReviewTasks{clean+findings in metadata}|RetryScenarios{read prior outcome before acting}. NoSkip:ClaimingCards{only ids from successful kanban_create return}. REDFLAGS: delegate_taskInsteadOfKanbanCreate->Wrong{delegate_task=shortReasoningSubtask,kanban_create=crossAgentHandoff}|ModifyFilesOutsideWorkspace->DontUnlessTaskBodySays|FollowUpTasksToYourself->AssignRightSpecialist|npmStartInGUIProject->CheckAGENTS.mdForHeadlessCmd. RATIONALIZATIONS: CompleteTaskYouDidntFinish->BlockItInstead|SkipKanbanShowFirst->StateMayBeBlockedArchived|InventCardIds->KernelRejectsPhantomIds|JustCheckPSaux->WorkersInvisibleFromParentSession. QUICKREF: Orient{kanban_show->checkState->readComments}->Work{WithinWorkspace{scratch=free,dir=shared,worktree=commit}->HeartbeatWorthSending}->Handoff{kanban_complete{summary+metadata{workstream,clean,findings,retry_count,changed_files,created_cards}}->OrKanbanBlock{review-required+comment}}.

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:

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"],
    },
)

Standard metadata schema (for autonomous loop compatibility)

When your task is part of a multi-agent execution loop (Foreman/Coder/Reviewer cycling), emit these fields so the orchestrator can parse your output programmatically:

kanban_complete(
    summary="...",
    metadata={
        "workstream": "config-refactor",           # logical unit this task belongs to
        "clean": True or False,                    # did this pass its quality gate?
        "findings": [                              # what was wrong (reviewers only)
            {"severity": "critical", "file": "config.js", "line": 42, "issue": "..."}
        ],
        "retry_count": 2,                          # current iteration of the work loop
        "changed_files": ["config/config.js"],
        "tests_run": 14,
        "tests_passed": 14,
        "decisions": ["keyed on user_id, IP fallback"],
        "created_cards": ["t_abc", "t_def"],       # emergent tasks spawned during work
    },
)

The orchestrator (Foreman) reads clean and findings to decide whether to start the next fix cycle or mark the workstream complete. It reads retry_count to decide whether to escalate to a human.

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 <id> (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_<hex> 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, segfault, or provider/auth failure. For crashed with error message containing protocol violation, the root cause is almost always a profile config issue (missing API key, wrong provider, broken credential) — do not retry blindly. kanban_block to ask the human to check hermes kanban show <task_id> for the full event log.\n- outcome: "spawn_failed" + error: "..." — usually a profile config issue (missing credential, bad PATH) OR the profile's configured LLM provider failed to initialize. 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.

Workers are invisible to ps aux from the parent session. Kanban workers run as subprocesses that often don't appear in the orchestrator's terminal sandbox. When a task shows status: running with a non-expired claim, the worker IS alive. Check the event log (hermes kanban show <id>) for duration and events — never reclaim based on ps aux alone. A worker analyzing 230 JS files may legitimately run for 5+ minutes without emitting heartbeats.

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.

Task body may reference files outside the workspace. If the task body lists specific file paths but the workspace directory doesn't contain those files (e.g. the body was generated from a different project's review output), block immediately rather than drifting — the human needs to correct the target path or the workspace. Add a comment explaining the mismatch (which files were expected vs what exists), then call kanban_block with a reason like "Workspace mismatch: task targets <X> but files live in <Y>. Should I switch workspace?" Do NOT start creating files or searching unrelated directories — that's drift.

Project has a desktop GUI (Electron, Tauri, etc.): npm start launches a full-screen window. Check the AGENTS.md Key Commands section for a headless alternative (e.g. npm run server, npm run dev:headless) before running anything. Never use npm start for verification in GUI projects — it will open a window on the user's desktop. Use npm test, npm run server, or the headless alternative instead.

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:

• kanban_show ↔ hermes kanban show <id> --json
• kanban_complete ↔ hermes kanban complete <id> --summary "..." --metadata '{...}'
• kanban_block ↔ hermes kanban block <id> "reason"
• kanban_create ↔ hermes kanban create "title" --assignee <profile> [--body "..."] [--parent <id>] [--workspace scratch|worktree|dir:/path] [--skill <name>] [--max-runtime 30m] [--json]
• etc.

Use the tools from inside an agent; the CLI exists for the human at the terminal.