Back to Details

graph

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

graph — Task/PRD to Parallel Execution Graph

graph — 任务/PRD到并行执行图

Turn a task (or PRD / SPEC / issue set) into a directed acyclic graph of work units, layer it into supersteps (waves), and implement each wave's independent nodes concurrently using subagents. Each node runs the full 
/goal → /review-it → /ship-it
pipeline inside its own git worktree, so parallel nodes never clobber each other's working tree. Between waves, a fan-in barrier merges results and re-plans the next wave.
This is the parallel sibling of 
/loop-it
. 
/loop-it
is strictly sequential (one worktree, one issue at a time). 
/graph
fans out every independent node in a wave at once.
将任务（或PRD/SPEC/议题集）转换为工作单元的有向无环图（DAG），将其分层为superstep（阶段），并通过子Agent（subagents）并发实现每个阶段中的独立节点。每个节点会在专属的git worktree内完整执行
/goal → /review-it → /ship-it
流水线，因此并行节点绝不会互相干扰工作目录。各阶段之间设有fan-in屏障，用于合并结果并规划下一阶段的任务。
本技能是
/loop-it
的并行版本。
/loop-it
严格按顺序执行（单一工作目录，每次处理一个议题），而
/graph
会同时分发当前阶段中的所有独立节点。

Mental Model (borrowed from LangGraph / graph engineering)

心智模型（借鉴自LangGraph / 图工程）

ConceptHere
NodeOne implementable unit of work (an issue / subtask)
EdgeA dependency: 
B depends on A
→ edge 
A → B
Superstep / waveA set of nodes whose deps are all satisfied — run concurrently
Fan-outDispatch one subagent per node in the current wave
Fan-in (barrier)Wait for all nodes in the wave before starting the next
State channel
.graph_state
— shared checkpoint, rewritten between waves (resume source)
Live tracker
graph.html
— Claude-style light-theme dashboard, re-rendered from 
.graph_state
at every checkpoint
Dynamic re-planAfter a wave, revise the graph if new work/deps emerged
Core principle: Independent nodes in the same wave have no shared state and no ordering dependency, so they can run in true parallel. Dependencies define the only ordering. Everything else runs at once.
概念对应含义
Node（节点）可实现的独立工作单元（一个议题/子任务）
Edge（边）依赖关系：
B依赖于A
→ 边
A → B
Superstep / wave（超级步骤/阶段）所有依赖均已满足的节点集合——可并发执行
Fan-out（扇出）为当前阶段的每个节点分配一个子Agent
Fan-in (barrier)（扇入/屏障）等待当前阶段所有节点完成后再启动下一阶段
State channel（状态通道）
.graph_state
—— 共享检查点，各阶段之间会重写（恢复执行的数据源）
Live tracker（实时追踪器）
graph.html
—— Claude风格的浅色主题仪表盘，每次检查点都会从
.graph_state
重新渲染
Dynamic re-plan（动态重规划）完成一个阶段后，若出现新的工作/依赖则修订图结构
核心原则： 同一阶段中的独立节点无共享状态且无顺序依赖，因此可真正并行执行。依赖关系是唯一的顺序约束，其余所有任务均可同时运行。

Overview

流程概览

Input (task / PRD / SPEC / issues)
        │
        ▼
1. Decompose into nodes  ─────────►  nodes = {id, title, deps, criteria, scope}
        │
        ▼
2. Build DAG + validate  ─────────►  detect cycles, orphan deps
        │
        ▼
3. Topological layering  ─────────►  waves = [[n1,n2,n3], [n4,n5], [n6]]
        │
        ▼
4. Render graph + confirm with user
        │
        ▼  (write .graph_state + graph.html — open graph.html to watch live)
┌──────────── per wave (superstep) ────────────┐
│                                               │
│  FAN-OUT: 1 subagent per node (parallel)      │
│    each subagent, in its own git worktree:    │
│      /goal (inline implement) → /review-it    │
│                              → /ship-it        │
│                                               │
│  FAN-IN barrier: wait for ALL nodes           │
│    integrate, update .graph_state             │
│    re-render graph.html                        │
│    re-plan next wave if graph changed         │
│                                               │
└───────────────────────────────────────────────┘
        │
        ▼
All waves done → final summary
输入（任务 / PRD / SPEC / 议题）
        │
        ▼
1. 分解为节点  ─────────►  nodes = {id, title, deps, criteria, scope}
        │
        ▼
2. 构建DAG并验证  ─────────►  检测循环依赖、孤立依赖
        │
        ▼
3. 拓扑分层为阶段  ─────────►  waves = [[n1,n2,n3], [n4,n5], [n6]]
        │
        ▼
4. 渲染图并与用户确认
        │
        ▼ （写入.graph_state + graph.html —— 打开graph.html实时监控）
┌──────────── 按阶段执行（superstep） ────────────┐
│                                               │
│  扇出：为每个节点分配一个子Agent（并行）      │
│    每个子Agent在专属git worktree中执行：    │
│      /goal（内联实现） → /review-it    │
│                              → /ship-it        │
│                                               │
│  扇入屏障：等待所有节点完成           │
│    集成结果，更新.graph_state             │
│    重新渲染graph.html                        │
│    若图结构变更则重规划下一阶段         │
│                                               │
└───────────────────────────────────────────────┘
        │
        ▼
所有阶段完成 → 最终总结

Step 1: Locate & Decompose Input

步骤1：定位并分解输入

Accept any of: a free-form task description, a PRD/SPEC file, or an existing issue set (GitHub / local 
.md
).
  • PRD/SPEC → reuse 
    /to-issues
    decomposition rules (one node per User Story; split large, merge tiny).
  • Existing issues → each issue is a node; parse dependencies from issue bodies (
    Depends on: #3
    , 
    Dependencies: #3, #5
    ).
  • Free-form task → break into the smallest independently-shippable units yourself.
Each node MUST have:
Node #N
  title:      short imperative title
  deps:       [list of node ids] or []
  criteria:   acceptance criteria (checklist) — how the subagent knows it's done
  type:       backend | frontend | fullstack | ui | infra | docs
  scope_hint: which files/dirs this node is expected to touch (for conflict analysis)
scope_hint
matters: two nodes with no dependency edge but overlapping file scope are not truly independent — see Step 3.
接受以下任意输入形式：自由格式的任务描述、PRD/SPEC文件，或现有议题集（GitHub / 本地
.md
文件）。
  • PRD/SPEC → 复用
    /to-issues
    的分解规则（每个用户故事对应一个节点；拆分大型任务，合并微小任务）。
  • 现有议题 → 每个议题对应一个节点；从议题内容中解析依赖关系（如
    Depends on: #3
    、
    Dependencies: #3, #5
    ）。
  • 自由格式任务 → 自行拆分为最小的可独立交付单元。
每个节点必须包含：
Node #N
  title:      简短的祈使句标题
  deps:       [节点ID列表] 或 []
  criteria:   验收标准（检查清单）—— 子Agent判断任务完成的依据
  type:       backend | frontend | fullstack | ui | infra | docs
  scope_hint: 该节点预期涉及的文件/目录（用于冲突分析）
scope_hint
至关重要：两个无依赖边但文件范围重叠的节点并非真正独立——详见步骤3。

Step 2: Build the DAG & Validate

步骤2：构建DAG并验证

Construct edges from 
deps
. Then validate:
CheckAction on failure
Cycle (
A → B → A
)		Print 
⚠️ 循环依赖: #A ↔ #B
. Break by node id order, warn user, ask to confirm or fix.
Dangling dep (
#7 depends on #99
, no such node)		Print warning, drop the phantom edge.
Scope collision (two dep-free nodes edit same files)Add a soft edge to serialize them (lower id first), OR flag for user. Never let two parallel worktrees fight over the same files.
Hot-file exception: A shared wiring file that nearly every node must touch (e.g. 
router.go
, 
main.go
, 
mod.rs
, a DI container, an 
__init__
re-export) does NOT count as a scope collision — treating it as one would serialize the entire graph into a chain. For such files, assume append-only edits merge cleanly, and prefer one of: (a) designate a single node that owns wiring and have others expose a registration hook, or (b) do a tiny follow-up "wire everything" node in the last wave. Reserve the collision rule for nodes that edit the same logic in the same file (e.g. two handlers rewriting the same function).
根据
deps
构建边，然后进行验证：
检查项失败时的操作
循环依赖（
A → B → A
）		打印
⚠️ 循环依赖: #A ↔ #B
。按节点ID顺序打破循环，向用户发出警告并请求确认或修复。
悬空依赖（
#7依赖于#99
，但不存在该节点）		打印警告，移除无效边。
范围冲突（两个无依赖节点编辑同一文件）添加软边使其按顺序执行（ID较小的优先），或标记给用户处理。绝不能让两个并行工作目录争夺同一文件。
热点文件例外： 几乎每个节点都需要修改的共享配置文件（如
router.go
、
main.go
、
mod.rs
、DI容器、
__init__
重导出文件）不算范围冲突——若将其视为冲突，会将整个图串行化为链式执行。对于此类文件，假设追加式编辑可干净合并，优先选择以下方式之一：(a) 指定单个节点负责配置，其他节点暴露注册钩子；(b) 在最后一个阶段添加一个小型的「整合所有配置」节点。仅当节点编辑同一文件中的相同逻辑（如两个处理程序重写同一函数）时，才触发冲突规则。

Step 3: Topological Layering into Waves

步骤3：拓扑分层为阶段

Compute waves via Kahn's algorithm:
  1. Wave 0 = all nodes with 
    deps == []
    and no scope collision among themselves.
  2. Remove wave-0 nodes; Wave 1 = nodes whose deps are now all satisfied.
  3. Repeat until all nodes placed.
  4. Within a wave, if two nodes edit the same logic in the same file (real collision, per the hot-file exception in Step 2), push the higher-id one to the next wave. Bare wiring-file overlap does not trigger this.
ID conventions (used consistently): lower id wins — cycles break by lowest id first (Step 2), and scope collisions serialize with the lower id first (higher id deferred to the next wave).
Print the layered plan:
📊 Graph: 6 nodes, 3 waves

Wave 0 (parallel ×3):  #1 db schema   #2 config loader   #3 logging util
Wave 1 (parallel ×2):  #4 API handler (deps #1)   #5 CLI flags (deps #2)
Wave 2 (parallel ×1):  #6 integration (deps #4,#5)

Max parallelism: 3 subagents in Wave 0.
Also emit a Mermaid diagram for the user:
```mermaid
graph LR
  n1[#1 db schema] --> n4[#4 API handler]
  n2[#2 config loader] --> n5[#5 CLI flags]
  n3[#3 logging util]
  n4 --> n6[#6 integration]
  n5 --> n6
```
Wait for user confirmation before dispatching any subagent. Let them adjust nodes, deps, or the max-parallelism cap.
通过Kahn算法计算阶段：
  1. 阶段0 = 所有
    deps == []
    且内部无范围冲突的节点。
  2. 移除阶段0的节点；阶段1 = 所有依赖已全部满足的节点。
  3. 重复上述步骤直到所有节点分配完毕。
  4. 在同一阶段内，若两个节点编辑同一文件中的相同逻辑（符合步骤2中的热点文件例外规则），则将ID较大的节点推迟到下一阶段。仅文件重叠不触发此规则。
ID约定（统一遵循）： ID越小优先级越高——循环依赖按最小ID优先打破（步骤2），范围冲突按最小ID优先串行执行（ID较大的推迟到下一阶段）。
打印分层计划：
📊 任务图：6个节点，3个阶段

阶段0（并行×3）：  #1 数据库架构   #2 配置加载器   #3 日志工具
阶段1（并行×2）：  #4 API处理器（依赖#1）   #5 CLI参数（依赖#2）
阶段2（并行×1）：  #6 集成测试（依赖#4,#5）

最大并行度：阶段0使用3个子Agent。
同时为用户生成Mermaid图表：
```mermaid
graph LR
  n1[#1 数据库架构] --> n4[#4 API处理器]
  n2[#2 配置加载器] --> n5[#5 CLI参数]
  n3[#3 日志工具]
  n4 --> n6[#6 集成测试]
  n5 --> n6
```
在分发任何子Agent前等待用户确认。允许用户调整节点、依赖关系或最大并行度上限。

Step 4: Pre-flight Checks

步骤4：预检查

Before the first wave (same spirit as 
/loop-it
):
bash
git rev-parse --is-inside-work-tree   # in a repo?
git status --porcelain                # clean tree? (dirty → stash/abort)
git branch --show-current             # on main/master?
git ls-remote --heads origin          # remote reachable?
gh auth status                        # if shipping to GitHub
Any hard failure → print the error and stop. Confirm a max concurrency cap with the user (default 3–4 parallel subagents; more risks rate limits and review noise).
Then initialize the state channel + live tracker (do this once, right after the plan is confirmed and before the first fan-out):
bash
undefined
在第一阶段执行前（与
/loop-it
遵循相同原则）：
bash
git rev-parse --is-inside-work-tree   # 是否在仓库内？
git status --porcelain                # 工作目录是否干净？（脏目录 → 暂存/终止）
git branch --show-current             # 是否在main/master分支？
git ls-remote --heads origin          # 远程仓库是否可达？
gh auth status                        # 若要推送至GitHub需验证
任何严重失败 → 打印错误并停止。与用户确认最大并发上限（默认3–4个并行子Agent；过多会触发速率限制并增加评审噪音）。
然后初始化状态通道 + 实时追踪器（计划确认后、首次扇出前执行一次）：
bash
undefined

1. Write the initial checkpoint (all nodes pending, current_wave 0).

1. 写入初始检查点（所有节点待处理，当前阶段为0）。

cat > .graph_state <<'JSON' { "version": 1, "task": "...", "repo": "owner/repo", "waves": [[1,2,3],[4,5],[6]], "current_wave": 0, "nodes": { "1": {"title":"...","deps":[],"status":"pending","wave":0}, ... } } JSON
cat > .graph_state <<'JSON' { "version": 1, "task": "...", "repo": "owner/repo", "waves": [[1,2,3],[4,5],[6]], "current_wave": 0, "nodes": { "1": {"title":"...","deps":[],"status":"pending","wave":0}, ... } } JSON

2. Keep it out of git.

2. 将其排除在git追踪外。

grep -qxF '.graph_state' .gitignore || printf '.graph_state\ngraph.html\n' >> .gitignore
grep -qxF '.graph_state' .gitignore || printf '.graph_state\ngraph.html\n' >> .gitignore

3. Render the Claude-style light-theme dashboard.

3. 渲染Claude风格的浅色主题仪表盘。

python3 skills/graph/scripts/render_graph_html.py .graph_state graph.html

Tell the user: **open `graph.html` in a browser** — it auto-refreshes every 5s, so it tracks execution live (waves, node statuses, progress bar, and a Mermaid DAG colored by status). Re-run the render command at every checkpoint (see Step 5b) to push updates.

---
python3 skills/graph/scripts/render_graph_html.py .graph_state graph.html

告知用户：**在浏览器中打开`graph.html`**——它会每5秒自动刷新，实时追踪执行状态（阶段、节点状态、进度条、按状态着色的Mermaid DAG）。每次检查点时重新运行渲染命令（见步骤5b）以推送更新。

---

Step 5: Execute Wave by Wave (fan-out → fan-in)

步骤5：按阶段执行（扇出 → 扇入）

For each wave, in order:
按顺序处理每个阶段：

5a. FAN-OUT — one subagent per node, in parallel

5a. 扇出 —— 为每个节点分配一个子Agent，并行执行

Dispatch all nodes of the wave in a single response (multiple Agent/subagent calls in one message = concurrent). Each subagent works in its own git worktree so parallel file edits never collide:
bash
undefined
在单个响应中分发当前阶段的所有节点（一条消息中包含多个Agent/子Agent调用 = 并发执行）。每个子Agent在专属的git worktree中工作，因此并行文件编辑绝不会冲突：
bash
undefined

The orchestrator creates a worktree per node BEFORE dispatching:

编排器在分发前为每个节点创建工作目录：

git worktree add -b feat/node-{N}-{slug} ../.graph-worktrees/node-{N} main

Each subagent receives a **self-contained** prompt (it does NOT inherit orchestrator context):

```markdown
You are implementing ONE node of a task graph, working in an ISOLATED git worktree.

Worktree:  ../.graph-worktrees/node-{N}   (already created on branch feat/node-{N}-{slug})
Node #{N}: {title}
Type:      {type}
Scope:     {scope_hint}  — stay within these files; do not touch other nodes' scope

Acceptance criteria (all must pass):
- [ ] {criterion 1}
- [ ] {criterion 2}

Context (deps already merged into main, pull first):
{summaries of dependency nodes' outputs, or the referenced PRD/SPEC excerpt}

Your pipeline (run all three, in order):
1. IMPLEMENT (inline /goal): read the node + any referenced PRD/SPEC, read adjacent
   code, implement to satisfy EVERY acceptance criterion, run build + tests + lint
   (e.g. go build ./... && go vet ./... && go test ./...). Iterate until all green.
2. REVIEW (/review-it): run code review on your changes, apply accepted findings,
   re-run focused tests, repeat until review is clean (max 2 rounds).
3. SHIP (/ship-it): commit (message references the node/issue), push branch,
   create PR, merge, close the issue.

Constraints:
- Work ONLY inside your worktree. Do NOT edit files outside {scope_hint}.
- Do NOT try to call `goal` via the Skill tool (it's a UI command, not a skill) —
  "implement" means you write the code yourself. /review-it and /ship-it ARE skills.
- If you cannot satisfy a criterion, STOP and report what's blocking — don't fake it.

Return: node id, PASS/FAIL, PR/commit refs, files changed, and — if you discovered new required work or a dependency the graph didn't capture — a `NEW_WORK:` line describing it (title + which nodes it blocks). Emit `NEW_WORK: none` if there's nothing.
Why worktrees, not branches alone: 
/goal
mutates the working tree. Two subagents editing the same checkout would corrupt each other. A worktree per node gives each its own filesystem checkout on its own branch — that's what makes the wave genuinely parallel and safe.
git worktree add -b feat/node-{N}-{slug} ../.graph-worktrees/node-{N} main

每个子Agent会收到**独立完整**的提示（不继承编排器上下文）：

```markdown
你正在执行任务图中的一个节点，工作在独立的git worktree中。

工作目录：  ../.graph-worktrees/node-{N}  （已在分支feat/node-{N}-{slug}上创建）
节点#{N}: {title}
类型:      {type}
范围:     {scope_hint}  —— 仅在此范围内工作；不要触碰其他节点的范围

验收标准（必须全部满足）：
- [ ] {criterion 1}
- [ ] {criterion 2}

上下文（依赖节点的输出已合并至main分支，请先拉取）：
{依赖节点输出的摘要，或引用的PRD/SPEC片段}

你的执行流水线（按顺序运行所有三个步骤）：
1. 实现（内联/goal）：读取节点内容 + 任何引用的PRD/SPEC，阅读相关代码，实现功能以满足所有验收标准，运行构建 + 测试 + 代码检查
   （例如：go build ./... && go vet ./... && go test ./...）。迭代直到全部通过。
2. 评审（/review-it）：对你的变更进行代码评审，应用已接受的评审意见，重新运行针对性测试，重复直到评审通过（最多2轮）。
3. 交付（/ship-it）：提交（提交信息引用节点/议题），推送分支，创建PR，合并，关闭议题。

约束：
- 仅在你的工作目录内工作。不要编辑{scope_hint}之外的文件。
- 不要尝试通过Skill工具调用`goal`（它是UI命令，不是Skill）——
  「实现」意味着你需要自行编写代码。/review-it和/ship-it是有效的Skill。
- 若无法满足某个验收标准，请停止并报告阻塞原因——不要伪造结果。

返回内容：节点ID、PASS/FAIL、PR/提交引用、变更的文件，以及——如果你发现了图中未包含的新工作或依赖——`NEW_WORK:`行描述相关内容（标题 + 它阻塞的节点）。若无新内容则返回`NEW_WORK: none`。
为何使用工作目录而非仅分支： 
/goal
会修改工作目录。两个子Agent编辑同一个检出目录会互相破坏。为每个节点分配独立工作目录，使其拥有专属的文件系统检出和分支——这是阶段真正并行且安全的核心保障。

5b. FAN-IN — barrier, integrate, re-plan

5b. 扇入 —— 屏障、集成、重规划

Wait for every subagent in the wave to return (BSP barrier — the next wave cannot start until this one commits). Then:
  1. Read each subagent's summary. Mark node 
    shipped
    or 
    failed
    .
  2. git checkout main && git pull
    — dependency outputs are now on main for the next wave.
  3. Remove finished worktrees: 
    git worktree remove ../.graph-worktrees/node-{N}
    (keep failed ones for investigation).
  4. Write checkpoint to 
    .graph_state
    , then re-render the tracker: 
    python3 skills/graph/scripts/render_graph_html.py .graph_state graph.html
    (the open 
    graph.html
    picks it up on its next auto-refresh).
  5. Dynamic re-plan (LangGraph-style conditional edge): scan each subagent's 
    NEW_WORK:
    line. If any is not 
    none
    , add the new node(s)/edge(s) and re-layer the remaining nodes before starting the next wave. Show the user the delta.
  6. If any node in the wave failed, mark all nodes that depend on it as 
    blocked
    and skip them (their inputs aren't ready).
Proceed to the next wave.
等待当前阶段所有子Agent返回（BSP屏障——下一阶段必须在当前阶段所有节点提交后才能启动）。然后：
  1. 读取每个子Agent的摘要。标记节点为
    shipped
    （已交付）或
    failed
    （失败）。
  2. git checkout main && git pull
    —— 依赖节点的输出现已合并至main分支，供下一阶段使用。
  3. 删除已完成的工作目录：
    git worktree remove ../.graph-worktrees/node-{N}
    （保留失败的工作目录用于排查）。
  4. 将检查点写入
    .graph_state
    ，然后重新渲染追踪器： 
    python3 skills/graph/scripts/render_graph_html.py .graph_state graph.html
    （打开的
    graph.html
    会在下次自动刷新时获取更新）。
  5. 动态重规划（LangGraph风格的条件边）：扫描每个子Agent的
    NEW_WORK:
    行。若存在非
    none
    的内容，则添加新节点/边，并在启动下一阶段前重新分层剩余节点。向用户展示变更内容。
  6. 若当前阶段中有任何节点失败，则标记所有依赖它的节点为
    blocked
    （阻塞）并跳过（它们的输入未准备就绪）。
进入下一阶段。

State File: 
.graph_state
(+ live tracker 
graph.html
)

状态文件：
.graph_state
（+ 实时追踪器
graph.html
）

.graph_state
lives at the repo root and must be in 
.gitignore
. It's the single source of truth: checkpoint it after every wave so a crash resumes at the wave boundary, and re-render 
graph.html
from it so the browser dashboard stays live. 
graph.html
is a derived view — never hand-edit it; regenerate it from 
.graph_state
.
json
{
  "version": 1,
  "updated_at": "2026-07-21T10:30:00Z",
  "task": "Add user auth",
  "repo": "owner/repo",
  "waves": [[1, 2, 3], [4, 5], [6]],
  "current_wave": 1,
  "nodes": {
    "1": { "title": "db schema", "deps": [], "status": "shipped", "branch": "feat/node-1-db-schema", "pr": 43, "wave": 0 },
    "2": { "title": "config loader", "deps": [], "status": "shipped", "wave": 0 },
    "3": { "title": "logging util", "deps": [], "status": "failed", "wave": 0, "error": "test TestLog failed", "attempts": 2 },
    "4": { "title": "API handler", "deps": [1], "status": "in_progress", "wave": 1 },
    "6": { "title": "integration", "deps": [4, 5], "status": "blocked", "wave": 2, "reason": "depends on #3 (failed)" }
  }
}
Status values: 
pending | in_progress | shipped | failed | blocked | skipped
. Each node carries 
title
+ 
deps
so 
graph.html
can draw the DAG and cards straight from the checkpoint.
Render the tracker any time with:
bash
python3 skills/graph/scripts/render_graph_html.py .graph_state graph.html
On resume: read 
.graph_state
, skip 
shipped
, ask about 
failed
(retry/skip), re-derive remaining waves, and re-render 
graph.html
.
.graph_state
位于仓库根目录，必须加入
.gitignore
。它是唯一的事实来源：每个阶段后创建检查点，以便崩溃后从阶段边界恢复执行；从它重新渲染
graph.html
，使浏览器仪表盘保持实时更新。
graph.html
是派生视图——切勿手动编辑；从
.graph_state
重新生成。
json
{
  "version": 1,
  "updated_at": "2026-07-21T10:30:00Z",
  "task": "添加用户认证",
  "repo": "owner/repo",
  "waves": [[1, 2, 3], [4, 5], [6]],
  "current_wave": 1,
  "nodes": {
    "1": { "title": "数据库架构", "deps": [], "status": "shipped", "branch": "feat/node-1-db-schema", "pr": 43, "wave": 0 },
    "2": { "title": "配置加载器", "deps": [], "status": "shipped", "wave": 0 },
    "3": { "title": "日志工具", "deps": [], "status": "failed", "wave": 0, "error": "测试TestLog失败", "attempts": 2 },
    "4": { "title": "API处理器", "deps": [1], "status": "in_progress", "wave": 1 },
    "6": { "title": "集成测试", "deps": [4, 5], "status": "blocked", "wave": 2, "reason": "依赖#3（失败）" }
  }
}
状态值：
pending | in_progress | shipped | failed | blocked | skipped
。每个节点包含
title
+ 
deps
，因此
graph.html
可直接从检查点绘制DAG和状态卡片。
随时使用以下命令渲染追踪器：
bash
python3 skills/graph/scripts/render_graph_html.py .graph_state graph.html
恢复执行时：读取
.graph_state
，跳过
shipped
节点，询问用户如何处理
failed
节点（重试/跳过），重新推导剩余阶段，并重新渲染
graph.html
。

Safety Guards

安全防护

  • Worktree isolation is mandatory — never run two parallel 
    /goal
    sessions in the same checkout.
  • Fan-in barrier is mandatory — never start wave N+1 before every node in wave N returns and merges.
  • Scope collisions serialize — dep-free nodes touching the same files go in different waves.
  • Never skip /review-it before 
    /ship-it
    .
  • Cap concurrency — default 3–4; more invites rate limits and merge contention.
  • Never force-push to main. Each node ships via its own branch/PR.
  • Failed node blocks its dependents — don't ship on top of unmet inputs.
  • Max retries per node — reuse 
    /loop-it
    's error classes; don't loop forever.
  • Confirm the plan before the first fan-out.
  • 工作目录隔离是强制要求——绝不在同一检出目录中运行两个并行的
    /goal
    会话。
  • 扇入屏障是强制要求——绝不在当前阶段所有节点返回并合并前启动下一阶段。
  • 范围冲突需串行执行——无依赖但触碰同一文件的节点需分属不同阶段。
  • /ship-it
    前绝不能跳过
    /review-it
    。
  • 限制并发数——默认3–4；过多会触发速率限制并增加合并冲突。
  • 绝不能强制推送至main分支。每个节点通过专属分支/PR交付。
  • 失败节点会阻塞其依赖节点——不要基于未满足的输入交付。
  • 每个节点的最大重试次数——复用
    /loop-it
    的错误分类；不要无限循环。
  • 首次扇出前确认计划。

Common Mistakes

常见错误

MistakeFix
Dispatching subagents in separate responsesOne response, multiple calls = parallel. Separate = sequential.
No worktree → parallel edits corrupt the treeOne 
git worktree
per node.
Two "independent" nodes edit the same fileAdd a soft edge; put them in different waves.
Starting the next wave before all nodes mergeEnforce the fan-in barrier.
Over-decomposing into 20 trivial nodesMerge tiny units; a node should be a meaningful shippable unit.
Ignoring a failed node's dependentsMark them 
blocked
, skip them.
错误修复方案
分开发包子Agent单个响应包含多个调用 = 并行。分开响应 = 串行。
未使用工作目录 → 并行编辑破坏工作目录为每个节点创建一个
git worktree
。
两个「独立」节点编辑同一文件添加软边；将它们分属不同阶段。
未等所有节点合并就启动下一阶段强制执行扇入屏障。
过度分解为20个微小节点合并微小单元；节点应是有意义的可交付单元。
忽略失败节点的依赖节点将它们标记为
blocked
并跳过。

Relationship to Other Skills

与其他Skill的关系

/prd → /prd-to-spec → /to-issues ─┬─► /loop-it   (sequential: one node at a time)
                                   └─► /graph     (parallel: whole wave at once)
                                          │
                     each node: inline /goal → /review-it → /ship-it (in its own worktree)
  • /to-issues
     — decomposition rules reused for building nodes.
  • /loop-it
     — sequential counterpart; use it when nodes heavily share files or serial safety matters.
  • /graph
     — this skill; use it when the DAG has genuine parallelism (independent subsystems).
  • /review-it
    , 
    /ship-it
     — real skills each node's subagent invokes.
undefined
/prd → /prd-to-spec → /to-issues ─┬─► /loop-it   （串行：一次处理一个节点）
                                   └─► /graph     （并行：同时处理整个阶段）
                                          │
                     每个节点：内联/goal → /review-it → /ship-it（在专属工作目录中）
  • /to-issues
     —— 构建节点时复用其分解规则。
  • /loop-it
     —— 串行版本；当节点大量共享文件或串行安全性至关重要时使用。
  • /graph
     —— 本Skill；当DAG存在真正的并行性（独立子系统）时使用。
  • /review-it
    , 
    /ship-it
     —— 每个子Agent会调用的真实Skill。
undefined