Kanban Worker

---
name: kanban-worker
description: 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.
version: 2.0.0
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [kanban, multi-agent, collaboration, workflow, pitfalls]
    related_skills: [kanban-orchestrator]
---

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`:

| 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:**
```python
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:

```python
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
    },
)
```

| Field | Type | When required |
|---|---|---|
| `workstream` | string | Always — groups related tasks under one logical unit |
| `clean` | boolean | Review tasks only — signals pass/fail to the orchestrator |
| `findings` | list[dict] | Review tasks only — what to fix in the next cycle |
| `retry_count` | int | Always — lets the orchestrator enforce escalation thresholds |
| `changed_files` | list[str] | Coder tasks — what files were modified |
| `created_cards` | list[str] | Any task that spawned emergent 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.

```python
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:**
```python
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:**
```python
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.**

```python
# 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"]],
)
```

```python
# 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.

```python
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.