/graph

name: graph
description: "Graph engineering for parallel task execution: convert a task, PRD, SPEC, or issue set into a dependency graph (DAG), layer it into supersteps, then implement each independent node concurrently with subagents — each node runs /goal → /review-it → /ship-it in an isolated git worktree, with a fan-in barrier between waves. Triggers on: graph, graph engineering, build a graph, task graph, dependency graph, DAG, parallel implement, 并发实现, 并行实现, 任务图, 把任务变成图, fan-out fan-in, superstep, dynamic workflow."
user-invocable: true
allowed-tools:
  - Bash(git:*)
  - Bash(gh:*)
  - Bash(cat:*)
  - Bash(mkdir:*)
  - Bash(grep:*)
  - Bash(python3:*)

graph — Task/PRD to Parallel Execution Graph

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.

---

Mental Model (borrowed from LangGraph / graph engineering)

| Concept | Here | |---------|------| | **Node** | One implementable unit of work (an issue / subtask) | | **Edge** | A dependency: `B depends on A` → edge `A → B` | | **Superstep / wave** | A set of nodes whose deps are all satisfied — run concurrently | | **Fan-out** | Dispatch 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-plan** | After 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.

---

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

---

Step 1: Locate & Decompose Input

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.

---

Step 2: Build the DAG & Validate

Construct edges from `deps`. Then validate:

| Check | Action 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).

---

Step 3: Topological Layering into Waves

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