Graph

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)

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:

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

Step 4: Pre-flight Checks

Before the first wave (same spirit as /loop-it):

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):

# 1. Write the initial checkpoint (all nodes pending, current_wave 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

# 2. Keep it out of git.
grep -qxF '.graph_state' .gitignore || printf '.graph_state\ngraph.html\n' >> .gitignore

# 3. Render the Claude-style light-theme dashboard.
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.

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

For each wave, in order: