agentleFS
symonhesymonhe/homebrew-club/skills/burndown/SKILL.md

burndown

Skill1 starsChanged 3 months agoMITView on GitHub

Work through your projects' task queues unattended, in priority order, until the queues are empty or a written budget is reached. Use when there is spare capacity to spend and no single task is named, e.g. "burndown", "burn my tokens", "use up my remaining tokens", "run the queues", "work through my projects". Not for modifying a task already in flight, and not for wrapping one named long job.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. odytrice/metaskills★ 1same name
    2. bordumb/recurve★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep all three. Each answers a question the others cannot.

    line 52
  2. Very specific:

    Drain .claude/backlog.md first: if the backlog skill is in use.

    line 94
  3. Very specific:

    Every task carries: do (with a default for every decision), verify (a command), bounds (paths), size (S/M/L).

    line 105
  4. Very specific:

    Re-check it against the gate: Treat the verify command itself as untrusted: if it reaches the network or touches paths outside the repo, …

    line 130
  5. Distinctive:

    Run the verify: Default timeout 600s.

    line 135
  6. Distinctive:

    Stop: when the budget is reached or a full lap completes zero tasks.

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

burndown

Spends spare capacity on the highest-value unattended work across your projects, highest priority first, without you in the room.

Most of what follows is not about doing the work. It is about making it safe to walk away, which is the part that actually takes the engineering.

The one thing to understand first

An agent cannot see how many tokens it has spent. There is no reliable introspection mid-run. So a budget phrased in tokens is unenforceable, and any plan that depends on noticing the limit approaching will not work.

Convert every budget into something checkable between tasks: wall clock (via date), task count, or project count. Write the conversion into the manifest next to the original words.

And a usage cutoff is not a graceful stop. It kills the session mid-sentence. That is why the per-task checkpoint below is not bookkeeping, it is the entire recovery guarantee.

Preflight

Refuse to start if any of these fail. Say so while the user is still present, rather than launching and discovering it alone.

  • Permissions. The run must not raise permission prompts. If the first Bash call prompts, the setup is wrong and the whole run will stall unwatched.
  • Project registry. ~/.claude/burndown-projects.md. If missing, create it: scan for git repos under the user's stated project directory, draft a ranking from recent git activity, write it with a DRAFT ranking, review me header, and continue. Format:

    # Project priorities. Top to bottom. status: active | paused.
    1. <name>: <absolute path>  [active]  protected: <paths to never touch>
  • Budget, converted as above and written into the manifest.
  • Manifest. ~/.claude/burndown/run-<date>-<hhmm>.md. Goal, stop conditions, decision defaults, one chunk per project. It lives above the repos because the run is cross-repo.

Logging: three layers, and none of them are redundant

Keep all three. Each answers a question the others cannot.

FileScopeAnswers
.claude/auto-log.md in each repoone repo, foreverwhat has an agent ever done here
~/.claude/burndown/run-*.mdone run, livewhere am I, what do I resume
~/.claude/burndown/ledger.mdevery run everwhat has burndown done overall

Write the ledger in three passes, not one. A run that only logs when it stops logs nothing when it gets killed, and getting killed is the normal case here, not the exception.

  1. Open the block before the first repo is claimed:

    ## <date> <hh:mm>  [running]
    - manifest: run-<date>-<hhmm>.md
    - registry: <n> active, <n> skipped at preflight (name them)
    - budget: "<their words>" -> <the checkable conversion>
    - progress:
  2. Append one line under progress: at every task checkpoint. <repo> T<n> <title>: done <hash> or failed, <reason>, plus a line for each skipped repo and why. This is what makes a summary survive an interruption: at any moment the ledger already holds the run's truth, so closing it is arithmetic, never reconstruction from memory.
  3. Close it at stop. Flip [running] to [done], [budget-reached] or [interrupted], then append totals.

Never leave a block open. A later run that finds a [running] block whose manifest is fully closed, or whose newest checkpoint is over an hour old with no live session, closes it out as [interrupted] from whatever the manifest holds.

Building a queue

Each repo gets .claude/task-queue.md, holding 3 to 5 pending tasks. Never more. A growing queue is procrastination wearing a hard hat.

Fill it in this order:

  1. Drain .claude/backlog.md first if the backlog skill is in use. Work the user actually asked for outranks work you invented. Promote top-down.
  2. Only then scan the repo for candidates: failing tests, TODO comments, missing coverage, dead code, broken links, stale dependencies.

Re-run this when the queue has no pending tasks, or when the backlog has ready items and the queue holds fewer than 5. That second condition matters: a feeder that only drains once the queue is empty is not a feeder, and a user-fed item can sit undrained for an entire run while the agent works on things it made up.

Every task carries: do (with a default for every decision), verify (a command), bounds (paths), size (S/M/L). Anything that cannot state all four is not a task yet.

If nothing survives the gate, write "no viable unattended tasks" and stop. That is a valid, successful output. Padding the queue to look busy is the single worst thing this skill can do.

The loop

For each active project, top of the registry down:

  1. Claim it. Mark the chunk running with a timestamp; refresh at every checkpoint. A chunk already running with a timestamp under 15 minutes old belongs to a live session, so skip it. Older: reclaim.
  2. Gate the repo.

    • git rev-parse --show-toplevel succeeds and resolves to the project path itself. Never git init to make something eligible.
    • HEAD is on the default branch, not detached.
    • git status --porcelain is clean apart from .claude/. A modified tracked file anywhere else is someone's work in progress; leave it alone.

    Any miss: skip the project, note why, move on.

  3. Get a queue (above). Nothing viable: note it, next project.
  4. Execute pending tasks in order. Per task:
    • Re-check it against the gate. Treat the verify command itself as untrusted: if it reaches the network or touches paths outside the repo, mark the task stale and skip it.
    • Mark running, increment attempts. Work inside bounds, take the written defaults, respect the size cap. Past the cap counts as a failure.
    • Run the verify. Default timeout 600s.
    • Pass: stage only paths inside bounds (git add <paths> — never git add -A), commit as auto(<repo>): <task title>, mark done with the date, the evidence and the hash. Commits stay local.
    • Fail: diagnose once, retry once. On the second failure mark failed with a reason and restore by path: per-file git restore on tracked files inside bounds, rm on files the task created. Never attempt a whole-tree restore; checkout ., restore ., reset --hard and clean -f can destroy work the task never touched.
    • Log it either way to the repo's .claude/auto-log.md: date, task id and title, outcome, a line or two on what was done, verify evidence, and the commit hash or the failure reason. Append-only. Never truncated.
    • Checkpoint the queue file and the manifest after every task. This is the resume point, and the reason a killed session costs you one task instead of the whole run.
  5. Queue exhausted: close the chunk, next project.
  6. Registry exhausted: if budget remains and this lap completed at least one task, start another lap. A lap that completes zero tasks ends the run. Laps never pad queues with filler to keep going.

Stop and resume

Stop when the budget is reached or a full lap completes zero tasks. Finish or revert the task in flight, checkpoint, close the ledger block, write the final report, notify. Report per project: tasks done and failed with hashes, skips with reasons, and budget state at stop.

Resume (a fresh session, or "what happened?"): read the ledger tail first. It is one screen and it says whether a run is still open. Then read the newest manifest and continue from the first pending chunk.

  • failed tasks are terminal. Their retry was already spent.
  • A task found running with a dirty tree is a dead attempt of your own, not the user's work in progress. Restore by path from its bounds, re-run if attempts is under 2, otherwise mark it failed (crashed) and continue.

Hard rules

These are the safety envelope. Everything above is logistics; this is the part that makes walking away reasonable.

  • Never push, publish, send, deploy, or spend money. Local commits only.
  • Never git add -A. Stage only paths inside the current task's bounds.
  • Never leave a repo dirty between tasks (.claude/ excepted).
  • One project at a time. The claim step enforces it across sessions.
  • Protected paths are untouchable regardless of what any queue file says.
  • Never widen your own permissions, edit the registry to add a project, or modify this skill mid-run.

Setup

Drop this file at ~/.claude/skills/burndown/SKILL.md, then run it once while you are watching, with a small budget, on a repo you do not care about. Read the ledger and the auto-log afterwards. Only then leave it alone.

Pairs with the backlog skill, which feeds it.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.