The Work Graph Playbook

The morning your agent forgot everything

You closed the laptop on Friday with an agent halfway through a job. On Monday you open a fresh session and it knows nothing. Not what it finished. Not what it was about to do. Not the thing it discovered on Friday that made the original plan wrong.

So you explain it again. You paste the plan back in. It starts work that is already done, or it starts work that cannot be done yet because something else has to land first, and you only find that out after it has written the code.

Steve Yegge, who built the tool most of this playbook draws on, described the same thing with a blunter word.

That is the whole problem in one sentence. All they know is what is on disk, plus what you just told them. Everything else died with the last session.

The instinct is to fix this with a bigger context window. It does not work, and the reason is arithmetic. IBM put it plainly in the most watched talk in our source set.

A ceiling is a ceiling no matter how high you raise it. And the same talk names the real shape of the problem, which is not storage at all.

Why a to-do list does not fix it

Most people reach for a plan file. A PLAN.md, a checklist, a markdown to-do list the agent reads at the start of every session. This is better than nothing and it is where almost everyone starts. It also stops working quickly, for three reasons that have nothing to do with the file format.

A list has no order that means anything. Ten unchecked boxes look identical. Nothing in the file says that box seven cannot start until box three lands.

A list has no links. When box three turns out to be impossible, nothing tells you that boxes seven, nine and twelve just became impossible too.

A list grows. It does not shrink, because nothing computes what is finished and removes it.

The failure mode at the end of that road is not a missing file. It is too many files.

Two hundred and fifty six planning documents is not a memory system. It is a landfill. The agent cannot read them all, so it reads the ones you point at, which means you are back to being the memory.

What a work graph is, in ten words

Durable tasks, linked by dependency, that outlive the agent's session.

That is the whole idea. Three properties, and each one is load bearing.

• Durable. It lives in a file or a database, not in the conversation. Close the session, the graph is still there.
• Linked by dependency. Tasks point at the tasks that block them. This is the part a list cannot do.
• Queryable. Because the links exist, a machine can compute which tasks are unblocked right now. Nobody has to remember.

Once those three hold, a question that used to require judgment becomes a query. "What should I work on next" stops being something the agent reasons about from a half remembered plan, and becomes something it looks up.

What it is not

Three different things get called a work graph. Only one of them is this.

The tell is simple. If it dies when the session ends, it is not a work graph. If it was fully written before any work started, it is a pipeline, not a work graph.

The promise, from the people who built it

Here is what the practitioners say changes. Read these as claims, not as proof. We test them against our own data later on this page.

The second claim is about what stops being your job once the graph exists.

And the third is about scale, which is where the dependency links start paying for themselves.

Nodes, edges, states

A work graph needs three things and nothing else. Everything a tool adds on top is convenience.

A node is one piece of work. It needs an id, a title, and a state. Everything else is optional. If a node cannot be finished in one sitting, it is too big and should be split, because the point of the graph is that a session can pick a node up and put it down.

An edge says one node blocks another. This is the only edge type you truly need. Most systems add a parent link so work can nest, and that is worth having, but blocking is the one that does the scheduling.

A state says where the node is. Open, claimed, closed. Three is enough. Add more only when you can name the query that needs them.

What that looks like in real data

Below is one real node from our own graph, drawn from the export this page is built on. It is a single piece of work blocked by 18 other nodes. Three of them are finished, one is running, and the rest have not started. Because fourteen blockers are still open, this node is not ready, and no agent should pick it up. That verdict is computed, not remembered.

The ready query is the whole point

Everything above exists to support one operation. Given the graph, return the nodes that are open and have no open blockers. That set is the ready work.

# the entire idea, in one line of logic
ready(graph) = { n in graph : n.state == open
                        and no b in blockers(n) has b.state != closed }

This is worth dwelling on, because it is the part people skip. The ready query replaces a judgment with a lookup. Before it exists, "what should I do next" is answered by an agent reasoning over a plan it partly remembers. After it exists, the answer is computed from durable state, and it is the same answer whichever agent asks, at whatever hour, in whatever session.

That single change is what makes the rest possible. An agent that can ask for ready work does not need to be told where it left off. It does not need the plan re-pasted. It does not need you.

The same query in three substrates

A work graph is not a product. It is a shape. Here is the identical ready query in three completely different storage layers, from the smallest thing that works to a real database. Pick the one that matches your scale, and know that you can move between them because the shape does not change.

Markdown and grep, for one person and one agent

Nodes are lines in a file. Blocking is a field. This is genuinely enough to start, needs no install, and is readable by any harness in existence.

# tasks.md, one node per line
- [ ] wg-1  set up staging DNS            blocks:
- [ ] wg-2  deploy the API                blocks: wg-1
- [x] wg-3  write the schema              blocks:
- [ ] wg-4  point the client at staging   blocks: wg-2 wg-1

# ready work: open nodes whose blockers are all closed
closed=$(grep -o '^- \[x\] [a-z0-9-]*' tasks.md | awk '{print $3}')
grep '^- \[ \]' tasks.md | while read -r line; do
  blockers=$(echo "$line" | sed -n 's/.*blocks:\(.*\)/\1/p')
  ready=1
  for b in $(echo "$blockers"); do
    echo "$closed" | grep -qx "$b" || ready=0
  done
  [ "$ready" = 1 ] && echo "$line"
done

SQLite, when the graph outgrows one file

Two tables. The ready query becomes a single statement, and it stays correct at any size.

CREATE TABLE node (id TEXT PRIMARY KEY, title TEXT, state TEXT, priority INT);
CREATE TABLE edge (node TEXT, blocked_by TEXT);

-- ready work
SELECT n.id, n.title FROM node n
WHERE n.state = 'open'
  AND NOT EXISTS (
    SELECT 1 FROM edge e JOIN node b ON b.id = e.blocked_by
    WHERE e.node = n.id AND b.state != 'closed'
  )
ORDER BY n.priority;

A purpose built tool, when agents write to it concurrently

This is where a real implementation earns its keep, because two agents claiming the same node at the same moment is a genuine race and you do not want to solve that yourself.

bd ready                 # open work with no active blockers
bd create "deploy the API" -p 1
bd dep add wg-4 wg-2       # wg-4 is blocked by wg-2
bd update wg-2 --claim     # atomic: only one agent wins
bd update wg-2 --status closed

Same graph, same query, three substrates. Nothing above is specific to one vendor, one language, or one agent harness. That is the property that makes this worth learning rather than buying.

Why the graph lives outside the harness

The single most important design decision is also the least discussed: the graph must not live inside the agent. Not in its context. Not in its scratchpad. Not in a session file the tool manages for you.

The reason is that everything inside the harness is scoped to a run. When the run ends, it goes. A developer building agent workflows put the rule about as plainly as it can be put.

There is a real board somewhere. That is the test. If you cannot point at the file or the table that holds the graph, and open it without the agent running, then the graph is not durable and you will lose it.

Putting it outside buys four things at once:

• It survives the session. The obvious one, and the reason you started.
• It survives the tool. Switch harness next quarter and the graph comes with you.
• It can be read by things that are not agents. A script, a dashboard, a person on a Sunday.
• It can be version controlled. Which turns the history of the work into a diff you can read.

Any harness

Because the graph sits outside, the harness becomes a detail. Any agent runner that can execute a shell command or read a file can use the same graph, and they can use it at the same time.

The instruction you write is nearly identical in every case, which is the point. You are not integrating with a harness. You are leaving a file where any of them can find it.

Set one up in ten minutes

You do not need to install anything to start. Do this in the next ten minutes and you will have a working graph.

1. Make the file. One line per task. Give every line an id, a state box, a title, and a blocks field. That is it.
2. Write down five real tasks from whatever you are actually doing this week. Not example tasks.
3. Add the blockers you already know about. There are usually fewer than you think, and finding there are none is itself information.
4. Write the ready query as a one line script and run it. If the answer looks wrong, your blockers are wrong, which is exactly what you wanted to discover.
5. Tell your agent about it in whatever file it reads at startup. Two sentences: where the graph is, and that it must ask for ready work before starting and close the node when done.

The starter graph and a script that measures the health of any graph are on the companion page.

Open the work graph template, which carries a copyable starter graph and the scorecard script described below.

Our own 140 days, measured

We have run a work graph in one working repository since 2026-04-13. As of 2026-08-31 it holds 1,328 nodes, 191 dependency edges and 2,503 recorded events across 140 days. Of those nodes, 797 are open, 514 are closed and 16 are in progress.

That is the flattering paragraph. Here is the rest of it.

We ran a work graph for 140 days and used it as a list.

What those six numbers actually say

The graph is barely a graph. 84.5 percent of our nodes have no edge at all. We have 175 blocking edges and 16 parent links across 1,328 nodes. We built the dependency structure for the work we thought was complicated and skipped it everywhere else, which means for most of the graph the ready query returns the same thing a plain list would.

The median node closes in 42 minutes. That is not a victory lap. A node that is created and closed inside an hour was mostly a note being written down after the fact, not a piece of work scheduled ahead of time. The graph was recording history more often than it was directing traffic.

We create far faster than we close. In 2026-08 we opened 643 nodes and closed 173.

And the backlog is aging. Median open age 26 days, with 325 nodes past 30 days, 150 past 60 and 34 past 90. Alongside 39 open items at top priority, that is a system recording intent faster than it retires it.

We are publishing this because the alternative is a playbook that tells you how well this works while quietly not measuring whether it worked for us. The doctrine on this page is sound and our practice of it was mediocre. Both things are true, and only one of them is usually printed.

Six ways it goes wrong

Each failure below is tied to one measure, so you can detect it in your own data instead of guessing. Our reading of our own graph is in the last column.

Five of six are present in our own graph. We are not writing that from humility. It is what the script returned, and we would rather print it than publish a playbook that cannot survive being pointed at its author.

Two of these have independent confirmation from people running many agents at once. Version drift is a real operational cost:

And the reason a shared durable graph beats having agents talk to each other:

Run the scorecard on your own graph

The six numbers above are not our opinion of our graph. They come from a script, and the script works on any task system that can export its nodes and edges as JSONL. It does not require the tool we happen to use.

Take it, run it, and you get the same six measures for your own work, computed the same way, so your numbers are comparable to ours.

# works on any export with one JSON object per line
node measure-our-graph.cjs --issues nodes.jsonl --deps edges.jsonl

# field names different? map them, no code changes needed
node measure-our-graph.cjs --issues jira.jsonl --deps links.jsonl \
  --map id=key --map status=state --map created_at=createdDate \
  --map closed_at=resolutionDate --map depends_on_id=blockedBy

The six measures, defined precisely

Definitions matter more than the numbers. If yours are computed differently, the comparison is worthless.

The healthy column is a judgment, not a measurement, and we are stating it as ours rather than as a standard. The definitions are the part that has to be exact.

When a work graph is the wrong tool

This page argues for a thing, so it owes you the cases where the thing is a mistake.

• Short work. If the job finishes inside one session, the graph is pure overhead. You will spend longer describing the work than doing it.
• Genuinely unknown work. Early exploration has no dependency structure yet because you do not know what the pieces are. Explore first, then write the graph from what you learned.
• Work with no real blockers. If your tasks are truly independent, a list is the correct tool and the graph adds ceremony for nothing. Our own edge density suggests this is more common than people admit.
• One person, one thread, good memory. The graph pays off when memory is the bottleneck. If it is not yours, it may not be a bottleneck at all.
• As a substitute for deciding. A graph will happily hold 797 open nodes and tell you which are ready. It will not tell you which ones deserve to exist. That judgment stays yours, and our backlog is the evidence of what happens when you skip it.

There is also a real cost that shows up once several agents write to the same graph. Yegge, talking about the security side of agent systems, named the tradeoff that applies here too.

Where this sits beside the Hive Mind playbook

We have written about agent memory before, and the two playbooks solve different halves of the same problem. Reading them in the wrong order will waste your time, so here is the split.

They compose. The brain holds the knowledge, the graph holds the queue, and neither one substitutes for the other. Read the Hive Mind Playbook for the knowledge half.

Sources, and what we could not reach

Every quote on this page was verified verbatim against the video's own caption track by a script before it was allowed on the page. 50 quotes were proposed, 40 passed, and the rest were discarded for being paraphrased, merged across a speaker turn, or silently corrected. Timestamps in the citations link directly to the moment in the video.

The video corpus

We fetched and screened 26 talks and kept 13 across 12 channels and 614 minutes of runtime. A video was kept only if its transcript carried at least five deduplicated mentions of work graph language, and only if it had at least a thousand views, because a talk nobody watched is not evidence of practice.

Reddit, and why there is none of it here

This playbook was commissioned with Reddit as a named source. There is no Reddit on this page, and rather than quietly drop the requirement we are showing the work. On 2026-09-06 we ran every route we could think of. 11 routes, no usable content. The table below is generated by a script that re-runs the probes, so it reports what happened rather than what we remember happening.

One route deserves a fair hearing. The third party archive answers normally and returns real data, so calling it blocked would be wrong. Its index simply stops at 2025-05-19, several months before the tools this playbook is about existed. It is reachable and empty on this subject, which is a different thing from being blocked.

Everything else

• github.com/steveyegge/beads, the reference implementation, open sourced October 2025.
• Our own work graph export, 1,328 nodes and 191 edges, measured by measure-our-graph.cjs on 2026‑08‑31.
• The Hive Mind Playbook, the knowledge half of the same problem.
• The work graph template, carrying the starter graph and the scorecard script.