---
name: design-dynamic-work-graph
description: |
  跨 Org Agent（Planner/Coder/Validator 共用）的通用方法论：如何把一个目标拆成一张可执行的
  graph_manifest（节点、依赖、每节点自包含提示词），供 work_graph_plan.py::plan_work_graph()
  的通用规划路径驱动、work_graph_orchestrate.py::run_graph() 执行。
version: 1.0.0
tags:
  - planning
  - work-graph
  - orchestration
metadata:
  origin: graphlemon-native
  related: [G（并行执行）docs/work-graph-parallel-execution-design.md, E docs/done/dynamic-work-graph-design-skill-design.md]
platforms: [linux, macos, windows]
---

# SKILL：design-dynamic-work-graph

## 适用场景
- 任务复杂到值得先规划一张图、再按图执行，而不是一次单次调用就能完成（不是所有任务都需要上图——任务很小或孤立时，直接一次调用更合适）。
- 调用方是 Planner 自身以外的 Org Agent（Coder/Validator），需要为自己的一批子任务生成 `graph_manifest`。

## 输出：一个 `graph_manifest`
```json
{
  "nodes": [
    {"node_id": "...", "depends_on": ["..."], "task_prompt": "..."}
  ],
  "edges": [
    {"from": "...", "to": "...", "edge_type": "zero_token" | "needs_judgment"}
  ]
}
```

每个节点必须自带 `task_prompt`：该节点执行时使用的完整、自包含提示词，不依赖调用方另外拼接上下文。这是跟 Planner 自己的 BRD/PRD/SDD/Benchmark 链的关键区别——Planner 的节点类型固定在一个小词表里，下游代码按 `artifact_type` 查表就能拿到提示词；Coder/Validator 的子任务没有这种固定词表，提示词必须在规划阶段由你自己写清楚。

## 规则（强制）

1. **节点边界**：一个节点 = 一次独立的、有明确输入输出契约的 Work Node 执行（一次 `claude -p` 调用）。不要把一个连贯的思考过程拆成多个人为的小节点。
2. **如实表达依赖，不要多加**：`depends_on` 只写真正存在数据流动的依赖——下游节点的 `task_prompt` 真的需要引用上游节点的产出内容，才算依赖。**不要为了图看起来更"有序"而人为串行化本来互不依赖的节点**：执行引擎（`topological_layers()`）会把没有依赖关系的节点自动分到同一层并发执行，多余的依赖会白白拖慢总执行时间，还会让"这几个节点该并行"这条信息从图里消失。
3. **`edge_type` 二选一**：
   - `zero_token`：纯聚合/规约边，下游不需要 Agent 推理就能处理上游输出（比如"把几份判断汇总计数"）。这类聚合优先用普通代码完成，不要为它专门生成一个节点。
   - `needs_judgment`：下游真的需要读懂上游内容、做出判断才能继续（比如"根据 SDD 内容写实现"）。
4. **任务小就不要上图**：如果目标本身一次 Work Node 调用就能完成，直接返回一个单节点 `graph_manifest`（或者告知调用方不需要走图规划路径），不要为了"用上这套机制"强行拆分。
5. **`node_id` 唯一、可读**：用能表达该节点做什么的短标识符（如 `test-module-a`），不要用无意义的序号。

## 分解方法

1. 先列出这批子任务里，每一对任务之间是否存在真实的数据流动（"B 的 `task_prompt` 是否真的需要 A 的产出内容"）。没有则不连边。
2. 对确实存在的依赖，判断是 `zero_token` 还是 `needs_judgment`。
3. 为每个节点写出自包含的 `task_prompt`——假设执行它的 Agent 看不到这次规划的任何上下文，只能看到这一个节点的 `task_prompt` 和它依赖节点的产出。
4. 检查是否有环（`topological_layers()` 遇到环会报错）——如果两个节点互相需要对方的产出，说明边界划错了，需要合并成一个节点或重新拆分。

## 自审清单
- [ ] 每个节点都有 `task_prompt`，且不依赖这次规划对话里才有的隐含上下文。
- [ ] 没有为了让图"看起来有序"而添加的虚假 `depends_on`。
- [ ] 没有本来可以用普通代码完成的聚合被写成了一个需要 Agent 推理的节点。
- [ ] 图里没有环。
- [ ] 如果这批任务本质上一次调用就能做完，没有为了走图机制而强行拆分。