graph-engineering

Files (5)

• GRAPH.template.md
• LIFECYCLE.md
• NODE.template.md
• SKILL.md
• TOPOLOGIES.md

SKILL.md (first lines)

# Graph Engineering

The **graph is the plan you look at**. Nawab §0–§18 still captures scope
(north star, blockers, commit discipline). This skill owns **shape and
scale**: what can run at once, which slice owns which files, and the
per-node plans that execute those slices.

Each **node** is a bounded workstream with **its own plan file**. The master
graph **must list a markdown link to every node plan** so you can open any
slice without hunting.

**Not graphify.** `graphify` maps a codebase. This skill shapes *execution*.

Template: [GRAPH.template.md](GRAPH.template.md)  
Node plan: [NODE.template.md](NODE.template.md)  
Lifecycle: [LIFECYCLE.md](LIFECYCLE.md)  
Topologies: [TOPOLOGIES.md](TOPOLOGIES.md)

## Persistence

Once loaded, stay on the graph for the **whole run** — every wave, including
resume after a dead session. Do not drift back to one sequential agent holding
the entire project. Ponytail on every code write.

Off only: "stop graph" / "run it linearly" / user reverts to §18.

---

## When to load

Load **only** when the user named this skill. Signals:

- `/graph-engineering` or `@graph-engineering`
- "graph this plan" / "graph engineering" / "run this as a graph"
- "one-shot this project" / "one-shot this feature"

**Do not load** because Plan mode is on or nawab-plans loaded.

**Skip the fleet** (one-node or short chain in §19) when the work is a real
1–3 step dependency. Do not invent nodes or nested plans for a hotfix.

This skill is for **entire products and major features** — research through
shipped software, proven by running it, then docs. Long, quality-rich,
parallel work.

---

## Hierarchy (depth 2, no more)

```text
EXECUTION_GRAPH.md          ← what you approve and read
  plans/nodes/<id>.md     ← one collapsed plan per node (linked from the graph)
```

1. **Graph** — topology, contracts, waves, **links to every node plan**.
2. **Node plan** — feature-mode nawab, collapsed: objective, paths, commits,
   gate, return contract. Not a second 18-section master.
3. **Stop.** A node plan does **not** spawn another graph unless the user
   names this skill again for that slice.

---

## Cursor primitives (not Claude Code)

Do not emit JS orchestration scripts or `.claude/workflows/`.

| Idea | Cursor |
|------|--------|
| Node | One `Task` (or lead job) that **executes that node's plan** against a JSON return contract |
| Node plan | `plans/nodes/<id>.md` — the only authority that node agent loads |
| Edge | Named artifact that actually crosses (schema field, file, list) |
| Fake "and then" | No Task, no wait — two node plans, same wave |
| Fan-out | Multiple `Task`s in **one message**, each prompted with **its** node-plan path |
| Plumbing | Lead code (`flatMap`, dedupe) — no extra node, no extra plan |
| Barrier / merge | Lead waits; one merge node whose plan sees the whole set |
| Verifier | Readonly `Task`s that try to kill findings before they flow on |
| Isolation | Disjoint write paths. Cloud worktrees only if the user asked |
| Cycle | `seen` set; dry stop after **2** empty rounds; dedupe vs **seen** |
| Model | `composer-2.5-fast` on extract/classify; `inherit` on merge/judge |
| Concurrency | Readonly: fan out freely. Writers: **2–4**, disjoint paths |

If a `model` slug is not in the session list, use `inherit`. Never guess.

---

## Gate 0 — Research, then questions (blocking)

**Before** nawab §19, node plans, or approval. Asking is expected. Do not
smooth over uncertainty.

1. Research the repo or state greenfield. 5–10 lines of what you found.
2. Ask numbered questions. Split **must-answer** (blocks compile),
   **trade-off** (neither option is obviously better — show both, ask
   PRIORITY), and **optional** (state the default).
3. **Stop. Wait.** Do not compile the graph on guessed architecture, UX,
   tenancy, or "we will figure it out in the node."

Full rules and the trade-off block: [LIFECYCLE.md](LIFECYCLE.md).

---

## End-to-end coverage

A full one-shot graph **includes every lifecycle stage** or marks
`N/A — [reason]`. Catalog: [LIFECYCLE.md](LIFECYCLE.md).

| Stage | Must mean |
|-------|----------|
| Docs-in | Existing docs good enough to plan, or listed gaps |
| Architecture | Boundaries + remaining trade-offs decided with the user |
| Design / UI UX | Required if there is a user-facing surface |
| Build | Fan-out slices with real edges only |
| Integrate | Barrier over the slices |
| Evaluate | Tests / evals that can fail |
| Run | **Boot it** — not only unit tests |
| Trials | **More than one** run (happy, empty, error, one regression) |
| Docs-out | README (and companions) **after** it works — `readme` skill |

A graph that ends at "code written" is incomplete.

From Vinayak-RZ/ARC, MIT.

More from Vinayak-RZ/ARC