# Burndown > Drain a mixed-origin ticket queue to empty as one supervised run, frontier-first, one PR per ticket. - Skill: `caneff/burndown` (Agent Skill, multi-file: 31 files) - Install (CLI): `npx skillmds@latest add caneff/burndown` - Raw SKILL.md: https://api.skillmd.com/api/skills/caneff/burndown/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: caneff (https://skillmd.com/u/caneff) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/caneff/burndown --- A **burn**: one mixed-origin ticket queue, drained to empty as one run. You are the **controller** — a session on a primary checkout's default branch, dispatching a worker per clump and ruling on what comes back. The terms are `~/.agents/skills/CONTEXT.md`'s; a worker's own job is [`implement`](~/.agents/skills/implement/SKILL.md). One spec's slices are a different run and a different policy: [`implement-spec`](~/.agents/skills/implement-spec/SKILL.md). A spec that turns up inside a mixed queue is handed off to it whole — [`references/spec-handoff.md`](references/spec-handoff.md). ## The loop The dispatch loop — pick the next jobs, start them, wait, start more as slots free up — lives **here and nowhere else** (#779). Its mechanical steps are `burndown/loop.py`; why each rule reads the way it does, with the evidence it came from: [`references/loop.md`](references/loop.md). **Where the controller runs.** Any primary checkout's **default branch** — read from `refs/remotes/origin/HEAD`, never assumed to be `main` — and not necessarily the target repo's checkout: the loop addresses the target with `--repo` on every tracker call. `python3 burndown/loop.py seat` refuses a linked worktree and says why, because inside one `/implement`'s front-door rule reads the session as a **worker** and the same prompt would start a build instead of a run. It refuses a detached HEAD and a non-default branch too. **Open the run.** 1. Take the seat (above), then `runfile.py start` the run with its slot budget (5 when `--slots` is omitted) and the controller's own herdr agent name (§ Run state). Resuming an existing run instead: `runfile.py resume`, and then **one message per live, unlanded worker** — its `announce` bucket and only that one, via `loop.announce`. A landed clump's worker gets none however its agent looks; a vanished one gets none either, and is reconciled or parked by hand. The bucket names each worker by its **herdr agent name**, which is the durable key and not an address: resolve it to a reachable session at **send time** (#923), and never write a resolved address into the run file. 2. Read the frontier (§ The frontier) over the **whole queue**, not the first wave's worth, and clump it (§ Clumping): `closure.py --json` into the candidates file, never built by hand. That exploration is the run's **frozen** candidate set: a ticket filed while the run is going waits for the next run. The one exception is a ticket filed *during* the run **because the run is stuck on what it fixes** — `loop.admit` takes it only with the clump it unblocks named. Then **tag the tier before any dispatch** (§ Tier tagging): `python3 burndown/tier.py =[,]...` writes the missing `documentation` label onto every docs-only candidate, because the tier is read off the ticket at dispatch and a label written after that is a label that came too late. 3. The **opening report** carries `closure.py`'s announcement line verbatim, so the reader can tell all three declaration states apart: a declared directive, a **declared None** — the repo has no include graph — and **silence**, which clumps conservatively by directory subtree. A controller reading "conservative" has to know which of the last two it got. It also carries `tier.py`'s line (§ Tier tagging), which **names every label the exploration pass wrote** and says `labels written: none` when it wrote none — a report silent about labels reads the same from a pass that wrote nothing and a pass that never ran, and the difference between those two is a ticket dispatched at the wrong tier. **Then, until the queue and the slots are both empty:** 4. **Recompute the frontier at each landing** and dispatch into every free slot. Refill is **continuous**: no waves, because a wave holds slots empty waiting for its slowest clump. 5. **At each dispatch, re-resolve the closures** — the clump's own and every **in-flight** clump's, through `closure.py` against current `main`, **one hop**; an in-flight clump's tickets and workspace come from the run file, its closure from that re-resolution, and the two together are `loop.py dispatch`'s `--in-flight`. A clump whose closure intersects a live workspace's is **off the frontier**: `loop.py dispatch` picks from what is left and names what holds the rest. That hold, with `picks`' same-tick guard (two clumps sharing a file are never picked in one tick, and that skip prints no `held` line), is what keeps a **family's clumps** apart: a clump sharing a file with a live or just-picked one waits, and family members sharing no file run at once. Two consequences, because neither is visible from the frontier's own definition — a run drains **out of ticket order**, and one parked worker can hold a **whole family** off the frontier until it lands. A controller reading only "open, unblocked, unclaimed" would dispatch into the collision. 6. **Full re-exploration fires on one trigger**: a landing whose diff touched a **hub** — a file two or more candidates' closures share (`loop.py hub`). Every other landing gets step 5 and nothing more. 7. **Box check before every dispatch** — read `uptime` and `free -g`, and pass the committed `ulimit -v` GB to `loop.py dispatch`, which weighs every worker the tick would start, takes only as many as the box has room for, and refuses outright when that is none. The **28** cap counts **agent processes** — Claude sessions, subagents included — across the whole shared box, not this run's and **not OS processes**: an idle WSL box holds ~190 of those, so `ps | wc -l` refuses every dispatch. `loop.py` measures the agent count itself (`ps -eo comm= | grep -cx claude`, by command name: `pgrep -f claude` also matches plugin scripts and hook shims and overcounts more than 2x); `--processes ` overrides it, and the refusal names the number and the counter. A box it cannot measure, or one listing no `claude` at all (the controller is one), is refused, never read as empty; pass `--processes` with a count you took. The ~**24 GB** ceiling is on the sum of the per-process `ulimit -v` caps. A slot the box cannot afford stays empty; that is not a reason to dispatch into it anyway. A slot is budgeted at its **peak**, not its steady state (#933): `references/loop.md` § The box check, and `loop.py dispatch` prints the `peak:` line that goes in the status line below. `loop.py box` takes `--live `, the workers already running; omitting it is refused. 8. Dispatch and merge through [`implement`](~/.agents/skills/implement/SKILL.md) § Dispatch, which claims the clump and starts the worker; `implement/SKILL.md` § The merge, which merges and cleans up, is the controller's own step there. The loop restates neither grammar. When two in-flight branches turn out to touch the same files, the collision procedure, the closure defect it implies, and the rule that every outstanding worker question is answered **before** cleanup: [`references/merge-tail.md`](references/merge-tail.md). Register each dispatched clump with `runfile.py clump` — its workspace and its worker's herdr agent name, or step 1's resume has nothing to re-announce to — and each landing with `runfile.py land`, so a restart can pick the run back up. 9. **Wait on the wake, and sweep on an idle one.** The loop waits by being idle, never inside a tool call: a controller in one hears no worker until it returns. What it trusts while it waits, in rank order, and the bounded backstop it runs when it wakes with nothing else to do: § Liveness. A clump that cannot go on parks, and a run that parks twice with no landing between stops: § Parking and escalation. ## The frontier Which tickets a run may dispatch next — open, labelled, unclaimed, waiting on nothing — is read by `burndown/frontier.py`, not by a regex at the call site: `python3 burndown/frontier.py