Taskgraph: Claude Code skill for AI agent status maps

Taskgraph is a Claude Code skill, built at AR Labs, for answering "where does this piece of work stand, and what happens next?" when AI agents are doing much of the work. It tells the agent coordinating the work, the orchestrator, how to draw a map of one branch of a task graph (all tracked tasks and the dependencies between them), check it against the real state of the tracker and the code, and keep it current while the project owner rules on what should happen next. The map shows what is finished and where its code landed, what is in flight, the next steps in order, and every decision that waits for a person. It is for anyone steering a build that coding agents carry out. The program that reads the graph and draws the page is described on the Taskgraph project page; this page covers the procedure an agent follows to use it.

The task graph is held in Beads, Steve Yegge's open-source issue tracker for coding agents. Each tracked task is a bead, and beads form a tree of parents and children with dependency edges between them; an edge says one bead must finish before another can start. A map shows one parent bead, the root, and everything under it. Each map also has an overlay, a small file holding what the tracker does not yet record: proposed edges, open decisions, items judged independent, and which agent session works the branch. The practice behind it is described in task graphs with Beads.

How it works

The skill has four branches, chosen by what the owner asks for.

Draw the map. Run the generator on the root. On a first map, fill the overlay before going further, then draw a fresh layout. Before reporting anything, check the page against live state: read the beads its summary names, and where the work lands in a code repository, fetch that repository and look at its pull requests. Then look at the rendered page itself. The report leads with what changed since the last view, then the next step and the numbered steps after it, then the decisions waiting for the owner.

Sequencing pass. For items with no dependency recorded, propose edges, each with a one-sentence reason and a confidence, and write them into the overlay rather than into the tracker. When the only reason for an edge is that two items edit the same files, the proposal says so ("write conflict"). Items with no dependency are listed as independent, with a reason. The pass is written up beside the map, lowest-confidence edges first, and is done when every open item has an edge, is listed as independent, or waits on a named decision.

The loop. The owner rules on the proposals. An approved edge is written to the tracker with a dated note giving its reason and confidence; a rejected one is removed; a decision is recorded on its bead. The map is redrawn after every ruling, and the numbered steps are handed, with the facts they rest on, to whichever session does the work.

Choosing the next view. When only a handful of items remain under the root, or the owner's next priority sits outside it, the skill steps up a level, maps the parent, and runs a sequencing pass on its top layer. Every map is kept as a record.

The judgement it encodes

Most of these rules were written down during the pilot, when we first used the map to steer a live build.

Every claim is checked this turn. Other sessions and the owner move beads between views, so the skill redraws and re-reads before each report, and repeats nothing it did not verify against the tracker or git in the same turn.

Landings are proved from git. A bead counts as landed when a pull request's merge commit, a delivery record or a commit naming the bead shows it, not because its status says closed. A branch merged and then deleted still shows as history.

Finished work stays on the map while its process is unfinished. Completed steps are part of the explanation of where things stand.

The layout is kept. A status change restyles a card in place and cards keep their positions, so the owner's eye can follow the map from one view to the next. A fresh layout happens only when the owner asks or the root changes.

NEXT has one definition. The next step is the owner's stated focus when one is set, even outside the root; otherwise it is the ready item at the head of the longest remaining chain. An item held back by an undecided proposal is not ready.

Proposals resolve three ways. Written to the tracker; satisfied, because the earlier end finished first; or moot, because the later end finished without it. Only open, undecided proposals hold an item back.

Steps and decisions are separate lists. The numbered steps match badges on the cards. Decisions are listed apart, each naming the step it blocks, so a decision is never counted as a step.

Drawing the map corrects the graph. Every gap the picture shows, such as an unassessed item, an undecided proposal or a step nobody owns, becomes either a question for the owner or an edge to write.

What exists today

The skill drives a prototype generator that reads the tracker and git and never writes to either; only the loop, after the owner approves, writes edges. A first proper version of the generator, with tests and its own repository, is being built as the Taskgraph project and will replace the prototype.

Example

Illustrative example. The opening of a report after redrawing a map:

Since the last view: the voice-turn slice merged (a commit on main
names its bead); the transcript-export slice moved to review.
 
NEXT: 3. Wire the export button to the new endpoint.
Then 4. Add the empty-transcript state; 5. Remove the old exporter.
 
Decisions for you:
- Proposal P7: should step 5 wait for step 4? Reason: write
  conflict only (both edit export.ts). Confidence: medium.
  Affects step 5.
 
Map: maps/<root>/map.html