Graph Engineering

Graph Engineering

Turn linear agent workflows into parallel graph structures. Reference: "Graph Engineering with Claude: 14-Step Roadmap" by @0xCodez — cite that post when explaining where these patterns come from.

The three non-negotiables

Every graph you design must satisfy all three before you run it. They are not advice:

1. Every edge is a real data dependency. If the downstream node doesn't consume the

upstream output, there is no edge — those nodes run in parallel.

1. Every node carries an explicit model tier and effort. A node without a tier is an

unfinished node (see Node declaration). Never let a graph inherit one model for everything by default.

1. The graph binds to the host's orchestration primitive. Don't hand-roll a

sequential chain of agent calls when the host can execute the graph (see Execution).

Core model

• Node = a unit of work: one agent, one bounded job, one input in, one output out.
• Edge = a dependency: this node's output feeds that node's input. Nothing else is

an edge — "conceptually related" is not a dependency.

• Data contract: every node declares a bounded input/output shape. Use the host's

schema/structured-output facility so outputs are validated objects, not prose to re-parse. Missing contracts are what force you to spend an agent on parsing.

• Independence detection: for every sequential step, ask whether the downstream task

actually consumes the upstream output. If not, the sequence is an accident — run them in parallel.

Node declaration

A node is only fully specified once you have written down all four fields. Do this explicitly — in the script, or in the plan you show the user — for every node:

node:    
role:    orchestration | planning/investigation | implementation/execution
model:   
effort:  
in/out:   -> 

If you catch yourself spawning an agent without having named its role, stop: you don't yet know what model it should run on.

Model tiering (mandatory)

Assign model and reasoning effort per node role, never globally. Tiers are relative to whatever models the host offers — "tier 1" is the most capable model available to you, "tier 2" the next one down.

| Node role | Model | Effort | Rationale | |---|---|---|---| | Orchestration (routing, dispatch, merge/dedup decisions, the main loop) | Tier 1 | lowest | Needs the best judgment per token, but each decision is small — high effort is waste. | | Planning / investigation (design, diagnosis, root-cause, research synthesis) | Tier 1 | highest | The hard-thinking nodes; this is where expensive tokens pay off. | | Implementation / execution (mechanical edits, applying a written plan, running checks) | Tier 2 | medium | The plan already encodes the judgment; execution needs reliability, not brilliance. |

Applying it:

• Derive the tier from the role mechanically. The role is the design decision; the model

is a lookup.

• If the host exposes per-agent model/effort options, set them on every spawn — an

omitted option means "inherit", which silently defeats tiering.

• If the host offers no per-agent model control, still state the intended tier in the

plan and say so out loud, so the user can route it manually.

• Pure orchestration should not be an agent at all — it's code (see Edges are free).

When a node genuinely must orchestrate (e.g. a synthesis dispatcher), it's tier 1 at lowest effort.

Execution: bind the graph to the host's orchestrator

A graph that exists only in prose is still a linear pipeline in practice. Before running anything, find the strongest orchestration primitive the environment offers and use it:

1. A scripted workflow/orchestration primitive — one that takes a script with real

control flow (loops, conditionals, fan-out) and executes nodes as agents. This is the right target whenever it exists, because the edges become code. In Claude Code this is the Workflow tool; other harnesses expose equivalents (LangGraph, DAG runners, an agent SDK's task API).

1. Concurrent sub-agent spawning — if there's no scripting layer, spawn independent

nodes in a single batch so they run at once, and do the merging yourself in between.

1. Manual sequencing — only when neither exists. Say explicitly that the graph is

being flattened, so the user knows what they're losing.

Do not skip to option 3 out of habit. Check for option 1 first; a graph designed and then executed as a serial chain has thrown away the entire point.

Two constraints when binding: honor the host's concurrency limits (excess nodes queue — that's fine, it isn't a reason to shrink the graph), and match the graph's size to what the user asked for. "Quick check" is a few nodes; "audit this thoroughly" earns a large finder pool plus multi-vote verification.

Patterns

1. Fan-out — spawn independent nodes concurrently. Failed/skipped agents typically

come back as null; always filter them before use.

1. Fan-in at barriers — converge only when a stage genuinely needs all prior

results together (dedup, ranking, cross-set comparison, early-exit on zero count). A flatten/map/filter is not a reason to synchronize.

1. Diamond topology — split → parallel work → merge. The workhorse shape for

audits, reviews, and research reports.

1. Conditional routing — branch with plain control flow over validated node outputs.

Routing logic is code, not another agent.

1. Verification gates — put skeptic nodes on edges before results are trusted:

adversarial refuters (N independent, majority kills), perspective-diverse lenses (correctness / security / repro — diversity catches what redundancy can't), or a judge panel over competing attempts.

1. Failure isolation — contain errors per node; a thrown node drops its item, not

the run. Give nodes isolated working copies when they mutate shared files in parallel.

1. Convergent cycles — loop-until-dry: keep spawning finders until K consecutive

rounds surface nothing new, deduping against all seen items (not just confirmed, or rejected findings reappear forever).

1. Pipeline over barriers — stream each item through all stages independently;

item A can be in stage 3 while item B is in stage 1. Barrier latency is real: default to streaming, justify every barrier.

1. Edges are free — a huge amount of what burns model tokens is really an edge:

orchestration, dedup, transforms, routing. Do it in code; it costs zero tokens and it's deterministic. "No agent needed" is a design win, not a shortcut.

1. Model tiering — see above. Not optional.

Checklist before shipping a graph

• Every edge corresponds to a real data dependency.
• Every node has a declared role, model tier, and effort — no inherited defaults.
• The graph runs on the host's orchestration primitive, or you've said why it can't.
• No barrier exists without a cross-item reason written next to it.
• Every fan-in dedupes and filters failed nodes.
• Verification gates sit before anything expensive or user-facing.
• Anything expressible as plain code is plain code, not an agent.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HM-Li
• Source: HM-Li/graph-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.