kanban-orchestrator

name	kanban-orchestrator
description	Decomposition playbook + specialist-roster conventions + anti-temptation rules for an orchestrator profile routing work through Kanban. The "don't do the work yourself" rule and the basic lifecycle are auto-injected into every kanban worker's system prompt; this skill is the deeper playbook when you're specifically playing the orchestrator role.
version	2.0.0
metadata	{"hermes":{"tags":["kanban","multi-agent","orchestration","routing"],"related_skills":["kanban-worker"]}}

Kanban Orchestrator — Decomposition Playbook

The core worker lifecycle (including the kanban_create fan-out pattern and the "decompose, don't execute" rule) is auto-injected into every kanban process via the KANBAN_GUIDANCE system-prompt block. This skill is the deeper playbook when you're an orchestrator profile whose whole job is routing.

When to use the board (vs. just doing the work)

Create Kanban tasks when any of these are true:

1. Multiple specialists are needed. Research + analysis + writing is three profiles.
2. The work should survive a crash or restart. Long-running, recurring, or important.
3. The user might want to interject. Human-in-the-loop at any step.
4. Multiple subtasks can run in parallel. Fan-out for speed.
5. Review / iteration is expected. A reviewer profile loops on drafter output.
6. The audit trail matters. Board rows persist in SQLite forever.

If none of those apply — it's a small one-shot reasoning task — use delegate_task instead or answer the user directly.

The anti-temptation rules

Your job description says "route, don't execute." The rules that enforce that:

• Do not execute the work yourself. Your restricted toolset usually doesn't even include terminal/file/code/web for implementation. If you find yourself "just fixing this quickly" — stop and create a task for the right specialist.
• For any concrete task, create a Kanban task and assign it. Every single time.
• If no specialist fits, ask the user which profile to create. Do not default to doing it yourself under "close enough."
• Decompose, route, and summarize — that's the whole job.

The standard specialist roster (convention)

Failure Modes

Failure	Prevention
Subagent planning wave exceeds requested cap after retrying timed-out lanes	Treat the user-requested subagent cap as a total-attempt budget, not only completed results. If a lane times out, report the timeout and ask before replacement attempts unless the user explicitly authorized retries beyond the cap.
delegate_task children time out before first LLM request when launched with an empty toolset	Do not pass toolsets: [] for no-tool planning. Use a minimal toolset such as ['terminal'] and explicitly instruct the child not to call tools, or omit toolsets only when inherited tool access is acceptable.
Codex planning/implementation launched with -C <worktree> cannot write logs/artifacts to the orchestrator root because the sandbox is scoped to the worktree	Put prompt files, logs, and expected outputs inside the same worktree or use /tmp for transient logs, then copy verified artifacts back deliberately. Do not expect a Codex sandboxed worker to write directly into the parent/orchestrator checkout.
researcher	Reads sources, gathers facts, writes findings
analyst	Synthesizes, ranks, de-dupes. Consumes multiple researcher outputs
writer	Drafts prose in the user's voice
reviewer	Reads output, leaves findings, gates approval
backend-eng	Writes server-side code
frontend-eng	Writes client-side code
ops	Runs scripts, manages services, handles deployments
pm	Writes specs, acceptance criteria

Decomposition playbook

Step 1 — Understand the goal

Ask clarifying questions if the goal is ambiguous. Cheap to ask; expensive to spawn the wrong fleet.

Step 2 — Sketch the task graph

Before creating anything, draft the graph out loud (in your response to the user). Example for "Analyze whether we should migrate to Postgres":

T1  researcher        research: Postgres cost vs current
T2  researcher        research: Postgres performance vs current
T3  analyst           synthesize migration recommendation       parents: T1, T2
T4  writer            draft decision memo                       parents: T3

Show this to the user. Let them correct it before you create anything.

Step 3 — Create tasks and link

t1 = kanban_create(
    title="research: Postgres cost vs current",
    assignee="researcher",
    body="Compare estimated infrastructure costs, migration costs, and ongoing ops costs over a 3-year window. Sources: AWS/GCP pricing, team time estimates, current Postgres bills from peers.",
    tenant=os.environ.get("HERMES_TENANT"),
)["task_id"]

t2 = kanban_create(
    title="research: Postgres performance vs current",
    assignee="researcher",
    body="Compare query latency, throughput, and scaling characteristics at our expected data volume (~500GB, 10k QPS peak). Sources: benchmark papers, public case studies, pgbench results if easy.",
)["task_id"]

t3 = kanban_create(
    title="synthesize migration recommendation",
    assignee="analyst",
    body="Read the findings from T1 (cost) and T2 (performance). Produce a 1-page recommendation with explicit trade-offs and a go/no-go call.",
    parents=[t1, t2],
)["task_id"]

t4 = kanban_create(
    title="draft decision memo",
    assignee="writer",
    body="Turn the analyst's recommendation into a 2-page memo for the CTO. Match the tone of previous decision memos in the team's knowledge base.",
    parents=[t3],
)["task_id"]

parents=[...] gates promotion — children stay in todo until every parent reaches done, then auto-promote to ready. No manual coordination needed; the dispatcher and dependency engine handle it.

Step 4 — Complete your own task

If you were spawned as a task yourself (e.g. planner profile was assigned T0: "investigate Postgres migration"), mark it done with a summary of what you created:

kanban_complete(
    summary="decomposed into T1-T4: 2 researchers parallel, 1 analyst on their outputs, 1 writer on the recommendation",
    metadata={
        "task_graph": {
            "T1": {"assignee": "researcher", "parents": []},
            "T2": {"assignee": "researcher", "parents": []},
            "T3": {"assignee": "analyst", "parents": ["T1", "T2"]},
            "T4": {"assignee": "writer", "parents": ["T3"]},
        },
    },
)

Step 5 — Report back to the user

Tell them what you created in plain prose:

I've queued 4 tasks:

• T1 (researcher): cost comparison
• T2 (researcher): performance comparison, in parallel with T1
• T3 (analyst): synthesizes T1 + T2 into a recommendation
• T4 (writer): turns T3 into a CTO memo

The dispatcher will pick up T1 and T2 now. T3 starts when both finish. You'll get a gateway ping when T4 completes. Use the dashboard or hermes kanban tail <id> to follow along.

Common patterns

GitHub-label-derived portfolio board: When the work already exists as GitHub issues across multiple repos, do not create a separate manual Kanban queue first. Build a label-derived board/dashboard view, classify by plan-gate labels and local approval evidence, and use it to choose the next small execution/governance/planning batches. For tier-1 repo boards, include per-issue AI provider/reviewer routing, machine routing, explicit decision/user-input lanes, and standing structure/test/CI/cross-review gates. When the user asks how to feed Hermes/AI swarms, add bounded ~5-hour recommendation packets derived from the board and verify every referenced issue live. See references/github-label-derived-portfolio-board.md for the proven collection, lane, artifact, recommendation-packet, provider/machine routing, and verification pattern.

Provider-credit approval control board: When the goal is to reduce wasted weekly provider quota, treat Kanban as a safe pull system, not as permission for agents to wander. Use lanes for planning feedstock, plan-review/approval candidates, execution-ready, running/leased, and QA/closeout. Approval affordances in an HTML/dashboard view must be backed by an auditable transaction: re-check live GitHub state, canonical docs/plans/ artifact, review artifacts with no latest MAJOR/FAIL/UNAVAILABLE/pending verdict, approval marker path, label transition, GitHub comment, and queue refresh. If no approved implementation work exists, route credits to planning/recon/review lanes instead of unapproved implementation. Running cards need owner/lease/idempotency metadata so the same issue is not double-dispatched. See agent-usage-optimizer/references/kanban-approval-control-plane.md for the detailed weekly anti-waste loop and dashboard-field contract.

Fan-out + fan-in (research → synthesize): N researcher tasks with no parents, one analyst task with all of them as parents.

Pipeline with gates: pm → backend-eng → reviewer. Each stage's parents=[previous_task]. Reviewer blocks or completes; if reviewer blocks, the operator unblocks with feedback and respawns.

Same-profile queue: 50 tasks, all assigned to translator, no dependencies between them. Dispatcher serializes — translator processes them in priority order, accumulating experience in their own memory.

Human-in-the-loop: Any task can kanban_block() to wait for input. Dispatcher respawns after /unblock. The comment thread carries the full context.

Pitfalls

Reassignment vs. new task. If a reviewer blocks with "needs changes," create a NEW task linked from the reviewer's task — don't re-run the same task with a stern look. The new task is assigned to the original implementer profile.

Argument order for links. kanban_link(parent_id=..., child_id=...) — parent first. Mixing them up demotes the wrong task to todo.

Don't pre-create the whole graph if the shape depends on intermediate findings. If T3's structure depends on what T1 and T2 find, let T3 exist as a "synthesize findings" task whose own first step is to read parent handoffs and plan the rest. Orchestrators can spawn orchestrators.

Tenant inheritance. If HERMES_TENANT is set in your env, pass tenant=os.environ.get("HERMES_TENANT") on every kanban_create call so child tasks stay in the same namespace.

Recovering stuck workers

When a worker profile keeps crashing, hallucinating, or getting blocked by its own mistakes (usually: wrong model, missing skill, broken credential), the kanban dashboard flags the task with a ⚠ badge and opens a Recovery section in the drawer. Three primary actions:

1. Reclaim (or hermes kanban reclaim <task_id>) — abort the running worker immediately and reset the task to ready. The existing claim TTL is ~15 min; this is the fast path out.
2. Reassign (or hermes kanban reassign <task_id> <new-profile> --reclaim) — switch the task to a different profile and let the dispatcher pick it up with a fresh worker.
3. Change profile model — the dashboard prints a copy-paste hint for hermes -p <profile> model since profile config lives on disk; edit it in a terminal, then Reclaim to retry with the new model.

Hallucination warnings appear on tasks where a worker's kanban_complete(created_cards=[...]) claim included card ids that don't exist or weren't created by the worker's profile (the gate blocks the completion), or where the free-form summary references t_<hex> ids that don't resolve (advisory prose scan, non-blocking). Both produce audit events that persist even after recovery actions — the trail stays for debugging.