A task ledger for AI coding agents
The small central list I use to coordinate a long build, with the details kept in individual task documents.
Published 2026-08-30
Loading content...
The small central list I use to coordinate a long build, with the details kept in individual task documents.
My ledger keeps a task's name, state, and documentation link in one central list. Workers take a ready item, follow its spec, verify the result, and leave enough evidence for the next session to continue.
I like a boring task list. Once the project has usable task documentation, the central list doesn't need to explain the whole product again. It needs to tell the next worker where to start.
My preferred version is a ledger with the task name, its state, and a pointer to the task document. The details live behind the pointer. Dependencies, acceptance checks, design references, and implementation notes don't all need columns in the ledger.
Here's a small illustrative version. These are example tasks, not a record of a particular build:
| Task | State | Document |
|---|---|---|
| 041: Save a local world | done | docs/items/041.md |
| 042: Reopen a saved world | ready | docs/items/042.md |
| 043: Show the world picker | drafting | docs/items/043.md |
The number gives the task a stable identity even if I change its title. A commit can refer to 042, and the next agent can find the spec without searching through several chats.
The exact words aren't important, but they need a shared definition. In one of my projects, doc means the item is documented and ready for implementation. It doesn't mean the documentation still needs writing.
For a new ledger, I'd make the states explicit:
drafting: the spec or its review is incomplete.ready: the spec is usable and the dependencies are satisfied.active: a worker has claimed it.done: the required checks passed and the result is recorded.blocked: a named dependency or decision prevents progress.skip: intentionally left unfinished, with a reason in the task document.Those are proposed names, not a translation table for every existing project. If a repo already uses a smaller vocabulary, I can keep it and write down the meaning.
In the project where both the ledger and the item doc contain a status, the worker has to update both. That duplication is manageable, but it is still duplication. If they disagree, a new worker should inspect the evidence and reconcile them before starting work.
For the hypothetical saved-world item, the document might look like this:
# 042: Reopen a saved world
status: ready
Source: PRD / saved worlds
Depends on: 041
Behavior:
After a reload, opening an existing world restores the blocks the
player changed. Opening it must not overwrite the saved version.
Acceptance:
Create a world, change a known block, save, reload, reopen the same
world, and inspect that exact block. Confirm the saved data survives.
Evidence:
Record the tested revision, steps, result, and any remaining limitation.
An implementation agent still needs to inspect the real save code. The spec tells it what success looks like and which product behavior it must preserve. It shouldn't need the original conversation to discover why saving matters.
The first task should be small enough to exercise this entire process. If I can't review the result or tell whether it passed, splitting the work further is probably useful.
The loop can read the next ready item, implement it, run its checks, record the result, and continue. It may do several items in one session, but each item still gets its own verification and handoff.
When a session ends, another can load the ledger and the relevant files. The product decisions live in the repo. I don't need to preserve the exact chat which produced the previous commit.
I also want failure to leave a useful record. A blocked item should say what prevented progress and what would unblock it. Otherwise the next pass can spend the same time rediscovering the same problem.
The ledger can support several workers, but a Markdown table doesn't provide locking. Two workers can read the same ready row before either writes active.
A simple arrangement is to have one coordinator assign different items before starting the workers. Separate worktrees help isolate their code changes, and the integration step still needs checks. If workers claim tasks dynamically, the claim needs a serialized mechanism, such as a single assigning process or a tracker which supports an atomic claim. Writing a name into a file after the fact isn't one.
Independent tasks make parallel work easier. If two items both change the same shared interface, completing one first may be quicker than resolving the overlap later. More workers don't remove dependencies.
I've also used agents sharing a working tree and branch. It requires much more care around staging and commits because one agent's files are immediately visible to the other. I wouldn't make shared-tree staging machinery a prerequisite for someone's first ledger.
For a defined feature, an empty ledger is a sensible stopping point. For an ongoing product, I may authorize a worker to inspect the current build, identify the next problem, and write a spec before implementing it.
Those are different amounts of authority. I want the loop instructions to say which applies, including any time or spending limit. "Keep going" is useful when the direction is clear. It isn't a substitute for choosing what I want built.
I'd start with a handful of tasks and one worker. After the first verified item, I can check whether the spec contained enough information and whether the evidence makes sense, then adjust the next item before running the rest.