Most people run AI agents the way they type: one line at a time. Ask, wait, fix what came back, ask again. By the end of the day the context is full, the agent has forgotten what it did three steps ago, and twenty open chats hold no single answer.
The work was a graph. The prompt drew a line.
That wiring layer between prompts and product has no textbook and no name on most teams. I call it graph engineering.
By the end of this you will have drawn your own graph, built one in the agent you already use, hardened it against the two failures that break most fleets, priced your real speedup before deploying a single agent, and taken six ready-to-run recipes with you. The receipts wait at the end: a production runtime rewritten in eleven days by the exact graph this course draws.
Before we get into it: the builds, the fails, and the alpha from these experiments go out on X and in the Telegram channel, every day. Both are free.
The linear agent feels like the natural shape because it is the shape of typing. One line, one thing at a time.
Three words carry the whole discipline.
A node is one unit of work. One agent, one input, one output. A single worker at a single station.
An edge is a dependency. The output of one node is the input of the next. Picture a rope handing a bucket down the line. If the next worker never opens the bucket, the rope is decoration.
A graph is the network where every independent piece runs at the same time.
“Do A, then B, then C” is already a graph. It is the weakest one available, one edge wide. B hangs and C never happens.
Line vs graph. Nodes are work. Edges are the real dependencies..
None of this machinery is new. The US Navy drew the same critical-path chart to schedule the Polaris missile in 1957. make -j compiled code in parallel in 1976. MapReduce carried the idea into the data center in 2004, and Airflow wired it into daily pipelines by 2014. The same directed graph of dependencies every time, arrows only flowing forward. Fifty years of proven machinery, and it has only just reached agents.
The mistake nearly everyone makes: reading “and then” as a wire.
Half of your and-thens are not wires. They are two unrelated jobs chained into a line, each forced to wait on a result the next step never opens.
The test is one question, and the question is the whole skill: does the next step read the previous step’s output? Yes means the edge is real, so the order stays. No means there was never an edge, so the steps run at the same time.
Take a real one: “summarize this file, and then tell me the weather.”
The weather never reads the summary. Two boxes, no arrow. A linear script chains them anyway because the words sounded like a wire.
Two boxes, no arrow: the “and then” that was never an edge..
Now put your actual task list through the same question, seam by seam. The arrows that survive are your real edges. The rest were standing in line for nothing.
Take what survived and draw it.
Real edges keep their order. Everything else stacks side by side to run together. What is left on the page is your graph.
Then find the longest chain of real edges still standing. That chain is your critical path, and it is the floor under your wall-clock time. Sixteen agents do not shorten it. Sixty-four do not either.
The critical path: the longest chain of real edges is the fastest this work can ever finish..
To make the job faster, cut a false edge. Adding an agent does nothing here. A to B to C never beats the sum of its own steps, no matter how many workers stand around it.
Draw the graph wide enough and a new problem appears: parallel agents in one folder start overwriting each other’s work, a hole Step 4 closes.
You do not need a paid feature underneath this. Any capable agent runs a graph if you hand it the structure in plain words. Paste this into the agent you already use:
You are an orchestrator. Build a graph, not a chain.
TASK: <describe the work> across <N> independent items (e.g. every file in src/routes/).
RUN AS A GRAPH:
1. FAN OUT — one worker per item, in parallel. Each worker: one input, one output. Workers share NO state.
2. VERIFY — for each worker's finding, spawn a SEPARATE verifier with FRESH context. The verifier checks a REAL signal (does the test pass / does the claim hold), not "did the worker say done".
3. MERGE — collect all verified findings into ONE report. Intermediate results stay in your notes, not re-fed as chat.
RULES: workers never review their own work; the verifier never implements; start with max <20> items to stay cheap.
Begin.One paragraph, and any capable agent becomes a graph runner.
Inside Claude Code you skip even that. Describe the graph in one line and it writes the orchestrator for you:
ultracode: audit every route handler under src/routes/ for missing authentication checks, then adversarially verify each finding before reporting. Analyze at most 20 files to start.Claude drafts a JavaScript orchestrator, prints the four phases (scope, fan out, verify, synthesize), and waits for your yes.
Then it runs in the background while your session stays free. Open /workflows and watch: sixteen workers up at once, each on its own file, a separate verifier picking up every finding on fresh context, and all of it folding into one report instead of the twenty scattered chats you would have opened by hand.
One run, four phases: scope, fan out, verify, synthesize..
If you like the run, press s. It saves to the project’s .claude/workflows/ (versioned, shared with your team, wins on a name clash) or to your personal ~/.claude/workflows/. Saved, it becomes a /name command you rerun forever. Trigger one ad hoc with the word ultracode. Turn it on for a whole session with /effort ultracode.
Saved graphs are also how I ship this pattern to other people. My public Suede skill pack carries /suede-codex-fleet, the same shape with OpenAI Codex CLI workers underneath: the orchestrator briefs, workers fan out in parallel, and a review gate holds everything they return.
Two caps hold the machine: sixteen agents at once, a thousand per run. A hard brake on a runaway.
The “zero tokens” line you will hear about workflows is half true. The coordination is free, because it is plain code, and intermediate results live in script variables instead of piling into your context. The agents underneath are all billed. A workflow burns more than a normal session, not less. Start at twenty files. Widen once it works.
Two failures take down most fleets. Two moves close them.
First: never let an agent grade its own work. This is measured, not folklore. GPT-4 recognizes its own writing 73.5% of the time, and that self-recognition causally drives it to prefer the very text it wrote (Panickssery, NeurIPS 2024). Put a model in a lineup of answers and it scores its own higher: GPT-4 by 10%, Claude by 25% (Zheng, NeurIPS 2023).
The maker never grades its own exam. So the verifier is a separate node with fresh context, an outsider that never touched the work, and it checks a real signal: a test that passes, a claim that holds against the source. For subjective calls, use a jury of three models from different families.
I froze this rule into my own tooling. /suede-code-review in the Suede pack is a verifier that only reviews: findings and a verdict, never the implementation.
A graph of agents sharing one context is one loop with extra steps, agreeing with itself.
Executor, fresh-context verifier, report. Below: one shared checkout collides, worktrees do not..
Second: isolation. Parallel agents in one git checkout clobber each other, the hole Step 2 left open. The fix comes straight off the Bun port. Freeze one rule into every worker:
Never git stash. Never git reset.
No git command except committing a specific file.
No slow commands before the test phase.That is the rule that let sixty-four agents share four checkouts without overwriting each other.
Then shard the fleet across worktrees, separate working copies of the same repo, one per crew. Isolate by the group, four worktrees of sixteen, so you never pay for sixty-four separate checkouts. Set worktree.baseRef: “head” and each one starts from your current branch. Now the fleet runs wide and nobody overwrites anybody.
One run unfolds into a thousand agents. Sixteen at a time, deployed in waves from a single window.
One prompt in, one answer out, up to a thousand agents in between..
Sixteen agents rarely buy sixteen times the speed, and you can compute the real number before deploying a single one. Amdahl’s law is the calculator you check before scrambling the fleet:
S = 1 / ((1 − p) + p/N)
p = share of the work that is independent (parallel)
N = number of agents
p = 0.95, N = 16 → ×9.14 (not ×16)
p = 0.70, N = 16 → ×2.91
ceiling (N = ∞) = 1 / (1 − p)The naive guess says sixteen. The merge and the verify eat the difference, and sixteen agents at 95% parallel work buy ×9.14.
Sixteen agents at p = 0.95 buy ×9.14, not ×16..
Push N and the ceiling holds. Even 256 agents at 95% only reach ×18.6. The serial tail is the anchor: the final merge, the verification, every real edge. The critical path was the floor. The serial fraction is the cap.
Estimating p is the Step 1 test again. Count the independent nodes against the chained ones and you have your number before one agent runs.
The method never changes: find the real edges, fan out, verify on fresh context, isolate the workers. Only the task line changes.
Security sweep. One agent per file hunts a missing auth check. An independent verifier confirms every hit before it reaches the report.
Cited research. The question splits into angles, the searches run in parallel, and the agents refute each other before a word gets written. Claude Code ships this one as /deep-research.
Module port. File by file. The test suite is the gate, and every failure loops back into the queue.
Adversarial diff review. Route by size. A small diff gets one pass. A large diff gets the full parallel audit.
Scheduled ecosystem scan. Save it once, run it by name on a timer.
Unknown-size discovery. Finders run in parallel, every result is checked against everything already seen, and the loop ends when two consecutive rounds come back empty.
Six graphs, one method. Save the card.
Change the task line. The graph is already built. I keep mine as skills: the Suede pack at github.com/JasonColapietro/suede-creator-skills ships these graphs as slash commands, /suede-codex-fleet for the worker fan-out, /suede-agent-teams for coordinated lanes with gates and rollback plans, /suede-code-review for the verify.
Now the receipts. An AI rewrote a million lines of production code in eleven days, and the machinery was the exact graph you just learned to draw.
The codebase was Bun, the JavaScript runtime millions of apps quietly depend on. It went from 535,496 lines of Zig to more than a million lines of Rust, across 6,502 commits, inside two weeks. By hand, that is close to a year of work for a team. The fleet ran about fifty workflows, sixty-four agents at peak sharded across four worktrees of sixteen, and the merge gate the whole way through was the full Bun test suite: 1.38 million assertions across six platforms. The models were ordinary, the same ones you already run. The shape of the work did it. Out the other side came Bun v1.4.0.
The result is already on your machine. Ten seconds proves it:
strings ~/.local/bin/claude | grep -m1 'Bun v1'
# → Bun v1.4.0The tool you code with runs on the runtime that rewrite produced. Eleven days for close to a year of team work, on the graph you now know how to draw.
The linear agent is the first shape you reach for because it is the shape of typing. It was never the ceiling.
Once you see nodes and edges, you read every task as a graph. Walk the seams. Cut the arrows that were never there. Fan the independent work wide, and gate the few edges that carry a result. The question changes with it: you stop asking one agent to do more in a line, and you start drawing a graph that runs the work wide.
Three rules hold the whole discipline:
Fan out where the work is independent.
Gate the edges where confidence matters.
Freeze the rules that keep parallel workers from colliding.
A prompter asks a question. An architect draws a graph.
The layer nobody teaches is yours now.
No posts
Comments
Nothing yet. Say the first thing.
Sign in to join the conversation.