kanban-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kanban Orchestrator — Decomposition Playbook

Kanban编排器——分解操作手册

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.

核心工作者生命周期（包括
kanban_create
扇出模式和“分解而非执行”规则）会通过
KANBAN_GUIDANCE
系统提示词块自动注入到每个Kanban流程中。当你作为专职负责任务分配的编排器角色时，本技能就是更深入的操作手册。

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.

Use one of these:

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

Hermes的配置方式多种多样。有些用户运行一个全能角色；有些用户运行小型集群（

docker-worker

、

cron-worker

）；有些用户运行自己命名的专属专家团队。没有默认的专家角色列表——编排器技能无法知晓当前机器上存在哪些角色。

在进行任务扇出之前，你必须基于实际存在的角色来开展任务分解。调度器会静默无法生成未知受指派者的任务——它不会自动修正、不会给出建议、也不会降级处理。因此，如果在仅配置了

docker-worker

的环境中，将任务卡片指派给

researcher

，该卡片会一直停留在

ready

状态。

步骤0：规划前先发现可用角色。

可以使用以下方式之一：

```
hermes profile list
```
——打印当前机器上已配置的角色列表。如果有终端工具则通过该工具运行；否则询问用户。
```
kanban_list(assignee="<some-name>")
```
——验证单个角色名称的合理性。对于未知受指派者会返回空列表（而非报错），因此该方法仅能确认你已经在考虑的名称。
直接询问用户。 当目标任务需要多个专家角色时，“你配置了哪些角色？”是不错的开场提问。

将结果缓存到你的工作记忆中，供后续对话使用。每次对话都重复询问会浪费工具调用次数。

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

何时使用看板（而非亲自完成工作）

Create Kanban tasks when any of these are true:

Multiple specialists are needed. Research + analysis + writing is three profiles.
The work should survive a crash or restart. Long-running, recurring, or important.
The user might want to interject. Human-in-the-loop at any step.
Multiple subtasks can run in parallel. Fan-out for speed.
Review / iteration is expected. A reviewer profile loops on drafter output.
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.

当满足以下任一条件时，创建Kanban任务：

需要多个专家角色。 研究+分析+撰写需要三个角色。
工作需在崩溃或重启后继续。 长期运行、周期性或重要的任务。
用户可能需要介入。 流程中任意环节需要人工参与。
多个子任务可并行运行。 通过扇出提升速度。
预期需要审核/迭代。 审核角色基于撰写者的输出进行循环处理。
审计轨迹很重要。 看板记录会永久保存在SQLite中。

如果没有满足上述任一条件——只是小型一次性推理任务——则使用

delegate_task

或直接回复用户。

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.

你的工作职责是“分配任务，而非执行任务”。以下规则可确保这一点：

不要亲自执行工作。 你的受限工具集通常甚至不包含用于实现的终端/文件/代码/网络工具。如果你发现自己“只想快速搞定这个”——请停下，为合适的专家角色创建任务。
对于任何具体任务，创建Kanban任务并指派给对应角色。 每次都要这么做。
创建卡片前拆分多流程请求。 用户的提示可能包含多个独立的工作流。先提取这些流程，然后为每个流程创建一张卡片，而非将无关工作捆绑到单个执行者卡片中。
并行运行独立流程。 如果两张卡片不需要彼此的输出，则不要设置关联，以便调度器可以将它们扇出。仅在存在真实数据依赖时才设置关联。
永远不要将依赖任务创建为独立的就绪卡片。 如果一张卡片必须等待另一张卡片完成，请在初始的
```
kanban_create
```
调用中传入
```
parents=[...]
```
。不要先创建卡片再后续关联，也不要依赖卡片内容中的“等待T1完成”这类描述。
如果没有匹配的专家角色，询问用户应创建哪个角色或使用哪个现有角色。 不要凭空发明角色名称；调度器会静默丢弃未知受指派者的任务。
分解、分配、总结——这就是全部工作。

Decomposition playbook

分解操作手册

Step 1 — Understand the goal

步骤1 — 理解目标

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

如果目标不明确，请提出澄清问题。提问的成本很低；错误地生成任务集群的代价很高。

Step 2 — Sketch the task graph

步骤2 — 绘制任务图

Before creating anything, draft the graph out loud (in your response to the user). Treat every concrete workstream as a candidate card:

Extract the lanes from the request.
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.
Decide whether each lane is independent or gated by another lane.
Create independent lanes as parallel cards with no parent links.
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.

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.

在创建任何任务之前，向用户口头（在回复中）草拟任务图。将每个具体工作流视为候选卡片：

从请求中提取各个流程。
将每个流程映射到步骤0中发现的角色之一。如果某个流程不匹配任何现有角色，请询问用户应使用或创建哪个角色。
判断每个流程是独立的还是需要依赖其他流程。
将独立流程创建为无父级关联的并行卡片。
将综合/审核/集成卡片创建为带有父级关联的卡片，关联其依赖的流程。如果子卡片的父级未完成，它会处于
```
todo
```
状态；仅当所有父级都完成后，调度器才会将其提升为
```
ready
```
状态。

以下是需要进行扇出的提示示例（使用占位符角色名称——请替换为用户环境中实际存在的角色）：

“构建一个应用” → 一张卡片指派给面向设计的角色负责产品/UI方向，一到两张卡片指派给工程角色负责实现，如果用户有审核角色，则再加一张后续的集成/审核卡片。
“修复阻塞问题并检查模型变体” → 一张实现卡片用于修复阻塞问题，加上一张发现/研究卡片用于配置/源验证。最终的审核卡片可以依赖这两张卡片。
“研究文档并实现” → 文档研究卡片可与代码库发现卡片并行运行；仅当实现确实需要这些研究结果时，才让实现任务等待。
“分析此截图并找到相关代码” → 一张卡片指派给具备视觉能力的角色进行视觉分析，另一张卡片用于搜索代码库。

“同时”、“最终”或“和”这类词并不自动意味着存在依赖关系。它们通常表示“确保在反馈前完成这些内容”。仅当一张卡片必须等待另一张卡片的输出才能启动时，才关联任务。

在创建卡片前向用户展示任务图。让他们进行修正——包括为每个流程指定实际的角色名称。

Step 3 — Create tasks and link

步骤3 — 创建任务并关联

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.

使用步骤0中的角色名称。以下示例使用占位符

<profile-A>

、

<profile-B>

、

<profile-C>

——请替换为用户实际拥有的角色。

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=[...]

会控制状态提升——子卡片会一直处于

todo

状态，直到所有父级卡片都完成，然后自动提升为

ready

状态。无需手动协调；调度器和依赖引擎会处理这一切。

如果任务图存在依赖关系，请先创建父级卡片，获取返回的ID，并在创建子卡片的

kanban_create

调用中将这些ID包含在子卡片的

parents

列表中。避免并行创建所有卡片再后续关联；这会导致调度器在子卡片的输入存在之前就认领该卡片的窗口。

Step 4 — Complete your own task

步骤4 — 完成你自己的任务

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

如果你本身是作为任务被生成的（例如，规划角色被指派了

T0: "investigate Postgres migration"

），请标记任务完成并总结你创建的内容：

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 — Report back to the user

步骤5 — 向用户反馈

Tell them what you created in plain prose, naming the actual profiles you used:

I've queued 4 tasks:
T1 (
<profile-A>
): cost comparison
T2 (
<profile-A>
): performance comparison, in parallel with T1
T3 (
<profile-B>
): synthesizes T1 + T2 into a recommendation
T4 (
<profile-C>
): 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.

用通俗易懂的语言告诉他们你创建的内容，指明你使用的实际角色：

我已创建4个任务：
T1 (
<profile-A>
): 成本对比
T2 (
<profile-A>
): 性能对比，与T1并行执行
T3 (
<profile-B>
): 综合T1和T2的结果生成建议
T4 (
<profile-C>
): 将T3的建议转化为给CTO的备忘录
调度器现在会处理T1和T2。T3会在两者都完成后启动。T4完成时你会收到通知。可以使用仪表盘或
hermes kanban tail <id>
来跟踪进度。

Common patterns

常见模式

Fan-out + fan-in (research → synthesize): N research-style cards with no parents, one synthesis card with all of them as parents.

Parallel implementation + validation: one implementer card makes the change while one explorer/researcher card verifies config, docs, or source mapping. A reviewer card can depend on both. Do not make the implementer own unrelated verification just because the user mentioned both in one sentence.

Pipeline with gates:

planner → implementer → reviewer

. Each stage's

parents=[previous_task]

. Reviewer blocks or completes; if reviewer blocks, the operator unblocks with feedback and respawns.

Same-profile queue: N tasks, all assigned to the same profile, no dependencies between them. Dispatcher serializes — that profile processes them in priority order, accumulating experience in its 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.

扇出+扇入（研究→综合）： N个无父级的研究类卡片，一个将所有研究卡片作为父级的综合卡片。

并行实现+验证： 一张执行者卡片进行变更，同时一张探索者/研究者卡片验证配置、文档或源映射。审核卡片可以依赖这两张卡片。不要因为用户在一句话中提到了两者，就让执行者负责无关的验证工作。

带闸门的流水线：

规划者→执行者→审核者

。每个阶段的

parents=[previous_task]

。审核者可以阻止或完成任务；如果审核者阻止，操作者会通过反馈解除阻止并重新生成任务。

同角色队列： N个任务，全部指派给同一个角色，彼此无依赖。调度器会序列化处理——该角色会按优先级顺序处理任务，并在自身记忆中积累经验。

人工介入流程： 任何任务都可以调用

kanban_block()

来等待输入。用户执行

/unblock

后调度器会重新生成任务。评论线程会保留完整上下文。

Pitfalls

常见陷阱

Inventing profile names that don't exist. The dispatcher silently fails to spawn unknown assignees — the card just sits in

ready

forever. Always assign to a profile from your Step 0 discovery; ask the user if you're unsure.

Bundling independent lanes into one card. If the user asks for two independent outcomes, create two cards. Example: "fix blockers and check model variants" is not one fixer task; create a fixer/engineer card for the fixes and an explorer/researcher card for the variant check, then optionally gate review on both.

Over-linking because of wording. "Finally check X" may still be parallel with implementation if X is static config, docs, or source discovery. Link it after implementation only when the check depends on the implementation result.

Forgetting dependency links. If the task graph says

research -> implement -> review

, do not create all tasks as independent ready cards. Use parent links so implement/review cannot run before their inputs exist.

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.

凭空发明不存在的角色名称。 调度器会静默无法生成未知受指派者的任务——卡片会一直停留在

ready

状态。始终指派给步骤0中发现的角色；如有疑问请询问用户。

将独立流程捆绑到一张卡片中。 如果用户要求两个独立的结果，请创建两张卡片。示例：“修复阻塞问题并检查模型变体”不是一个修复者任务；创建一张修复者/工程师卡片用于修复问题，一张探索者/研究者卡片用于变体检查，然后可选地让审核任务依赖这两张卡片。

因措辞过度关联任务。 “最终检查X”如果X是静态配置、文档或源发现，仍可与实现任务并行执行。仅当检查依赖于实现结果时，才将其关联到实现任务之后。

忘记依赖关联。 如果任务图是

研究→实现→审核

，不要将所有任务创建为独立的就绪卡片。使用父级关联，确保实现/审核任务在输入存在之前无法运行。

重新指派vs创建新任务。 如果审核者阻止任务并提示“需要修改”，请创建一个关联到审核者任务的新任务——不要重新运行同一个任务。新任务指派给原执行者角色。

关联的参数顺序。

kanban_link(parent_id=..., child_id=...)

——父级在前。顺序错误会导致错误的任务降级为

todo

状态。

如果任务图的结构依赖于中间结果，不要预先创建整个图。 如果T3的结构依赖于T1和T2的发现，让T3作为“综合发现结果”的任务存在，其第一步是读取父级的交付内容并规划后续工作。编排器可以生成其他编排器。

租户继承。 如果你的环境中设置了

HERMES_TENANT

，请在每次

kanban_create

调用中传入

tenant=os.environ.get("HERMES_TENANT")

，以便子任务保持在同一个命名空间中。

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:

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.
Reassign (or
```
hermes kanban reassign <task_id> <new-profile> --reclaim
```
) — switch the task to a different profile (one that exists on this setup) and let the dispatcher pick it up with a fresh worker.
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.

当工作者角色持续崩溃、产生幻觉或因自身错误被阻止（通常是：模型错误、缺少技能、凭证失效）时，Kanban仪表盘会用⚠标记该任务，并在抽屉中打开恢复部分。主要有三种操作：

回收（或
```
hermes kanban reclaim <task_id>
```
）——立即终止运行中的工作者并将任务重置为
```
ready
```
状态。现有认领的TTL约为15分钟；这是快速解决的途径。
重新指派（或
```
hermes kanban reassign <task_id> <new-profile> --reclaim
```
）——将任务切换到另一个角色（当前环境中存在的角色），让调度器用新的工作者处理该任务。
修改角色模型——仪表盘会打印
```
hermes -p <profile> model
```
的复制粘贴提示，因为角色配置存储在磁盘上；在终端中编辑配置，然后回收任务以使用新模型重试。

当工作者的

kanban_complete(created_cards=[...])

声明包含不存在的卡片ID或并非由该工作者角色创建的卡片ID时（网关会阻止完成），或者自由格式的摘要引用无法解析的

t_<hex>

ID时（建议性文本扫描，非阻塞），会出现幻觉警告。这两种情况都会生成审计事件，即使执行了恢复操作也会保留——轨迹会留存用于调试。",