graph

Assign a goal. Get back a receipt, not a claim.

/graph <goal> decomposes any goal into a DAG of single-job specialist agents with typed JSON hand-offs on every edge, runs it in the background, and — for the goals that matter — hands you an artifact you can re-verify yourself: a rerunnable proof harness, a re-runnable citation table, or a measured disagreement across independent framings.

That's the whole idea. A single self-looping agent (Claude Code's /goal) can only ever tell you "I checked, I'm confident." That's a self-report — you take it on faith. /graph is built to hand you the instrument reading instead: variance is undefined for one observer, and a verdict the sole narrator declares is not proof.

/graph "audit this repo's route handlers for security issues"

                     ┌──▶ find:injection ──┐
  scope ─────────────┼──▶ find:authz ──────┼──▶ dedup ──▶ verify ×3 votes ──▶ synthesize
  (which files       └──▶ find:secrets ────┘   (code,     per finding          (merged report,
   matter?)              (parallel lenses)      free)     ≥2 refute = dead)     fixes, stats)

Every arrow is a JSON schema, not a paragraph of vibes. Each node does exactly one job. Findings that don't survive verification are listed as refuted or unverifiable, so the split is visible instead of buried.

Vocabulary. A DAG (directed acyclic graph) is the plan. A node is one specialist agent doing one job. An edge is the typed JSON artifact a node hands the next. The sink is the final node — what you actually wanted. Throughout: nodes count the design; agents count the spend (fan-out and verification multiply nodes into agents).

---

/goal vs /graph — the difference in one table

	/goal (one self-looping agent)	/graph (DAG of specialists)
Output	a conclusion in prose	a conclusion + a receipt you re-verify
Trust model	trust the narrator	check the instrument
Verification	the same agent re-reading itself	a different agent with fresh context, blind to the answer
Coverage	one context window	many independent finders
Best at	fast, focused, cheap	high-stakes, broad, or must-be-provable
Cost	1 agent	many (that's the price of the receipt)

They are not the same tool scaled up. They differ in kind: the loop optimizes for a good answer fast; the graph optimizes for an answer you don't have to take on faith.

---

Should you use /graph? (30-second answer)

One question decides it: would you want to double-check this answer yourself?

• Yes → use /graph. It does the double-check and hands you the proof so you don't have to. Reach for it when:
  • the answer must be provable — "does this fix actually work?", a security/reliability audit before a release, "is this review's citation real?"
  • the goal is bigger than one context — audit N files, migrate N components, survey many sources (it found 2× the bugs of a loop on a 282-file audit)
  • being wrong is expensive, or you want a measured second opinion instead of one confident guess
• No → just use plain Claude / /goal. It's 3–88× fewer agents (per EVIDENCE.md) and already precise on: one focused change, a quick fix, a task you'll accept on trust, anything exploratory. /graph's own Step-0 gate will tell you the same and refuse to over-engineer it.

Rule of thumb: /goal = a good answer, fast and cheap. /graph = an answer plus a receipt, slower and pricier. Pay for the receipt when the answer has to hold up. Full numbers below and in EVIDENCE.md.

---

Proven, not claimed

Every categorical claim here was tested head-to-head against /goal on the same task, same model, same repo — and the receipts were re-verified by an independent agent, not just asserted.

Across all 3 tests	/goal	/graph
Re-verifiable receipts shipped	0 of 3	3 of 3
Real findings (Test ③)	13	26 — 2.0×
Recall (Test ③)	~65%	~90% — +25 pts
Precision (Test ③)	100%	~100% — tie
Source files mutated while "verifying" (Test ①)	1	0
Agents / run	1	3–88

The trade in one line: /graph spends 3–88× the agents to turn an unverifiable claim (0/3) into a re-verifiable receipt (3/3), and to ~double the findings where scope beats one context — at equal precision.

① Executable claim — "this bug reproduces / this fix makes the test pass" (real median-off-by-one):

	delivered	your repo	third party can re-verify?
/goal (ran the test)	prose "I ran it, it flips"	mutated it — left the fix in place	no
/graph oracle-forge	a harness: exit 1 as-is vs exit 0 fixed	untouched (ran in a throwaway worktree)	yes — the tester re-ran the harness

② Non-executable claim — "is this review's citation actually supported?" (planted bad citation):

	caught it?	delivered	re-verifiable from the output alone?
/goal	yes	prose with a couple quotes	no — reopen both docs and redo the audit
/graph grounded-claim-audit	yes	claim→verbatim-span table + crux + the exact grep commands	yes — the tester re-ran the greps

③ Coverage at scale — exhaustive silent-error audit of a real 282-file repo:

	real findings	precision	recall	cost
/goal (1 loop)	13	100%	~65%	1 agent
/graph (full power)	26	~100%	~90%	88 agents

The honest read (baked into the plugin itself): on a small/clean task a capable loop is already precise — so /graph's edge is coverage (test ③, 2× the real bugs) and the receipt (tests ① and ②), not "catching more" on easy problems. The receipt costs real agents; it's worth it when being wrong is expensive, and wasteful when the loop is already right. /graph's own Step-0 gate tells you when not to use it. And it's three tests, not thirty: enough to demonstrate the receipt mechanisms work, not a distribution over the tail — treat the numbers as existence proofs, not benchmarks.

---

Install (2 minutes)

Inside Claude Code, run:

/plugin marketplace add ayaangazali/graph-engineering
/plugin install graph@graph-engineering

Then restart the session (plugins load at startup). /graph, /graph-plan, /graph-save, /graph-goal, /graph-next, and /graph-eval are now available in every repo on your machine. If the bare name doesn't autocomplete, the namespaced form /graph:graph <goal> always works.

Requirements. Claude Code ≥ 2.1.154 with the Workflow engine (any paid plan; on Pro, flip Dynamic workflows on in /config). Check with claude --version; update with claude update. No engine? /graph detects that and automatically falls back to plain subagent orchestration — same schemas, lighter verification (1–2 refuters instead of 3), capped at ~8 nodes, zero setup.

(API semantics verified against 2.1.216 — see the cheat sheet.)

Other install methods

Try without installing:

claude --plugin-dir /path/to/graph-engineering

Pin in project settings (.claude/settings.json) so your whole team gets it. Register the marketplace and enable the plugin — enabledPlugins alone fails for teammates who never ran /plugin marketplace add:

{
  "extraKnownMarketplaces": {
    "graph-engineering": { "source": { "source": "github", "repo": "ayaangazali/graph-engineering" } }
  },
  "enabledPlugins": { "graph@graph-engineering": true }
}

---

Use it

/graph <any goal>

Goal	What the graph does
/graph does this fix make the failing test pass?	oracle-forge: build a harness, prove it flips fail→pass under the fix in a throwaway worktree, ship the rerunnable harness
/graph audit src/routes for security issues	3 parallel lenses → dedup → 3-vote adversarial verify per finding → merged report with fixes
/graph does REVIEW.md's claims hold up against the source docs?	decompose to atomic claims → bind each to a verbatim span → blind-check past planted decoys → claim→span table + crux
/graph which queue system fits our stack?	K decorrelated framings → cluster → a measured disagreement distribution, not one confident guess
/graph migrate src/ui from CSS modules to Tailwind	map: one agent per component in an isolated worktree → verify each diff builds → index-based merge

What you'll see: the DAG printed before anything runs (above ~25 projected agents it asks first), an approval prompt for the workflow, live progress per phase in /workflows, and one final report with stats — confirmed / refuted / unverifiable, plus the receipt.

Commands

Command	What it does
/graph <goal>	Design the DAG, then execute it
/graph-plan <goal>	Design only — see the DAG, schemas, projected agent count, and full script before spending tokens
/graph-save [name]	Persist the last run as .claude/workflows/<name>.js — replay it as /<name> next session
/graph-goal <goal>	Compile a long-horizon goal into a persistent goal graph on disk — frozen objectives + gated nodes
/graph-next [slug]	Execute one gated tick of that graph: drift-check, work the frontier node, run its gate, write back
/graph-eval <task-class>	(advanced/offline) code-gated A/B to pick better finder briefs on synthetic plants

/graph-save is the sleeper feature: any graph that worked once becomes a permanent, parameterized slash command for your whole team (project workflows ship with the repo).

Long-horizon goals: the persistent graph

A one-shot /graph run designs its DAG in context and forgets it. For a goal that spans sessions — a project an agent works at continuously — that's the wrong shape: nothing on disk says what's done, done-conditions are self-graded prose, and last week's "done" silently rots as the code moves. /graph-goal + /graph-next fix exactly that:

/graph-goal "ship v1 of the auth system"     compile once: frozen objectives +
                                             gated nodes → .claude/graph-state/<slug>.json
/graph-next                                  one bounded tick: drift-check → frontier
                                             node → work → gate → write back → stop
/loop /graph-next                            continuous autonomous progress

The design pins everything an autonomous agent could lie to itself about to something checkable:

• done is an exit code, not an opinion — every node carries a machine-checkable acceptance gate (a card-9-style rerunnable harness, or concrete check commands), authored to fail before the work exists. No gate, no done.
• Freshness is a git SHA — each done node records last_verified_sha and the files it watches; a pure-git drift sweep at the top of every tick flips stale nodes to needs_reverify and reruns their gates. Tuesday's commit can't silently keep Monday's "done".
• Scope is frozen — objectives are written once, by you; a tick may split nodes and add gated subtasks under an existing objective, but can never add objectives, drop nodes, or grade its own work. Anything normative lands in awaiting_human.
• Cost stays flat — a tick works one node inline (cheap loop); full /graph fan-out fires only on nodes explicitly marked wide (discovery/audit shapes). Two failed gate attempts → blocked with evidence, move on. No infinite grinding.

The state file is plain committed JSON (format: skills/graph/reference/goal-state.md) — the audit trail of what the loop did unattended is history, readable by a human in one screen.

---

The shape gallery

/graph composes thirteen shapes (full cards with runnable skeletons live in skills/graph/reference/patterns.md):

1. Validation chain    item ─▶ produce ─▶ verify ─▶ fix ─▶ re-verify   per-item, streaming
2. Fan-out + merge     ┌▶ find:a ┐
                       ├▶ find:b ┼─▶ dedup ─▶ verify                   parallel lenses, one barrier
                       └▶ find:c ┘
3. Judge panel         N authored attempts ─▶ blind judges ─▶ synthesize  wide solution spaces
4. Adversarial verify  claim ─▶ 3 refuters ─▶ ≥2 refute = dead         noisy claims you can't afford wrong
5. Loop-until-dry      rounds of finders until 2 come back empty        discovery of unknown size
6. Map-reduce sweep    n items ─▶ n mappers ─▶ index-based reduce       migrations, bulk audits
7. Evaluator-optimizer sink ─▶ grade vs goal ─▶ repair once             refine one artifact to a goal
8. Gated sequence      graph 1 ─▶ human decides ─▶ graph 2              a decision mid-goal
─── the categorical five: a receipt a loop cannot produce ─────────────────────────
9. Oracle-forge        claim ─▶ 2 counterfactual worlds ─▶ flip-check   a rerunnable proof harness
10. Consensus dist.    K framings ─▶ cluster ─▶ distribution            a measured disagreement, not a guess
11. Obligation ledger  spec ─▶ discharge each ─▶ coverage ledger        completeness over a written contract
12. Grounded audit     claims ─▶ bind spans ─▶ blind-check + decoys     a claim→span table + VOID gate
13. Crucial experiment sealed bets ─▶ blind fetch ─▶ enum match         a pre-registered discriminating fact

Cards 9–13 are the difference in kind from /goal. For executable goals the receipt is rerunnable — card 9 reads a real exit code, a non-model oracle. For non-executable goals there's no world oracle, so the receipt is auditable: cards 12–13 manufacture a code-enforced information barrier (a blind checker the orchestrator was provably never fed the answer) plus re-readable spans and code-computed tallies. Honest limit: those non-executable verdicts still bottom out in same-model judgment — they're auditable, not truth certificates — so pure "is this sound?" routes to the disagreement distribution (card 10), never to a fake proof. See examples/oracle-verify.js, examples/grounded-claim-audit.js, and examples/consensus-diagnosis.js.

How it works

No servers, no framework, no runtime dependency. The plugin is knowledge, not infrastructure — a handful of markdown files:

1. The graph skill teaches Claude a design discipline: qualify the goal (don't graph what a loop does fine), route by failure mode to the right receipt, decompose into single-job nodes, contract every edge as a JSON Schema, execute.
2. Execution uses Claude Code's native Workflow engine — deterministic JavaScript orchestrating subagents, with schema-validated outputs enforced at the tool layer (the same machinery behind Anthropic's built-in /deep-research).
3. No Workflow engine? It falls back to layered fan-out with the plain Agent tool: same DAG, same schemas, validation done by the orchestrating model.

The core (README + SKILL.md) reads in about ten minutes; the pattern gallery is reference you dip into as needed. Start with skills/graph/SKILL.md.

When NOT to use this

Graphs aren't free — every node is a fresh context that must be briefed, and a badly modeled graph is worse than a good loop. /graph's own Step-0 gate enforces this:

• One focused change (fix this bug, rename this function) → just ask Claude. /graph will say the same and do it inline.
• Fewer than ~2 genuinely independent subtasks → the sweet spot is 2–4 specialist nodes (3–5 for large goals); more only pays for mechanical fan-out over items, not extra "thinkers".
• Everything re-reads the same big context → N agents each re-briefed on the same 50 files loses to one persistent-context loop. Graphs win on independent work.
• Tight token budgets → verification alone is ~3× the agents of the nodes that produce claims. That's the price of the receipt; don't pay it if you don't need it. /graph-plan shows the projected agent count before you commit.
• Human judgment mid-flow → workflows can't pause for input, so /graph splits the goal into two sequential graphs at the decision point (shape 8).

FAQ

"Workflow tool not available" — now what? Nothing to do: /graph detects it and runs as a layered subagent fan-out (same schemas, lighter verification, ~8 nodes). Full engine needs Claude Code ≥ 2.1.154, a paid plan, and on Pro Dynamic workflows enabled in /config.

How much does a run cost? Reported in projected agents — fan-out and 3× verification mean a 6-node design can spawn ~40–80 agents. /graph-plan shows the number before you spend.

Watch / cancel / resume? /workflows shows live progress and cancels. Runs execute in the background. If one fails halfway, completed nodes are cached — edit the persisted script and resume; only the failed/edited nodes re-run.

Does it work in any repo / language? Yes. The plugin ships no code that runs in your project — nodes are Claude subagents reading your repo like Claude always does.

Is anything sent anywhere? No. Pure prompt engineering — no servers, no telemetry, no hooks. It's the markdown files in the repo layout below; that's the whole plugin.

/graph collides with a command I already have? Project skills win over plugin skills; the namespaced form /graph:graph <goal> always works.

Repo layout

skills/graph/            the core skill: qualify → route → decompose → contract → execute
  ├── SKILL.md
  ├── fallback.md        no-Workflow orchestration playbook
  └── reference/         API cheat sheet, thirteen pattern cards, goal-state format
skills/graph-plan/       dry run: DAG + script, zero execution
skills/graph-save/       persist a run as a reusable /command
skills/graph-goal/       compile a long-horizon goal into a persistent goal graph
skills/graph-next/       one gated tick of that graph (loop it for autonomy)
skills/graph-eval/       offline, code-gated A/B to pick better finder briefs
agents/dag-node.md       JSON-disciplined node executor (fallback path)
agents/blind-checker.md  information-isolated read-only checker (cards 12/13)
examples/                runnable saved workflows to copy: security-audit,
                         oracle-verify (proof harness), consensus-diagnosis,
                         grounded-claim-audit, crucial-experiment
.claude/workflows/       this repo's own refine-panel — we dogfood: it reviews
                         this repo through the very methodology it ships

Contributing

Issues and PRs welcome. Good first contributions: a new pattern card with a skeleton that obeys the determinism rules, or a worked example under examples/. Run /refine-panel from this repo before large changes — five reviewers are cheaper than one maintainer.

License

MIT