Graph Engineering Is Two Ideas Wearing One Name

How harness, loop, and graph engineering actually stack, and how a graph learns without retraining

Graph engineering is two ideas wearing one name. Perhaps a lot more than two if I am being honest, but let’s try to compress this article into something tangible and avoid too much navel-gazing. One is the control-flow graph your agents run in: specialized nodes, typed routing edges, shared state on the wire. The other is the knowledge graph they think with: Markdown concepts, linked, versioned, progressively disclosed. Neither is new, but giving the movement a name has power much like when someone coins a design pattern name or a tech stack approach (Ajax). Naming it gives people the ability to define it. Everyone in July 2026 argued about the first one. Google shipped a spec for the second one a month earlier, and almost nobody connected them, which now they are starting to. The systems worth copying treat both as the same artifact, in the same repo, in the same files, which might be the real pattern to follow. Convergence is often king. One move, and it is what lets a graph learn without anyone touching a weight.

Key takeaways

• A single loop is the smallest possible graph, one node with an edge back to itself. Graph engineering is the floor above loop engineering, not a replacement for it.

• The two graphs, orchestration and knowledge, want to be the same file-native artifact. routes_to and depends_on are both just links in a Markdown file.

• Graphs learn by changing topology and trust, not weights. Six concrete operators, all of them already shipping in real code.

• Progressive disclosure and external anchors are non-negotiable. Without the first you burn context; without the second you build a bureaucracy that grades its own homework.

If you are coming in cold

Five terms carry most of the weight here. OKF (Open Knowledge Format) is Google’s June 2026 spec: a directory of Markdown files, one concept each, linked to each other. Progressive disclosure means showing an agent just enough to decide what to read next, rather than dumping a directory into its context, and something we used for a while before it got a name and became part of the agent skill spec. Blast radius is the set of things that break when you change one node. ULID is a sortable 128-bit identifier, used here to give every work item a stable identity. Ground-truth anchors are measurements that cannot be argued with, like a passing test or a green CI run, as opposed to one agent grading another’s report.

Start here, if you only read one section

The smallest useful version of everything below, and it is not a framework:

1. Add a directory of Markdown files to one repo, one concept per file, type in the frontmatter, links between them. You now have a valid OKF bundle.

2. Add a root index.md that lists what exists and nothing more.

3. Add a log.md. Append one line per change.

4. Next time an agent gets something wrong in a way it will repeat, write the node instead of correcting it in chat.

5. When you can no longer hold the shape in your head, run impact analysis before editing high-degree nodes.

The rest of this piece is why each of those five steps matters.

---

Abstract: In July 2026, the AI agent community started saying “graph engineering” the way it had spent the previous months in 2026 saying “loop engineering.” The framing arrived fast, got over-marketed within a week, and picked up two genuinely different meanings that nobody bothered to separate, and perhaps they shouldn’t. One is a control-flow graph, which is not even close to new (see LangGraph or Google ADK version 2): specialized agent nodes, typed routing edges, shared state, an orchestrator. The other is a knowledge graph: Karpathy’s LLM Wiki pattern, formalized by Google Cloud in June 2026 as the Open Knowledge Format. This article traces both origins, maps graph engineering against harness engineering and loop engineering, and then argues the interesting part: the two graphs want to be the same artifact. Two working systems already treat them that way, and a third supplies the learning mechanism the first two are missing. Along the way, we get concrete about the mechanic almost nobody names: how a graph learns, and what that means for an agent that has to improve without anyone retraining it.

---

One Sentence

Did anybody actually invent graph engineering? Not really. On July 18, 2026, Peter Steinberger (@steipete) posted a single question, and the vocabulary of a whole field moved:

“Are we still talking loops or did we shift to graphs yet?”

For most people, that post is the origin story. Within a day the internet produced manifestos and counter-manifestos, including David Khourshid (creator of XState, so a man who knows what a state machine is) calling parts of it slop. Carlos E. Perez wrote the elaboration most of the serious follow-ups cite. By the end of the month, vendors had maturity models. This is the power of giving something a name. It is like the line in the sand. It gives concepts meaning, and then we can discuss what that name means or not. Will we agree? Eventually. Then if someone uses it wrong enough times, the meaning changes, just like everything in the English language. I am looking at you, “monetization,” whose meaning changed because Internet bros used it wrong so many times that it no longer meant to physically produce coins or print paper money but somehow meant to make a profit. I digress.

The honest version, which is more useful than the hype version. The terminology was new in July 2026. The practice was not. LangGraph shipped StateGraph with nodes, edges, and state along the edges long before anyone tweeted about org charts. Microsoft AutoGen shipped GraphFlow with sequential, parallel, conditional, and looping flows. Google ADK shipped graph workflows and A2A delegation. I wrote build guides for two of them: LangGraph Essentials in Python and Multi-Agent Orchestration with Google ADK. The list is much longer than this, but this for sure is not a new concept per se. One of the better write-ups landed it exactly. Graph engineering is real and over-marketed, and both are true at once.

Why care about a name at all? Because the name decides what you reach for at 2 a.m. when the thing is broken and you have to pick a layer to go stare at. Naming the layers has been the real payoff of this whole vocabulary sequence, and the sequence is worth walking properly. Giving something a name gives it power, a debate, points, and counterpoints. Peter Steinberger has become the Martin Fowler of 2026 without the long, detailed descriptions.

---

The Stack Nobody Drew Until It Had Five Floors

The community converged on a five-layer model (the cleanest early statement of it came from @sairahul1 the following day):

Prompt → Context → Harness → Loop → Graph

Each layer got its name at the moment the layer below it stopped being where the failures lived.

Prompt engineering

You type words at a model. The failure mode is that the model misunderstands you. The fix is better words. This was 2023, and it is now table stakes rather than a discipline.

Context engineering

You stop typing the same words and start engineering what the model sees: retrieval, rules files, memory, injected standards. I covered the mechanics of this in Injecting the Right Rules at the Right Moment. The failure mode is that the model is working from the wrong facts. This is where CLAUDE.md, AGENTS.md, project memory, and rules-injection systems live.

Harness engineering

The harness is the environment the agent runs inside: prompts, tools, memory, permissions, state, evaluation, recovery. The model is the CPU. The harness is the operating system you own. If the term is new to you, start with What Is Harness Engineering; the long version, with the research, is in The Harness: The New Operating System for Agentic AI Scaling.

This one has real numbers behind it, which is rare in this field. The RUCAIBox survey “Agent Systems with Harness Engineering” synthesizes 502 references into a structured taxonomy, which is the closest thing the field has to a map. HarnessX (arXiv:2606.14249) reports an average of +14.5% across five benchmarks, and up to +44.0%, with the same model weights. Different harness, same weights, double-digit gains. CAAF (arXiv:2604.17025) reframes the harness as a deterministic, auditable enterprise asset for regulated sectors.

Harness engineering answers static questions. What can the agent see? What can it touch? What persists? What happens when it breaks? I have spent a good chunk of the last year writing about this layer, including observability and when to split one agent into several, and the thing that keeps surprising people is that number above. Same weights. Different environment. Double-digit gains.

Loop engineering

Then agents started running for hours instead of minutes, and the failures moved. Geoffrey Huntley’s Ralph method popularized the shape: run the agent until the goal is met, not until the response is done. Boris Cherny, who runs Claude Code at Anthropic, put it as bluntly as anyone has:

“I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.”

Loop engineering answers dynamic questions. What happens next? When does it stop? Who checks the work? How does it resume tomorrow? I have written a piece on each of those: stopping conditions, the maker/checker split, and managing loop state across sessions. Over the first half of 2026, a whole pile of jobs quietly migrated from “harness work” to “loop work”: scheduling, maker/checker verification, durable state across runs, sub-agent spawning. Anthropic’s Claude Managed Agents (June 9, 2026) took the three pieces every team kept rebuilding by hand- scheduling and evaluation and fan-out- and made them platform primitives. I unpacked what it removes and what it does not in Loop Engineering: The Problem and Why Claude Managed Agents Exist.

Graph engineering

And then loops hit their own ceiling: a single loop is one context trying to do every job. It searches, drafts, reviews its own work, and grades that review, all in the same window. Actually, I don’t think it ever judged its own work per se. There were always adversarial subagents (doers and judges), but let’s stay on script. But if we are being honest, a loop was always a graph with an orchestrator, workers, and judges. In its simplest form, it might rubber-stamp itself, but in reality it was always a graph because most people did not make this mistake. A single loop in a single context can pollute its own context by stirring raw source data into polished prose. And it can only ever do one thing at a time, no matter how many hours you give it.

Graph engineering is the practice of designing the graph your agents run in: which specialized nodes exist, which edges route work between them, and what shared state travels along those edges. How to divide up the work. Do things in parallel. Then somehow stitch this work back together into a final work product.

The line that makes the whole hierarchy click. A single loop is the smallest possible graph: one node with an edge back to itself. Graph engineering is not a replacement for loop engineering. It is the floor directly above it, exactly as loop engineering sits directly above the harness. I mapped that boundary and what is migrating across it in Harness Engineering vs. Loop Engineering.

---

Harness, Loop, Graph: The Comparison

Reading that table row by row is worth the extra minute.

Unit of design. The harness is scoped to a single agent’s world. The loop is scoped to that agent’s repetition over time. The graph is scoped to the relationships between multiple such agents. Each layer takes the previous layer’s whole output as its atom.

Question it answers. This is the diagnostic value of the vocabulary. If your agent deleted something it should not have, that is a harness problem (permissions, tools). If it kept working after the job was done, that is a loop problem (stop condition, verifier). If your writer agent produced a beautiful summary of the wrong research, that is a graph problem (state schema on the edge between researcher and writer).

Named. Only the July 2026 date is precise; the other two are approximate, because names of this kind get adopted rather than announced. The pattern still holds in all three cases. The name lands well after the practice and just before the vendor blog posts. Being early to the name is not the same thing as being early to the practice, and only one of those has ever shipped anything.

Core artifacts. Notice how the artifacts get more declarative as you climb. Harness artifacts are mostly configuration. Loop artifacts are mostly control code. Graph artifacts are mostly plain data, meaning a node list, an edge list, and a state schema. No accident. The shift from code to data is the hinge the second half of this article swings on.

Signature failure. Graph failures are genuinely new, because they are coordination failures rather than agent failures. Every node can be individually correct and the system still wrong. The previous two layers have no vocabulary for that bug at all.

Evidence it is real. The frameworks predate the name in all three cases, which is the normal way engineering vocabulary works. Nobody invented the three-tier architecture and then built one.

Perez adds the caveat that keeps this from being a diagram-drawing exercise. Topology alone does not save you. In his framing, you can build a beautiful graph of loops where “every one of those loops consumes reports” and no loop touches the ground. Graphs need anchors: measurements that cannot be argued with. Tests. Coverage floors. CI gates. A graph of agents grading each other’s reports is a bureaucracy, not an architecture.

---

The Other Graph

Now the part that got lost in the July noise.

The agent community spent July arguing about routing topology. Meanwhile, a separate thread, with almost no overlap in participants, had been building a completely different kind of graph. It finished in the same season, and almost nobody connected the two.

April 4, 2026: Karpathy’s LLM Wiki

Andrej Karpathy published a GitHub gist called llm-wiki. It was, by his own framing, an idea file rather than a product: one page describing a pattern. Stop making the model re-read your raw sources on every query. Compile the sources once into a structured, interlinked wiki of Markdown files, one file per concept, with cross-references and provenance. Then query the wiki.

The observation underneath it is the good part, quoted here as Google Cloud reproduced it in the OKF launch post:

“LLMs don’t get bored, don’t forget to update a cross-reference, and can touch 15 files in one pass. The bookkeeping that causes humans to abandon personal wikis is exactly what LLMs are good at.”

Every personal wiki I have ever started died of the same thing. Maintenance is tedious, and the payoff shows up months later, so the cross-references rot and then you stop opening it. Now read Karpathy’s sentence again. He is describing the exact work LLMs are best at, aimed at the exact reason humans quit. By most secondary accounts, the gist collected thousands of stars and dozens of re-implementations inside of a fortnight.

June 12, 2026: Google Cloud ships OKF v0.1

Google Cloud’s data analytics team (Sam McVeety and Amir Hormati) published the Open Knowledge Format, an open specification that formalizes the LLM-wiki pattern into a portable, interoperable format.

The spec is almost aggressively boring, which is its best feature. An OKF bundle is a directory of Markdown files. Each file describes exactly one concept. YAML frontmatter carries the small set of fields that need to be queryable. Files link to each other with ordinary Markdown links, and those links are the graph.

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| Column | Type | Description |
|---|---|---|
| `order_id` | STRING | Globally unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |

Exactly one field is required, and it is type. Everything else, including what types exist, is left to the producer. Google calls this “minimally opinionated,” and the design principle behind it is stated plainly in the launch post: the value of a knowledge format comes from how many parties speak it, not from who owns it. Not tied to a cloud, a database, a model provider, or an agent framework. Never requires a proprietary account or SDK to read.

Two optional file conventions do most of the interesting work:

• index.md at each directory level, for progressive disclosure as an agent navigates the hierarchy

• log.md, for chronological history of changes

I wrote up why the spec matters, and why disclosure beats raw context, in Open Knowledge Format: Agents Don’t Need More Context. They Need Better Disclosure. Google shipped an enrichment agent that walks BigQuery datasets and drafts concept docs, a static HTML visualizer that renders any bundle as an interactive graph in one self-contained file with no backend, and three sample bundles. The reference implementation lives at GoogleCloudPlatform/knowledge-catalog/tree/main/okf.

The collision nobody announced

By July 2026 we had two things called graphs:

They look unrelated. They are not. Both are Markdown-and-YAML-shaped, both are file-native, both are git-mergeable, and both describe a system that an agent has to navigate without loading all of it. The distinction between “a node that is a workflow” and “a node that is a document describing a workflow” is thinner than it looks, and at least two shipping projects have already collapsed it.

---

Progressive Disclosure Is the Load-Bearing Idea

Before we get to those projects, we need the mechanic that makes any of it work, because it is the same mechanic in all three of these worlds and it is why agent skills, LLM wikis, and OKF bundles feel so similar in use.

I have argued this at length in the OKF piece, so here is the short version. Context windows are finite, attention degrades long before the window fills, and dumping a directory into a prompt is the single most common way teams waste both. The solution is equally simple to state and surprisingly hard to do well: show the agent enough to decide what to read next, and nothing more.

Compare the three implementations.

Tier by tier, because the parallels here are load-bearing rather than cute.

Always in context. In all three cases, this tier is a catalog of names and one-line purposes, deliberately too thin to act on. Its only job is routing. An OKF root index lists catalogs. A skill frontmatter description says when to use the skill. Neither tells you how to do anything.

Loaded on demand. This is the working tier: the actual content for the one thing you selected. One concept page. One skill body. The cost of this tier scales with decisions made, not with knowledge available, which is the entire point.

Loaded on deeper demand. The long tail. Full API references, provenance chains, edge cases. In OKF this is following outbound links; in skills it is the references/ directory. Most runs never touch this tier, and that is a feature.

The superpowers skill library (Jesse Vincent’s, who publishes as obra, currently 6.2.0) has the sharpest rule I have seen written down about that top tier. From its writing-skills skill, on how to write a description:

“description: Third-person, describes ONLY when to use (NOT what it does) ... Start with ‘Use when...’ to focus on triggering conditions ... NEVER summarize the skill’s process or workflow“

The instruction looks pedantic until you meet the failure it prevents. If the always-loaded tier summarizes the process, the agent will cheerfully act on the summary and never open the file. A partial summary beats no summary in exactly zero cases, because a partial summary is confident. Your top tier has to be useless for execution and excellent for routing. Think of it as a restaurant menu rather than a recipe: enough to choose, nowhere near enough to cook. An identical constraint applies, word for word, to an OKF index.md.

The OKF graph-engineering plugin implements the same idea with an explicit budget instead of a rule of thumb. Its context pack defaults to 2 hops and 20 nodes, and when the neighborhood is bigger than the budget, it does not truncate arbitrarily. From scripts/okf-graph.py in SpillwaveSolutions/okf-plugin (v0.2.0, MIT), here is the ranking that decides what survives the cut:

def score(nid: str) -> tuple:
    c = concepts.get(nid)
    if c is None:
        return (9, 9, 9, nid)
    return (
        0 if nid == target else 1,                 # ①
        0 if c.verified else 1,                    # ②
        0 if c.type in HIGH_IMPACT_TYPES else 1,   # ③
        c.title.lower(),                           # ④
    )

ranked = sorted((n for n in neighborhood if n in concepts), key=score)
included = ranked[: max(1, max_nodes)]                 # ⑤
excluded = [n for n in ranked if n not in included]    # ⑥

① The concept you asked about always sorts first. The pack has a root, and the root is never a casualty of the budget.

② Verified nodes beat unverified ones. Trust is a sort key, not a footnote. A bundle that has been human-checked or CI-checked wins the scarce context slots.

③ High-impact types beat leaf knowledge. In this plugin HIGH_IMPACT_TYPES covers AgentNode, Workflow, Harness, and SharedState, which is to say the harness-shaped nodes outrank the reference-shaped ones when space is tight.

④ Title, alphabetically, as the tiebreaker. Deterministic output matters more than cleverness here: the same query should produce the same pack, so packs can be diffed and cached.

⑤ The budget is applied by slicing the ranked list, so trimming is always “drop the least important,” never “drop whatever BFS visited last.”

⑥ The excluded set is kept and reported, not silently dropped. The pack tells the consumer what it did not include and offers it on request. Silent truncation reads as “that is all there is,” which is the single most dangerous lie a context pack can tell.

The BFS underneath it is outbound-only by default, with a comment in the source explaining exactly why: outbound-only keeps packs inside a theme instead of flooding through hub catalogs that link to everything. Anyone who has watched an agent follow a “see also” link into the entire company wiki will recognize the problem.

/btw

BFS here means Breadth-First Search.

This is the graph traversal algorithm used to collect the neighborhood of a starting concept when building a limited context pack for an agent with the okf-plugin.

How it works in this setting

• -You start at a target node (the concept the agent asked about).

• BFS expands level by level: first the direct neighbors (1 hop), then the neighbors of those neighbors (2 hops), and so on.

• The pack is then ranked and truncated to a budget (the article mentions the default of **2 hops / 20 nodes**).

Why “outbound-only”

The traversal only follows **outgoing** links from each node. It deliberately ignores incoming links.

The hub pages (indexes, “see also” catalogs, overview pages) often have high in-degree. If the search followed incoming links, a single popular hub could pull the entire company wiki into the pack. Outbound-only keeps the expansion thematically contained around the starting concept.

This is a common and practical design choice when doing limited neighborhood expansion on knowledge graphs that contain highly connected catalog or index nodes.

---

Two Systems That Merged the Two Graphs, and One That Explains How They Learn

1. okf-plugin (SpillwaveSolutions), the dual graph made explicit

The okf-graph-eng plugin’s premise is stated in its README in one sentence: OKF already gives you a clean, git-native knowledge graph, and graph engineering is the next layer, treating that same portable graph as the model for agents, workflows, shared state, and decisions.

Concretely, it extends the OKF type vocabulary along two tracks:

• Knowledge types: Dataset, Table, Metric, Playbook, Runbook, API, Reference

• Graph-engineering / harness types: AgentNode, Workflow, Harness, DecisionRecord, SharedState, ToolCapability, TicketLink

And it adds optional typed edges on top of plain Markdown links, so humans keep readable prose links and machines get semantics:

links:
  - target: /agents/researcher.md
    rel: routes_to
  - target: /knowledge/orders.md
    rel: depends_on
  - target: /tickets/mvp-plugin-scaffold.md
    rel: tracks

The rel vocabulary is small and deliberately unglamorous: depends_on, routes_to, implements, documents, uses, owns, supersedes, related_to, tracks, maps_to.

routes_to is the tell. Look at what it is doing there: a control-flow edge, living inside a knowledge-graph file. Once you have that, an OKF bundle stops being documentation about your agents. It becomes a description of your agent graph that happens to be readable by humans, renderable on GitHub, and reviewable in a pull request.

The payoff is impact analysis. Ask the plugin what breaks if you change a concept and it computes both closures, inbound (who depends on this) and outbound (what this depends on), then ranks the result by heuristics that read like an on-call runbook: AgentNode / Workflow / Harness / SharedState rank higher; verified: false on a high-impact type escalates to critical; status: deprecated gets flagged for cleanup but deprioritized for feature work; shallow hop depth with many dependents outranks a deep leaf.

Blast-radius analysis, for your harness. Before you touch the shared-state schema that four agents read, you get the names of the four agents.

The bundle ships as a self-describing sample: sample-okf/ models the plugin itself as both a knowledge graph and an agent graph. It is the compiler-written-in-itself move, and it is the fastest way to understand the format.

2. wiki_ticket_sdd, graph engineering that predates the name

WikiTicket SDD (pronounced “wicked ticket”) is a spec-driven development system built around an append-only, git-native work log. For why spec-driven development matters in the first place, see Why Your AI Coding Sessions Fall Apart at Hour Three. Its own documentation makes a claim that would be insufferable if the code did not back it up:

“WikiTicket SDD is a graph engineering system. Not ‘graph-engineering-adjacent,’ not ‘inspired by’ ... ‘Graph engineering’ just gave a name, in mid-2026, to what bin/ia_graph.py, the event log, and the work taxonomy were already doing since this repo’s first commits.”

WikiTicket SDD was designed based on some of the early harness engineering work where they had basically a todo.jsonl file. I wanted to take that concept and use it, but then be able to map it to existing SDD systems (GSD, Superpowers, SpecKit, etc.) and to ticketing systems like Jira, GitHub Issues, GitLab, Azure DevOps, Amazon CodeCatalyst, and Google Issue Tracker. As well as create artifacts that I could store in Confluence or GitHub Wiki.

The idea was to have a visible workflow where stakeholders could see the milestones, roadmaps, decisions, and ADRs being used to create the project. Thus, keep it all visible as work in progress (WiP), and in systems they’re already used to. Map it onto their existing workflows using Confluence, Jira, GitHub Issues, wikis, Github PRs, GitLab MRs, Azure DevOps (tickets, PRs, etc.), Amazon CodeCatalyst, or Google Issue Tracker. Collaboration and project reporting are all about the visible WiP. Watch me WiP. Watch me. Watch me. I digress, back to graph engineering.

Map the four primitives for Wiki Tickets SDD to the actual code, and the claim holds:

Two details deserve to be pulled out.

The first is trace_check(). It walks the actual edge set looking for work items with no produces, references, or lands-in edge, which in English means: work with no plan, no ticket, or no PR. The repo’s own doc lands the point better than I can: “You can’t run that check against a metaphor.” It is the sharpest available proof that a graph is real rather than decorative. Ask of any “graph” system: what check does it run that would fail if the graph were fake?

The second is the fold. Choosing “append events, derive state” over “mutate rows” is what makes concurrent agents safe. Two agents on two branches both appending to a union-merged JSONL file produce a clean merge. Two agents mutating shared state produce a fight. The choice is written up as an architecture decision record (docs/adr/0001-event-log-fold-union-merge.md), which is itself a node in the graph, which is the joke and also the point.

The surrounding philosophy is what the project calls fishbowl development: use AI as heavily as you like, but the work is never hidden. Keep the WiP visible. Every plan becomes tracked tickets. Roadmaps and status reports are generated artifacts, never hand-edited. No “the agent did a bunch of stuff last week, and nobody knows what.”

One more thing worth respecting: the same document declines to name any single essay as the canonical definition of graph engineering, on the grounds that the framing is an emerging consensus rather than a settled standard. In a field this noisy, a project careful about what it does not claim is telling you something about the rest of its claims.

3. Superpowers, the skill graph

Superpowers is a skill library, not a graph tool, and it belongs in this list anyway, because it is where the learning mechanism is written down. I have covered it twice before, once on the verification discipline it enforces and once on the psychology that makes an LLM actually obey it.

Its writing-skills skill opens with a claim that sounds like a category error and is not:

Writing skills IS Test-Driven Development applied to process documentation.

The mapping is exact:

And the core principle: if you didn’t watch an agent fail without the skill, you don’t know if the skill teaches the right thing.

Look at what that actually is. A learning algorithm. Not a metaphor for one: it has a signal (observed failure), an update (a written node), and a verification step (re-run the scenario). Hold onto it, because it answers the last two questions in this article.

---

The honest caveat, and what landed while I was writing

Two of those three systems are mine, which you should weigh accordingly.

At the time of writing, no one has published a production case study of the merged graph, control flow, and knowledge in one bundle, at organizational scale. The gap is real, and I am not going to paper over it.

What did land, while this piece was in draft, is stranger and more useful: Anthropic shipped both halves separately, in the same season, and did not put them in the same artifact.

The knowledge half is now an official Claude cookbook guide, capabilities/knowledge_graph. The pipeline is four stages: Haiku extracts typed entities and subject-predicate-object triples against a Pydantic schema; Sonnet resolves duplicate entities; the result assembles into a NetworkX graph; queries serialize a two-hop neighborhood back to Claude. Two details are worth stealing outright. First, resolution merges on meaning rather than string distance, using the one-line description the extractor wrote for each entity, which is how it collapses “Edwin Aldrin” and “Buzz Aldrin” into one person despite zero character overlap. Second, the whole thing ships with a hand-labeled gold set and a precision/recall scorer, so you can change one line of the extraction prompt, rerun, and watch the number move.

The control-flow half is Anthropic’s own migration playbook, and it has the numbers this article was missing. Jarred Sumner ported Bun from Zig to Rust: roughly a million lines of Rust in under two weeks, with 100% of Bun’s existing test suite passing in CI before the merge landed, nineteen regressions surfacing afterward and all fixed. Cost: 5.9 billion input tokens and 690 million output tokens, about $165,000 at API pricing. Mike Krieger took a Python codebase to 165,000 lines of TypeScript over a weekend using hundreds of agents, eight phase gates, three adversarial review rounds, and a final parity harness that diffed every command’s output against the Python original.

Read the structure rather than the headline numbers. Work queues, phase gates, adversarial reviewers in separate contexts, a build daemon serializing expensive recompiles, implementers on a smaller model and reviewers on a larger one. Nobody involved called it a graph. It is a graph, drawn in shell scripts.

And the guidance Anthropic gives for it is the sixth operator in the next section, stated better than I state it: let scripts, a compiler, a diff, a test suite, be the referee. Paired with a definition of done that a machine can check without opinion, namely that the output file exists on disk.

Now the part that keeps this honest. Andrew Kelley, who created Zig, called the Bun rewrite unreviewed slop, and his sharpest question is aimed exactly at the anchor:

“The argument for shipping all the million lines of unreviewed code is that the test suite is good enough to catch everything. It’s not sufficient to catch bugs in Zig code, but it is sufficient to catch bugs in [a] million lines of unreviewed slop?”

Kelley has landed the strongest objection to ground-truth anchors anyone has made, and it deserves a straight answer rather than a dismissal. He is right that a test suite calibrated to human-paced change is not automatically calibrated to a million machine-written lines. The anchor does not become stronger because you leaned on it harder. What the Bun case actually shows is that an anchor bounds the blast radius rather than eliminating it: nineteen regressions escaped, were caught, and were fixed. Call it a real answer, and a weaker claim than the marketing around these migrations suggests.

So: both halves are proven at scale, by the same company, in the same season, in two entirely separate artifacts. okf-plugin and WikiTicket SDD remain existence proofs that the merge is clean and cheap at the scale of a repo and a small team. Whether it holds at platform-org scale is still open, and the sensible way to find out is the pilot the early OKF guidance already recommends: twenty to fifty concepts, one owner group, one agent use case, one measurable workflow. If it does not pay for itself at that size, it will not at ten times that size.

How Can a Graph Learn?

This is the question that separates a diagram from a system.

A neural network learns by changing weights. A graph engineering system does not have weights it can touch. It learns by changing its own topology and its own trust annotations, and then persisting that change to disk. Six mechanisms, all of which exist in shipping code today.

1. Add nodes

The simplest mechanism, and the one people underrate. A concept gets authored. A plan gets captured. A skill gets written. In OKF terms: a new file with frontmatter, a body, and links. In WikiTicket terms: a create event appended to the log with a fresh ULID.

The discipline that makes this learning rather than accumulation is that each new node has to be reachable. An orphan node is not knowledge; it is litter, which is why okf-validate reports orphans as a first-class check.

2. Add and retype edges

New nodes are cheap. New edges are where understanding lives, because an edge is a claim about a relationship.

trace_check() is the clean example. It finds missing edges, reports them as gaps, and worklog link / link-pr closes them. The system is telling you what it does not know about its own structure. A learning signal that arrives with a street address beats one that arrives as a vague feeling every time.

Retyping matters just as much. Promoting a vague related_to to a specific depends_on does not add information volume; it adds precision, and precision is what makes impact analysis trustworthy.

3. Decay and refresh trust

This is the mechanism most homegrown knowledge bases skip, and skipping it is why they rot.

The OKF-plugin author skill defines a small provenance vocabulary that does real work downstream:

stale_after is the interesting one, because it means the graph can flag itself as out of date without anyone noticing first. Validation warns on stale nodes and on unverified high-impact nodes (an AgentNode or SharedState with verified: false). And as shown earlier, verified is a sort key in progressive-disclosure packing, so trust does not just get reported in a table. It changes what the agent reads.

A graph that knows which of its own beliefs are unverified is doing something a fine-tuned model cannot do at all.

4. Fold, do not overwrite

Append-only event logs plus per-field last-writer-wins folding mean the graph’s history is never destroyed by an update. You can replay it. You can diff it. Two agents working concurrently merge instead of clobbering.

This is what makes multi-agent learning tractable. If your knowledge substrate is a mutable database, parallel agents are a lock-contention problem. If it is a union-merged event log in git, parallel agents are a merge, and merges are a solved problem.

5. Change structurally, impact first

The okf-plugin‘s change workflow is: run impact, present the ranked dependents, then author the change, then re-validate and re-run impact if the topology moved.

Read that as a learning loop, and it is a gradient check. Before you perturb a node, you compute what the perturbation touches. After you perturb it, you re-measure. A system that always edits first and discovers the blast radius from a production incident is not learning; it is being punished.

6. Anchor to ground truth

Perez’s warning again, because it is the one that kills real deployments: a graph of loops that only reads reports has no contact with reality. The anchors have to be things that cannot be argued with.

Anthropic’s own migration playbook puts it in one line: let scripts, a compiler, a diff, a test suite, be the referee. In WikiTicket, that means a coverage floor enforced in CI (currently >=80% on bin/*.py, targeting 95%), a merge-green policy where PRs merge only when every gate is green and never with --admin, and frozen artifacts: plans, roadmap snapshots, and published status reports are written once and never regenerated, with corrections landing as new documents. In this article’s repo, it is the same instinct: task ci must exit zero before any commit, and the CI workflow runs exactly task ci so local and remote cannot diverge.

Without anchors, every one of the previous five mechanisms will happily converge on a beautifully linked, fully verified, entirely wrong graph.

---

How Can an Agent Improve and Learn?

Now put the two halves together, because “how does a graph learn” and “how does an agent learn” turn out to be the same question asked from different ends.

An agent has five places to put a lesson, and they differ in how long the lesson survives.

The rows are worth walking, because almost every “my agent keeps making the same mistake” complaint is a lesson filed one row too high.

Within a turn. Reasoning. Genuinely useful and entirely disposable. Nothing you learn here survives, and treating it as learning is the root of the “but we already discussed this” frustration.

Within a session. This is the loop’s territory: maker/checker results, tool outputs, sub-agent reports. It survives as long as the loop does. Loop engineering is largely the craft of deciding what from this row deserves promotion to the next one.

Across sessions, one person. Memory files and personal skills. I broke the persistence layers down individually in Claude Code Memory and the Five Layers That Fix It. This is the first row where the lesson is a file, and therefore the first row where it is real. It is also where most people stop, which is why their teammates get none of it.

Across sessions, one repo. Skills, captured plans, decision records, an OKF bundle. Checked into git, reviewed in PRs, validated in CI. A lesson filed here is subject to the same quality gates as code, which is exactly the point.

Across the team. The wiki and the tracker. WikiTicket’s ticket-sync and wiki-publish skills push work items and generated docs into whatever system the team already uses (GitHub, GitLab, Jira, Azure DevOps, Confluence, Linear, and other as a first-class option), deliberately keeping per-system code out of the core.

The actual learning algorithm

Superpowers already gave it to us. Generalized past skill-writing, it is four steps:

Anthropic’s migration playbook arrived at the same rule from a completely different direction, and states it as an operational policy: a rule violation triggers regeneration rather than a per-file patch. See the same mistake in a third file, and you do not hand-fix three files. You add one sentence to the rulebook and rerun the batch. You are not fixing the code. You are fixing the process that produced the code, which is the only version of the fix that survives contact with the next batch.

Same instinct as writing the node instead of correcting the agent in chat. Two teams, two problem domains, one conclusion.

1. Observe a real failure. Not a hypothetical. Watch the agent do the wrong thing without the guidance, and write down the exact rationalization it used.

2. Write the smallest node that addresses that specific failure. A skill, an OKF concept, an ADR, a rule. Scoped to the observed failure, not to the general topic.

3. Wire it in. Give it a description that routes correctly and links that make it reachable. An unreachable lesson has not been learned; it has been filed.

4. Verify, then close the loopholes. Re-run the scenario. Where the agent finds a new gap in the wording, that gap is the next test case.

RED, GREEN, REFACTOR, applied to the knowledge graph instead of the codebase.

Two failure modes are worth naming explicitly, because both are common and both feel productive.

If you want the practical version of authoring and tuning these, I wrote How to Build, Evaluate, and Tune AI Agent Skills.

Writing skills nobody triggers. A perfect document with a description that never matches the situation is dead weight that costs context on every single run. The routing tier is not a summary; it is an index, and it is the part to test hardest.

Learning without anchors. An agent that writes a lesson, verifies it against its own reasoning, and files it as verified: true has learned nothing except how to agree with itself. Verification has to come from outside: a passing test, a green CI run, a human review, a working deploy.

When a graph is the wrong shape

Everything above has a cost, and it is worth naming the cases where you should not pay it.

Skip the graph when the task is genuinely one-off, when you do not yet know the shape of the work, or, most importantly, when there is no mechanical way to judge whether the output is correct. The last one is disqualifying rather than merely inconvenient. A graph without an anchor is an org chart for a committee that cannot tell whether it is winning.

In all three cases, a loop is still the right tool, and reaching for topology early buys you structure you will have to throw away once you learn what the work actually looks like. The graph earns its setup cost at exactly the point where the same shape of work repeats at scale, and a machine can tell right from wrong. Before that point you are guessing at a topology; after it you are amortizing one.

Anthropic’s own playbook encodes the same priority by ordering: build the mechanical judge first, and do no agent work until you have one.

What this looks like on Monday

Those five steps from the top of the piece, now that you know why each one earns its place:

1. Pick one repo. Add a directory of Markdown files, one concept per file, type in the frontmatter, links between them. Congratulations, you have a valid OKF bundle, and it took ten minutes.

2. Add a root index.md that lists what exists and nothing more. Your routing tier is done.

3. Add a log.md. Append one line per change. Your history is done.

4. The next time an agent does something wrong in a way it will repeat, write the node instead of correcting it in chat.

5. When you have enough nodes that you cannot hold the shape in your head, add impact analysis before you edit high-degree ones.

Every one of those steps is boring, file-based, and git-native, which is exactly why they compound.

---

The Bottom Line

The term arrived as a tweet and got over-marketed within a week, and it still named something real. The layers stack cleanly: the harness builds the machine, the loop makes it converge, and the graph decides who talks to whom.

But the more useful observation is the one that got buried under the July noise. The control-flow graph the agent community named and the knowledge graph that Karpathy sketched and Google standardized are the same shape, in the same format, in the same repository. routes_to and depends_on are both just links in a Markdown file. Once you accept that, your agent topology becomes a reviewable artifact, your documentation becomes executable routing, and your context packs get to be small because the graph knows what matters.

And that is when the interesting question stops being “how do I orchestrate agents” and becomes “how does this thing get smarter every week.” The answer is unglamorous: new nodes, better edges, honest trust annotations, an append-only history, impact analysis before surgery, and at least one measurement that cannot be argued with.

The model is the CPU. The harness is the OS. The loop is the scheduler. The graph is the filesystem, and the filesystem is the only part that remembers.

---

Next in this series

This piece is the map. The next one is the build: standing up a dual graph in practice, OKF concepts plus AgentNode and Workflow types in one bundle, wired to a real agent, and then the harder question of whether it measurably improves reliability or just feels tidier. I will publish the bundle, the typed-edge vocabulary, and the numbers, including the ones that do not flatter the thesis.

---

If you are a paid subscriber, thank you. Your support makes this work possible.

If you are a free subscriber and find these articles useful, please consider upgrading. A paid subscription is $80 per year or $8 per month.

Free subscribers typically receive access to the full versions of paid articles after one to two months.