By Matija, the developer behind Build with Matija. In October 2026 I built five products and internal tools with one orchestrating agent handing numbered tasks to worker agents, each in its own git worktree. This article is written from the ledgers, task files, run reports and commit history of those five repositories. Models: Claude Opus 5.5 as orchestrator, Sonnet 5.5 and Haiku 5.5 as workers. Last updated 2026-10-26.
To run several coding agents in parallel on one codebase, put the coordination in a file the agents read and write: a task ledger in the repository. Each row names one task, what it depends on, the exact check that proves it is done, the folders it may touch and its status. An orchestrating agent claims rows for workers, each worker builds its task in its own worktree and writes a run report, and every open question becomes a numbered decision with a recorded answer. Coordination then survives a closed chat, a crashed session and a fresh model, because the state lives in Git. I used this pattern across five repositories in one week. Below is the ledger format, the split of roles between me, the orchestrator and the workers, the run report that serves as the handoff, and the failures that only appeared once many agents ran at the same time: a full disk, a host load average of 90, and decision numbers that collided.
Why chat stops working as the coordination layer
With one agent, the chat is the plan. You say what you want, it works, you correct it. Once three or four agents work at the same time, the plan has to exist somewhere all of them can see, and it has to outlive each session. A worker that starts an hour later needs to know which tasks are taken, which are blocked, and what was decided while it was not running.
I described the limit from the hardware side in my remote development workstation article: the constraint is how many agents I can supervise. A ledger raises that ceiling, because my supervision moves to reviewing records: claimed rows, run reports and decisions waiting for me.
The five repositories where I ran this in October:
The format got more structured with each repository, and the repositories copied from each other on purpose. Attest settled its stack "from async-discovery and meeting-kb". Sedule's task script came "from Attest with key BM". Docket's UI tasks cite a reference report written from Sedule's front end. That chain is part of the story: a ledger makes reuse explicit, because the next project can copy the tooling and the rules along with the code.
What a ledger row contains
Docket's UI ledger is the most complete version, so I will use it as the reference. Every task is one row in a Markdown table in docs/implementation/ui-ledger.md:
text
// File: docs/implementation/ui-ledger.md (one row, trimmed)
| ID | Task | Depends on | Exit criterion | Sources | Status | Notes |
| U25 | Forgotten password: /auth/forgot-password (always the same
"if an account exists, we sent a link" answer) and
/auth/reset-password?token= (new password and confirm;
invalid or expired token copy; success → sign-in)
| U20, U19
| Playwright (mock): request, reset, sign in with the new
password, expired token
| U06, B2
| done
| Lane: apps/web/src/features/auth/reset/; 2026-10-26: host disk
full (ENOSPC), nothing built; re-run attempt 2; merged af9d5f3,
report: runs/U25.md; DW-U25-1..3 → U19b |
Each column does a specific job for an agent that arrives with no memory.
Depends on decides when a task may start. A worker never has to judge whether the sign-in layout exists yet; the row says U25 waits for U20.
Exit criterion is the single most important field. It names the check that ends the task, written so a worker can run it and paste the output. "Playwright (mock): request, reset, sign in with the new password, expired token" leaves no room to declare victory after a typecheck. Recount's tasks call the same field "done when", and one commit message records the lesson behind it: "sharpen done-when after the first attempt".
Sources points at the specification the task implements, so the worker reads the contract before it touches neighbouring code.
Lane lists the folders the task may change. The ledger states the rule once: feature tasks touch only their own src/features/<feature>/ and e2e/<feature>/ folders. Lanes are what make parallel work safe. Two workers whose lanes do not overlap cannot produce a merge conflict in each other's files.
Status uses a small fixed vocabulary: todo, doing with the date and branch, done with the merge commit and a link to the report, blocked with a reason, dropped with the decision that dropped it.
Sedule keeps one file per task, with the same information in front matter. This is a real one, created after I reviewed the deployed UI:
markdown
<!-- File: work/tasks/BM-134.md -->
---
id: BM-134
title: Compact /app actions with Lucide icons
status: planned
priority: 3
who: agent
area: web
depends_on: []
created: 2026-10-24
---
## Done when
Across apps/app, action buttons use lucide-react icons: icon-only
(shadcn Button size icon / icon-sm) with a Tooltip and aria-label
for common row and toolbar actions, and icon plus short label for
primary actions; no hand-made components; app:check and lint pass
## Notes
model: haiku (effort high)
Owner request 2026-10-24 after reviewing the deployed UI.
## Log
- 2026-10-24 created
When a worker claims it, the file gains started, branch: worktree-agent-<id> and a log line, and on completion a completed date and a one-line summary of what changed and which checks passed. The who field separates agent tasks from owner tasks, and the model line chooses the worker model per task. More on that below.
Waves: let a script decide what runs in parallel
Dependencies make the ledger a graph, and a graph can be sorted into waves: sets of tasks with no dependencies between them. Docket's ledger has a section that a script regenerates on every change, marked "Generated by ledger.py waves --write. Do not edit by hand":
The orchestrator reads the current wave, claims as many rows as it has workers for, and starts them. Nobody hand-plans the parallelism. The last line matters as much as the others: owner tasks sit on their own gated track, so a worker never waits silently on something only I can do.
Sedule's planning pull request tested the graph before any code existed: "A simulated run of the ledger (tasks marked done wave by wave in a throwaway copy) reaches 42 of 51 tasks with only BM-1 done by the owner, and all agent tasks once DNS (BM-2) and Brevo (BM-3) are done." That one sentence told me before the build started exactly which of my own tasks would unblock the rest.
Three roles: owner, orchestrator, workers
The ledger only works if everyone knows who writes which part of it.
The commit history shows the split directly. In Docket, the ledger commits ("ledger: claim U43", "ledger: done U25; add and claim U19b") are co-authored by Opus, and the feature commits and run reports for tasks such as U21 and U25 are co-authored by Haiku. Sedule's planning pull request describes "an Opus 5.5 orchestrator launching Sonnet 5.5 workers" through three repository skills: next-task, spawn-worker and project-status. A day later Sedule's UI plan switched UI tasks to Haiku workers, and each task file states the model and effort it should run with.
Choosing the model per task is cheap once the task is specified this tightly. A row with a named lane, a contract to read and a Playwright exit criterion leaves little to interpret, which is where a smaller model does well. Planning, decisions and merges stay with the larger model because they need judgment across the whole graph.
Worktrees, lanes and one rule for pushing
Each worker runs in its own git worktree on its own branch. Sedule's task files record branches such as worktree-agent-a9262a78ea0e747fa; Docket uses readable names such as ledger/U41-projects. The worktree gives each worker its own checkout, its own node_modules and its own test containers (Docket's journeys run with DOCKET_TEST_CONTAINER_PREFIX=U25, so parallel test databases do not collide).
Merging needs a rule every agent follows the same way. Attest's agent instructions settled it on 23 October:
markdown
<!-- File: AGENTS.md (Attest, Shipping section, excerpt) -->
- "Push", "push to main" and "deploy" all mean the same thing:
merge the work into local main, rebase, and push main to origin.
- Never push any branch other than main. No feature, task, worktree
or claude/* branch ever goes to origin. Branches and worktrees stay
local and are merged into local main before the push.
- When a task's checks pass, do the above. Do not batch finished work.
That is where an agent's job ends: the owner builds and deploys main
in Coolify.
This keeps the remote clean while dozens of short-lived branches come and go, and it gives the worker one unambiguous end state. It is the parallel version of the commit-to-main habit I described in commits versus branches for a solo AI developer: branches are still sandboxes, and with several workers each sandbox lives in its own worktree.
The run report is the handoff
A finished task leaves a report at docs/implementation/runs/<ID>.md. This is the document I actually read, and the one the next worker reads when a task builds on it. The structure that settled in Docket:
markdown
<!-- File: docs/implementation/runs/U25.md (structure, trimmed) -->
# U25: Forgotten password-**Status:** done
-**Attempt:** 2 (attempt 1 stopped on ENOSPC before any code was written)
-**Branch / commits:** ledger/U25-reset, 0e47dd4
-**Date:** 2026-10-26
## Outcome
Measured against the exit criterion: met, mock mode. 5 of 5 journeys pass.
Not verified in the browser: the sign-in step (see D-U25-5 and F1).
## Verification
The exact commands and their output: web:check, the journeys,
the real-mode auth journeys re-run because routes changed, root check.
D-U25-1 … D-U25-5, each with its source and whether it was delegated.
F1 …, DW-U25-1 … (each becomes a follow-up row or a note on an existing one)
Three parts of this format earned their place.
Outcome against the exit criterion, including what was not verified. The U25 report says plainly that one step was not checked in the browser and why. A report that lists its own gaps tells me exactly where to look.
Verification as pasted output. The report quotes the commands and their results, down to "check-production-build: .../apps/web/dist holds no MSW or mock code" and "tests 571, pass 571". It also records a failure that was not the task's: a first root check failed ten server tests while the host was overloaded, and the same tests passed on the rerun. The worker explained it and showed that its diff touched nothing under apps/server.
Discovered work with task-scoped IDs. Workers notice problems outside their lane all the time. They are not allowed to fix them, so they record them as DW-<task>-<n>, and the orchestrator turns them into rows. U40 (the clients screens) produced several; two of them became a new task, U30a, for shell follow-ups such as a missing toast container and a doubled breadcrumb trail. That is how scope creep becomes scheduled work.
Decisions: what the owner answers, and what is delegated
Every question that is bigger than one task becomes a numbered decision. Docket's UI ledger had 30 numbered decisions (OD-1 to OD-30) by 26 October, each a row with the question and the answer. Workers record their own task-level decisions inside their report (D-U21-1, D-U25-4) and mark whether each was delegated or needs review.
On 25 October I delegated a large part of that to the orchestrator; the ledger quotes it as "I trust you with decisions". Each delegated decision is still written down with its reasoning, so I can review them afterwards in one pass. OD-29 is a good example of a decision the orchestrator made under pressure:
Root pnpm check fails only in tests that start the production entry ("server did not listen" within the 5 s budget) while the host load average is 55–90. Delegated: a branch that does not touch apps/server or packages/ passes rule 14 when the failing test files pass when re-run alone on the rebased branch; the rerun is quoted in the merge note.
The other repositories show where the line sat before I delegated. Async's deploy tasks record "owner approves host steps one by one", and I added deploy permission rules as the work needed them. Recount records "owner-delegated decisions" for budget, backup destination and priorities. Attest kept deploys with me: agents push main, and I build and deploy in Coolify. The line moved from project to project, and the ledger recorded where it sat each time.
Verification is a dial you set per project
The five repositories did not use the same level of testing, and the ledger made that choice explicit for every agent.
Each setting has a visible cost in the history. Attest's lowest setting was fast, and the ledger is honest about what it skipped: one task records that a new form passed typecheck and lint but was "not exercised in a browser (owner asked to skip testing)". Docket's highest setting caught real problems inside each task, and it still let something slip between tasks: on 26 October the orchestrator found that pnpm web:e2e --mock on main failed 15 journeys. Part of the cause was journeys written by different workers sharing a database and a run order, and part was a test pattern that the page's Content Security Policy blocks. It became task U19b, with the explicit instruction that "the seed assertion is not weakened".
Recount shows the third kind of limit, where more attempts stop helping. Its extraction-prompt task was parked in the backlog "after two attempts; model variance dominates". A ledger makes that call easy to make and easy to find later, which a chat thread never does.
The lesson I take from the table: decide the verification level per project and per phase, write it into the agent instructions, and add one check that runs across tasks after merges. Per-task exit criteria do not catch interactions between tasks.
What broke when many agents ran on one host
All of this ran on one development server. Running many workers there produced failures I had not planned for, and none of them were bugs in the code.
The disk filled up. On 25 October the ledger records "block U21 U23 U25 (host disk full)". Three workers stopped on ENOSPC before writing any code. Each worktree has its own dependencies, build output and test containers, so disk use grows with the number of parallel workers. The blocked rows were re-run from main once space was freed, which is exactly what the blocked status and the attempt counter in the report are for.
Load made tests time out. With many workers building and testing at once, the host load average reached 55 to 90. Tests that start a server with a five-second budget failed, and Sedule's history has the same symptom: "pnpm check blocked by Docker test timeouts under host load". OD-29 above is the rule that kept merges moving without weakening the checks.
Global numbers collided. Sedule numbered its decisions globally (D-112, D-113, …), and parallel workers picked the same next number. The history has "Renumber BM-127's decision to D-129 (D-124 is the bookings list UI)", "Renumber BM-94's decision to D-116 (D-113 is the Astro sitemap)" and "Keep BM-125's extended D-139 row in place of a duplicate". Docket avoided this by construction: only the orchestrator allocates global OD- numbers, and workers number everything inside their task (D-U25-1, DW-U40-4, F1). Use task-scoped IDs for anything a worker creates.
My checklist before starting a wave now covers the host as well as the ledger: free disk for one full worktree per worker plus headroom, a cap on parallel workers that the host can test at once, test containers named per task, and a sweep that removes merged worktrees.
How much it shipped
The ledgers make the output countable. Sedule went from merged planning documents on 23 October to its /app UI, planned as full parity with its MCP tools, on 24 October; the history for that day contains at least 37 task merges. Docket's UI ledger was proposed on 25 October, and by 26 October 25 of its tasks were done and one was dropped by decision, from the screen specification through sign-in, consent, sign-up, password reset, the app shell and the first CRUD screens.
From Markdown ledgers to Docket
Across these repositories the ledgers hold the same kinds of record: tasks, dependencies, findings, decisions, blockers, required reviews and handoffs. Docket is that shape as a product, with an MCP server so that an agent can call get_handoff for a task, open a work session, record findings and decisions as it goes, and close the session with what is unresolved. Its own instructions to agents read like the ledger rules: recorded findings and decisions are established knowledge, so do not repeat an investigation without new evidence.
There is one honest wrinkle. Docket's own web UI is being built from a Markdown ledger, because the product that replaces the ledger does not have its UI yet.
If you want to build something similar, the server side is a normal remote MCP server; I covered the basics in how to build an MCP server in Next.js.
What this means if you are buying the work
For a company hiring a small team that works this way, the useful question is the one I raised in architecture as the control layer for AI-assisted development: what is the supervision model? A ledger answers it with records. Every task has a written exit criterion, every merge has a report with pasted verification, and every decision has a number, an answer and an owner. That is also what makes the delivery model in enterprise software from a two-person team credible: the capacity comes from parallel agents, and the accountability comes from the paper trail they are required to leave.
Ask a supplier to show you one run report and one decision log from a real project. If they cannot, the speed they promise has no audit trail behind it.
FAQ
Do I need special tooling to start?
No. Start with a Markdown table of tasks in the repository with the seven columns above, an AGENTS.md that explains the claim and report rules, and one script that checks the table for missing dependencies. Docket's wave generator and Sedule's task script are refinements you can add once the format settles.
How many workers should run at once?
As many as your host can build and test without timeouts, and no more than the current wave allows. Disk and load were my limits before the ledger or the models were.
Which model should be the orchestrator?
Use your strongest model for planning, decisions and merges, because those need judgment across the whole graph. Well-specified tasks with a lane and an executable exit criterion run well on smaller models, and you can set the model per task in the task file.
How do I stop workers from editing each other's files?
Give every task a lane, a list of folders it may change, and have the orchestrator refuse merges that touch anything else. Problems outside the lane go into the report as discovered work.
What happens when a session crashes halfway through a task?
The row still says doing with the branch name, so the orchestrator can resume or re-run it from main. The run report records the attempt number, which is how U21 and U25 show "Attempt 2" after the disk filled up.
Conclusion
Running coding agents in parallel needs a coordination layer that outlives every session, and a task ledger in the repository is the simplest one I have found. Give each row a dependency list, an exit criterion a worker can execute, a lane of folders and a status. Let an orchestrator claim rows wave by wave and keep global numbering to itself, have each worker leave a run report with pasted verification and its own gaps, and turn every larger question into a numbered decision. Then plan for the failures that come from parallelism itself: disk per worktree, host load during tests, and interactions between tasks that no single exit criterion sees.
Let me know in the comments if you have questions, and subscribe for more practical development guides.