kanban-orchestrator

# 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. ## Profiles are user-configured — not a fixed roster Hermes setups vary widely. Some users run a single profile that does everything; some run a small fleet (`docker-worker`, `cron-worker`); some run a curated specialist team they've named themselves. There is **no default specialist roster** — the orchestrator skill does not know what profiles exist on this machine. Before fanning out, you must ground the decomposition in the profiles that actually exist. The dispatcher silently fails to spawn unknown assignee names — it doesn't autocorrect, doesn't suggest, doesn't fall back. So a card assigned to `researcher` on a setup that only has `docker-worker` just sits in `ready` forever. **Step 0: discover available profiles before planning.** Default mechanics for ordinary orchestrators: - `hermes profile list` — prints the table of profiles configured on this machine. Run it through your terminal tool if you have one; otherwise ask the user. - `kanban_list(assignee="<some-name>")` — sanity-check a single name. Returns an empty list (rather than an error) for an unknown assignee, so this only confirms a name you're already considering. - **Just ask the user.** "What profiles do you have set up?" is a fine first turn when the goal needs more than one specialist. Cache the result in your working memory for the rest of the conversation. Re-asking every turn wastes a tool call. **三省六部 / Regent correction (2026-05): department roster is NOT 吏部 work.** In the governed Regent setup, the main Regent must not personally run `hermes profile list` for a multi-step/fan-out task. If available department agents/profiles are needed, create a **尚书省 / dispatcher / registry** Kanban card to inventory the department roster and suggest assignments, then let 中书拟制 based on that handoff. **吏部 is only for expert/talent pools** (external specialists, agency-agents-zh style expert roles, reserve officials), not for listing the standing 三省六部 department agents. For trivial one-shot tasks where no roster choice matters, skip this step entirely rather than over-bureaucratizing. ## 🚨 Red Flags: DO NOT SKIP THIS SKILL | Excuse your brain will make | Why it's wrong | |------------------------------|----------------| | "This is just research — I can do it myself faster" | The user did NOT agree. Research tasks qualify for Kanban: planner→reviewer→archivist. Direct execution is the #1 anti-pattern | | "I'll just find files before creating the task" | One `find` is acceptable; two+ discovery calls = you're doing the planner's job. Create the Kanban task with discovered paths in the body | | "The Emperor said 好/🉑, let me confirm before building" | Approval IS the signal to act. Asking "是否开干?" again wastes a full round-trip — immediately build the chain | | "It's a simple file merge, I'll handle it inline" | File operations that look trivial (cp, fix heading, add cross-refs) are still multi-step governance work. The Emperor corrected this with "交给史官干呀" | | "delegate_task is faster than Kanban for this read-only analysis" | Governance assessment (reading 三省六部 docs, judging architecture gaps) is itself governance work — use Kanban with durable trail, not synchronous delegate | **The counter on this page grows because each trap has been triggered at least once in real sessions. The Emperor has corrected the orchestrator 6+ times for these exact rationalizations.** ## 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. 7. **planner-first governance.** The task type falls in the planner-first mandatory list — visual/PDF delivery, multi-node complex coordination, new skill/first-run, multi-step制度修改, or any task with multi-round acceptance risk. These must go through planner plan-preview before execution cards are created. 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. - **Split multi-lane requests before creating cards.** A user prompt can contain several independent workstreams. Extract those lanes first, then create one card per lane instead of bundling unrelated work into a single implementer card. - **Run independent lanes in parallel.** If two cards do not need each other's output, leave them unlinked so the dispatcher can fan them out. Link only true data dependencies. - **Never create dependent work as independent ready cards.** If a card must wait for another card, pass `parents=[...]` in the original `kanban_create` call. Do not create it first and link it later, and do not rely on prose like "wait for T1" inside the body. - **If no specialist fits the available profiles, ask the user which profile to create or which existing profile to use.** Do not invent profile names; the dispatcher will silently drop unknown assignees. - **Decompose, route, and summarize — that's the whole job.** **三省六部 / Regent persona extra rule:** When the user runs a governed multi-agent system with named ministry profiles (planner, reviewer, engineer, auditor, archivist), **default to Kanban for any multi-step task** — including research, analysis, and synthesis. Do not reach for `delegate_task` as a shortcut, even if the task seems like a one-shot. The user created those profiles for a reason; skipping them breaks the governance model they explicitly set up. If the user scolds you for bypassing the system once, the next attempt MUST use Kanban. **尚书省 mandatory insertion (2026-05-25 制度补丁):** 任何多步骤 Kanban 链，门下封驳通过后**必须插入尚书省协调卡**，再下接工部/御史/史馆。模式：`planner → reviewer → SHANGSHU → [engineer, auditor, archivist] → final reviewer`。尚书省不只是"部门盘点"，它是执行总枢（L1 派发 / L2 协调 / L3 汇总）。不得以"固定链路/通路 C 简径"为由跳过——跳过的是 pre-planning 部门盘点，不是尚书省在 execution chain 中的协调位置。全板仅有 2 个 shangshu done 任务即为制度缺口证据。 **Grill Gate（grill-me / grill-with-docs 吸收，2026-05-25）：** 承旨后若需求存在歧义，监国太子必须先追问（≥2 轮）方可拟制。门下封驳时须用既有制度文档（SOUL、constitution、kanban-orchestrator、Obsidian CONTEXT/ADR）拷问方案。需求歧义时中书省应建 `grill-required` 决策卡，格式如下： ```yaml # Grill Decision Card question: "歧义点描述" context: "父皇原文 / 相关制度条款" interpretation_a: "孤的理解 A" interpretation_b: "孤的理解 B（或其他可能性）" recommendation: "孤推荐的理解及理由" impact: "不同理解对方案的影响" ``` **吏部 vs 尚书/三省 边界（2026-05-19 补正）：** 当需要「盘点可用部门 agent / profile 名册」时，此活归 **尚书/dispatcher/三省调度体系**，不归吏部。**吏部只管专家/人才库**（如 agency-agents-zh 精选专家、外部人才引进）。不可把「部门职能名册盘点」派给吏部/registry profile。 **The &quot;it&#039;s just research&quot; trap:** The most common rationalization for bypassing 三省六部 is thinking &quot;this is just web research / document synthesis / reading files — I can do it faster myself.&quot; The user does NOT agree. Research tasks qualify for Kanban: planner researches and drafts, reviewer checks, archivist files. The orchestrator doing the work is the #1 anti-pattern. If you catch yourself thinking &quot;this is simple enough to do inline,&quot; stop and create a Kanban task for the planner instead. Two bypasses in one session = the orchestrator has failed its primary duty. **The &quot;just finding files&quot; variant:** A sneaky sub-form — the orchestrator runs `search_files` to &quot;just find where the Obsidian docs are&quot; or `execute_code` to &quot;just list what's in a directory before creating the task.&quot; This is still bypassing 三省六部. The planner should do its own discovery. If the orchestrator must locate something before creating a task, *one* `find` or `search_files` is acceptable — then immediately create the Kanban task with the discovered paths in the body. Two or more discovery calls = you're doing the planner's job. **The &quot;just ask one more time&quot; trap (NEW — 2026-05-27):** After presenting a plan and the Emperor says &quot;好/可以/🉑/执行/开干&quot;, DO NOT ask &quot;是否开干？&quot; or &quot;是否准奏？&quot; again in the next turn. Just start building the Kanban chain. The Emperor's approval is the signal to ACT, not to seek confirmation of the confirmation. This happened in the morning-news session: the plan was presented, the Emperor approved (&quot;好&quot;), and the orchestrator responded with another &quot;是否开干？&quot; — wasting a full round-trip. Once approved, the only acceptable next turn is chain creation + dispatch. Combine with the 太子主动轮询模式: present plan, get approval, immediately build chain, then track every stage without waiting for prompts. **The "just merge files" variant (NEW — 2026-05-18):** When the user says "merge these archives into the knowledge base," the orchestrator's instinct is to `read_file` the docs, plan the edits, and `patch`/`write_file` the changes. This is bypassing 三省六部 — it is the archivist's and engineer's job, not the orchestrator's. File-merge operations that look trivial (cp a file, fix a heading, add cross-references) are still multi-step governance work that should go through planner→reviewer→engineer→auditor→archivist. The Emperor corrected this directly with "交给史官干呀" — the archivist is the specialist for knowledge base operations. If you catch yourself reading files to "understand what needs merging," stop and create a Kanban task for the planner instead. **The "delegate_task instead of 三省六部" variant (NEW — 2026-05-20):** When the user asks to update Obsidian governance documents (especially 三省六部 / 监国太子制度 docs), do **not** substitute `delegate_task` for the formal Kanban chain. A synchronous delegate can be interrupted with the parent turn and produces no durable board trail; the Emperor explicitly corrected this with "用三省六部制度执行啊" after a failed delegate_task attempt. Correct pattern: create a serial Kanban chain `planner → reviewer → archivist → auditor`, with dependencies bound at creation time. If the reviewer blocks the plan, create a new planner revision + new reviewer, then rewire downstream archivist away from the blocked reviewer parent so it is not stuck behind a blocked ancestor. **The "governance assessment via delegate_task" variant (NEW — 2026-05-24):** Reading 三省六部/Regent documents and judging multi-agent architecture gaps is itself governance work, even if it looks like a read-only analysis. Do not use `delegate_task` for this class. Use Kanban with at least `planner → reviewer → auditor` so document discovery, plan-preview, fact-checking, and boundary review have a durable trail. The Regent may do only a start-of-turn board check and final synthesis; if a prior `delegate_task` was started, treat it as a boundary violation, stop relying on it, and create the formal chain immediately. **The "board clear, but regent silent" variant (NEW — 2026-05-25, 第7次纠正):** The entire Kanban board clears (all chains done, 0 active tasks), the watchdog delivery bridge fires correctly, but the Regent still does not proactively report completion to the Emperor. This is the last-mile gap: the push pipe works (watchdog → Telegram), but the Regent fails to notice the delivery bridge, fetch task summaries, and synthesize a human-readable复命. The Emperor corrected this with "看板已经清空了，但是你没有主动向我汇报". Fix: SOUL.md 第11条启动铁律 mandates a start-of-turn `hermes kanban list --json` check; if all previously-active chains are now done/archived, immediately report with concise per-card summaries. This is NOT solved by more automation — the gap is behavioral. The watchdog's raw推送 is evidence, not delivery; the Regent must be the final human-facing gate. **Kanban "done" is not delivery.** A task status of `done` only means the worker exited through protocol; the orchestrator must still receive the artifact, read/verify the run summary/workspace path, and decide whether downstream fan-in/review/audit/delivery cards are missing. If the user asks about completed chains (e.g. "早新闻和P0"), do not merely report statuses. Fetch the task outputs, summarize artifact paths, identify missing final stages, and immediately create the missing Kanban cards. This prevents the false closure pattern: `done` leaf tasks with no final synthesis or user-facing result. When the user asks "然后呢？" after a `done` report, treat it as a delivery-gap signal: either deliver the approved artifact now (path + concise summary) or route the next necessary closure step (e.g. git diff triage / final review) through Kanban. **Artifact persistence for downstream audit/delivery.** If a downstream card must inspect artifacts from an upstream worker (PDFs, screenshots, generated reports, exported HTML, audio/video, etc.), do **not** rely on scratch workspaces that may be garbage-collected before audit/final delivery. Create or instruct workers to use a persistent workspace under `~/.hermes/workspaces/<task-slug>/`, and include that absolute path plus expected artifact filenames in both the upstream completion summary and downstream card bodies. This avoids the failure pattern where render succeeds, but audit/final-review blocks because the scratch directory vanished. See `references/persistent-artifact-workspaces.md`. **Watchdog/cron output is not formal delivery.** The watchdog may correctly push raw transitions such as "engineer done" or "batch cleared," but the Regent still owes a concise human-facing复命: what completed, whether review/audit approved, artifact paths if relevant, and whether anything remains. If the user says "Kanban结果有了，你也没有主动汇报/处理," treat it as a governance failure: immediately inspect current board + relevant task summaries/final-results, perform any missing closure action, then report in ≤6 lines. Do not defend that cron already emitted a notification; raw monitoring signals are evidence, not delivery. **Watchdog stale-blocked false alerts (NEW — 2026-05-25).** When a reviewer REJECTs a plan and a v2/v3 revision chain is created, the original v1 blocked card stays on the board as audit trail. After 30+ minutes, the watchdog fires an A-level "needs Emperor decision" alert — but the v1 card is stale, superseded by the running/done v2/v3 chain. The `_is_blocked_superseded()` heuristic in the watchdog (v3.1) detects this: it checks if a newer version of the same task chain exists in `running`/`done` and downgrades the alert to C-level (silent). When this false alert fires, archive the stale blocked card and verify the watchdog has v3.1+. See `references/stale-blocked-card-suppression.md` for the full heuristic, test scenarios, and integration. This happened twice in one session: t_8b0f77b1 (edict v1) and t_e1b1bced (p0 v1), both correctly suppressed after the fix. **Kanban "blocked" is not always unhandled.** In setups with a coordinator poll, a visible blocked card may coexist with an auto-created recovery chain. Before telling the user "still blocked" or creating new repair cards, check recent coordinator event files / final-results and recent board tasks for follow-up cards spawned after the block. Report the real chain state: original blocker, recovery card(s), review/audit card(s), and whether closure/archival is still missing. **Blocked final-review requires immediate recovery, not status-only reporting.** If a final reviewer blocks after upstream execution/audit mostly passed, inspect the block reason and create the narrow recovery chain immediately (`fix → review → final closure`). This is especially common when canonical docs were updated but a mirror/registry copy (e.g. `~/.hermes/notes/agent-registry.md`) was not synchronized. Do not just tell the Emperor "blocked"; repair or route the repair in the same turn, then report the running recovery card. Full checklist: `references/blocked-final-review-mirror-sync.md`. **Partial completion wording:** When a multi-part initiative has subtracks (P0-1/P0-2/P0-3), never collapse a completed subtrack into "P0 complete." Report the exact scope: "P0-1 complete; P0-2/P0-3 pending." Before saying a whole initiative is complete, query all sibling cards/root cards and verify implementation + review for each accepted subtrack. The Emperor explicitly corrected the Regent for bypassing or passivity **six separate times** across sessions. The third correction ("你不要自己干活") happened during what the orchestrator thought was innocuous file-path discovery. The fourth correction ("交给史官干呀") happened when the Regent started reading and planning a knowledge-base merge — file operations that looked trivial but were the archivist's domain. The fifth correction ("每次都要我点进度") happened when the Regent dispatched tasks and went silent, waiting for the Emperor to ask "进度怎么样了？" The sixth correction ("你现在都不用看板了吗") happened when the Emperor approved a P0 plan with "可以" and the Regent verbally acknowledged without creating any Kanban tasks — treating approval as case-closed instead of the signal to build the board. The Emperor's frustration: he should never have to prompt for progress — the orchestrator must actively monitor and report proactively. This is now mandatory (see Step 5 — Monitor proactively). The lesson: when the Emperor has invested in a 三省六部 fleet, treat ANY multi-step information-gathering or file operation as Route-Through-Kanban territory. Direct execution is the exception, not the rule. ## 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). Treat every concrete workstream as a candidate card: 1. Extract the lanes from the request. 2. Map each lane to one of the profiles you discovered in Step 0. If a lane doesn't fit any existing profile, ask the user which to use or create. 3. Decide whether each lane is independent or gated by another lane. 4. Create independent lanes as parallel cards with no parent links. 5. Create synthesis/review/integration cards with parent links to the lanes they depend on. A child created with unfinished parents starts in `todo`; the dispatcher promotes it to `ready` only after every parent is done. 6. **planner-first gate**: if the task type is in the planner-first mandatory list (complex/visual/PDF delivery, multi-node, new skill,制度修改, multi-round acceptance risk), create a **planner card first** (assignee=planner), let it produce a plan-preview artifact, and only after the planner card is `done` create the downstream execution cards with `parents=[planner_card_id]`. This prevents execution before direction is settled. Examples of prompts that should fan out (using placeholder profile names — substitute whatever exists on the user's setup): - "Build an app" → one card to a design-oriented profile for product/UI direction, one or two cards to engineering profiles for implementation, plus a later integration/review card if the user has a reviewer profile. - "Fix blockers and check model variants" → one implementation card for the blocker fixes plus one discovery/research card for config/source verification. A final reviewer card can depend on both. - "Research docs and implement" → a docs-research card can run in parallel with a codebase-discovery card; implementation waits only if it truly needs those findings. - "Analyze this screenshot and find the related code" → one card to a vision-capable profile for the visual analysis while another searches the codebase. Words like "also," "finally," or "and" do not automatically imply a dependency. They often mean "make sure this is covered before reporting back." Only link tasks when one card cannot start until another card's output exists. Show the graph to the user before creating cards. Let them correct it — including which actual profile name should own each lane. ### Step 3 — Create tasks and link Use the profile names from Step 0. The example below uses placeholders `<profile-A>`, `<profile-B>`, `<profile-C>` — replace them with what the user actually has. ```python t1 = kanban_create( title="research: Postgres cost vs current", assignee="<profile-A>", # whichever profile handles research on this setup 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="<profile-A>", # same profile, run in parallel 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="<profile-B>", # whichever profile does synthesis/analysis 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="<profile-C>", # whichever profile drafts user-facing prose 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. If the task graph has dependencies, create the parent cards first, capture their returned ids, and include those ids in the child card's `parents` list during the child `kanban_create` call. Avoid creating all cards in parallel and linking them afterward; that creates a window where the dispatcher can claim a child before its inputs exist. ### Step 4 — Complete your own task If you were spawned as a task yourself (e.g. a planner profile was assigned `T0: "investigate Postgres migration"`), mark it done with a summary of what you created: ```python kanban_complete( summary="decomposed into T1-T4: 2 research lanes in parallel, 1 synthesis on their outputs, 1 prose draft on the recommendation", metadata={ "task_graph": { "T1": {"assignee": "<profile-A>", "parents": []}, "T2": {"assignee": "<profile-A>", "parents": []}, "T3": {"assignee": "<profile-B>", "parents": ["T1", "T2"]}, "T4": {"assignee": "<profile-C>", "parents": ["T3"]}, }, }, ) ``` ### Step 5 — Deploy watchdog and monitor proactively (MANDATORY) **Telegram orchestrators CANNOT poll in a loop** — the platform is request-response, and the agent only acts when the user sends a message. Manual `hermes kanban show` polls only work when the user messages, which means the user has to ask "进度？" — which the Emperor explicitly hates. **The solution: deploy the kanban-watchdog cron pattern once per setup.** The v2 watchdog auto-discovers all non-done tasks via `hermes kanban list --json` — no track file maintenance needed. It pushes status-change notifications directly to the user's chat without the orchestrator needing to be active. **One-time setup (already done on this machine):** ```bash # The script is at ~/.hermes/profiles/regent/scripts/kanban-watchdog.py # The cron job is already created as "kanban-watchdog" (every 1m, no_agent=True, deliver=origin) # Verify: hermes cron list | grep watchdog ``` **No per-batch maintenance needed.** The v2 watchdog discovers whatever is on the board. When you create Kanban tasks, the watchdog picks them up automatically on the next cycle. When you archive tasks, they drop off automatically.