kanban-worker

Kanban Worker — Pitfalls and Examples

kanban-worker: this is the detail layer.

Sub-steps with task()

When your task requires sub-steps (analysis → implementation → testing), use task(subagent_type="<name>", description="summary", prompt="...") to spawn subagents. Types: explorer, implementer, tester, reviewer. The subagent_type parameter is built into the task tool schema — discoverable without loading a skill.

For worktree-isolated or tmux-parallel work, use gjc_delegate_execute / gjc_delegate_team via GJC Coordinator MCP.

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