timeboxed-iterating skill
scriptsRuns tasks iteratively over a user-specified duration by dispatching parallel subagents that share state via on-disk files.
- GitHub stars
- 28
- Files
- 9
- Last commit
- Nov 11, 2026
- License
- MIT
- Allowed tools
- —
What does the timeboxed-iterating skill do?
timeboxed-iterating runs tasks iteratively over a user-specified duration by dispatching parallel subagents that share state via on-disk files.
Summary generated from the skill's SKILL.md.
About the timeboxed-iterating skill
Executing complex, repetitive tasks over a specific timeframe is what this skill enables for developers who need to grind through large workloads. It functions as a linear orchestrator that manages a clock and dispatches multiple subagents in parallel batches to work on independent units. Instead of the orchestrator performing the work, it focuses entirely on planning, time-checking, and managing on-disk state files like the progress digest and environment cheatsheet.
This approach prevents context exhaustion by ensuring the orchestrator never ingests large artifacts or long transcripts. Subagents communicate via tiny status updates and persist all heavy results to the filesystem. The system distinguishes between finite goals, which stop once an explicit list is exhausted, and open-ended goals, which utilize the entire user-specified duration. By using role-prompt paths and shared files by reference, the skill eliminates the need for subagents to rediscover information, allowing knowledge to accumulate dynamically through a self-populating cheatsheet.
What an agent can do with it
- 1Exhaustive lint error correctionA developer can assign a finite list of specific errors for subagents to fix until the list is complete.
- 2Automated test coverage improvementAn agent can run parallel subagents to write new tests for different modules until the time limit is reached.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the timeboxed-iterating skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the timeboxed-iterating skill in Claude Code
~/.claude/skills/timeboxed-iterating/SKILL.md
$ npx degit av/skills/timeboxed-iterating ~/.claude/skills/timeboxed-iteratingInstall the timeboxed-iterating skill in Claude Code (project)
.claude/skills/timeboxed-iterating/SKILL.md
$ npx degit av/skills/timeboxed-iterating .claude/skills/timeboxed-iteratingInstall the timeboxed-iterating skill in Codex
~/.agents/skills/timeboxed-iterating/SKILL.md
$ npx degit av/skills/timeboxed-iterating ~/.agents/skills/timeboxed-iteratingInstall the timeboxed-iterating skill in Gemini CLI
~/.gemini/skills/timeboxed-iterating/SKILL.md
$ npx degit av/skills/timeboxed-iterating ~/.gemini/skills/timeboxed-iteratingInstall the timeboxed-iterating skill in Claude.ai
npx degit av/skills/timeboxed-iterating timeboxed-iterating && zip -r timeboxed-iterating.zip timeboxed-iterating # claude.ai → Customize → Skills → + → Create skill → Upload a skill → timeboxed-iterating.zip
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableav/skills/timeboxed-iterating is public and reachablegithub.com/av/skills/tree/HEAD/timeboxed-iterating ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-11github.com/av/skills/commits ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/av/skills/blob/HEAD/timeboxed-iterating/SKILL.md ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/av/skills/blob/HEAD/timeboxed-iterating/SKILL.md ↗Pass
- SKILL.md follows the Agent Skills formatdescription is 1139 characters; the limit is 1,024github.com/av/skills/blob/HEAD/timeboxed-iterating/SKILL.md ↗Finding
SKILL.md
View on GitHubTimeboxed Iterating — Parallel Fan-Out Under a Clock
Take a goal and a duration and grind it out with subagents. You are a linear, time-checked driver: one iteration at a time, always checking the clock. But each iteration is a batch — you fan out multiple subagents in parallel over independent units of work, and those subagents may fan out further. You never author anything yourself. Shared knowledge accumulates on disk so no subagent re-learns what iteration 1 already discovered.
Your Role
You are the orchestrator. You do exactly five things:
- Manage the clock —
date +%sbefore every batch; the deadline is the brake. - Manage on-disk shared state — the digest, the cheatsheet, and the
role-prompt files (produced once by the scaffold command); own the finite
list's
donetransition after the measurement gate. - Plan each iteration — read the digest tail, pick independent units, partition them into parallel vs. serial, size a model per unit.
- Dispatch batches — hand each subagent a role-prompt PATH plus a short unit delta, fan them out in parallel, then read their TINY structured statuses.
- Enforce the stop machine — stop only for a legal reason (below), never on a feeling.
You do no authorship and no analysis: no code edits, no DB queries, no PR creation, no HTML/report generation, no "quick fixes," no reading the codebase to figure something out. Every productive act happens inside a subagent — even under context pressure, even after a blowout (this is the Orchestrator-Only Line, and it is the fix for the failure where orchestrators burned their scarcest resource doing delegable work). Your context is reserved for the dispatch loop. If you catch yourself doing anything other than checking time, managing the on-disk files, planning, and dispatching — stop. That work belongs in a subagent.
Pure dispatch — never ingest large content (E3). Orchestrator context is the
scarcest resource on a long run; exhausting it forces premature restarts. So you
never read a full artifact, a full subagent transcript, or a large return into
your own context. Subagents persist their results to disk — their unit file, the
digest, the cheatsheet — and return only a TINY structured status (e.g.
unit X: done, commit <hash> or measure X: PASS — <one line>). You read only the
compact digest tail plus those one-line statuses. Prefer having subagents
append their own digest/unit-file entries so you are not even reproducing that
content. Per-iteration footprint stays minimal: clock check → glance at the digest
tail → dispatch by reference → record/confirm a one-line status. If a return is
about to dump an artifact or a wall of prose into your context, that is a Red Flag
— it belongs in the unit file, fetched by whoever needs it, not by you.
The Iron Laws
1. THE CLOCK (OR THE USER) DECIDES WHEN AN OPEN-ENDED RUN STOPS. Not you, not a subagent, not a "feels done."
2. A FINITE LIST DECIDES WHEN A FINITE RUN STOPS. Exhaust the list → stop. Finishing early is CORRECT, not failure.
3. THE ORCHESTRATOR NEVER AUTHORS. It checks time, manages disk state, plans, dispatches, reads returns. Nothing else.
4. EACH ITERATION FANS OUT; INDEPENDENT WORK RUNS IN PARALLEL. Serial dispatch of independent units is the dominant, forbidden loss.
Law 1 preserves this skill's one genuine strength — an open-ended run must not stop early just because progress "looks good." Law 2 narrows that strength: it does not apply to a finite, exhaustive spec or a finite item list, where padding the clock after the list is done is pure waste. You must classify the goal (Phase 0) to know which law governs.
What Makes This Work (Non-Negotiables)
Violate any of these and you are running a slow serial loop, not this skill:
- Linear driver, parallel fan-out. You never run two iterations at once — the loop is sequential and time-checked. But one iteration dispatches many subagents at once over independent units. (C1)
- Shared state by reference, never inline. Progress digest, cheatsheet, and role-prompt files live on disk; every dispatch passes paths — the role prompt, and (via the initialiser) the digest and cheatsheet — and orders the subagent to read them first. You never paste a template, the digest, or the cheatsheet into a prompt. (C2)
- The cheatsheet populates itself. Every subagent reads the initialiser preamble first, which makes it read the shared state and append any hard-won environment fact back to the cheatsheet before returning — so knowledge accumulates dynamically, batch over batch, and the next batch starts warm. Recipes and gotchas are discovered continuously, NOT front-loaded from a test run. (B2/D1)
- Single source of truth for volatile values. Live counts, hashes, and iteration numbers live in exactly one place (the digest). Never embed them across N files. (B4)
- Real success bar first — numeric OR textual. The actual bar the goal is judged by is identified up front and piloted before mass production — it gates the loop early, not at the end. That bar may be numeric (a threshold, score, count, pass rate) OR qualitative/textual (a rubric, an acceptance description, an LLM-judge verdict, a checklist, "reads like X and covers Y"); the gate is identical either way. The gate does not expire after the pilot: every unit produced against a statable success bar must pass that real bar — applied by a separate measurement subagent, never the producer — never a proxy — before it is marked done (Phase 2d). If the goal has no statable success bar at all, the gate does not apply. (B5)
- Front-load only genuine enablers. Stand up execution infrastructure, record the real success bar (numeric OR textual) + scope/validity bar IF one exists, and sync the repo in the first iteration(s) — never the final hour. Everything else (recipes, tool quirks, gotchas, reusable findings) is discovered DYNAMICALLY by subagents via the initialiser+cheatsheet loop, not front-loaded from a test run. (B8/D1)
- Model sized to the unit, capped at your own tier. Cheap models for mechanical units; never a model more powerful than the orchestrator. (C3)
- No manufactured work, no idle. The loop never invents bookkeeping to stay busy and never sleeps out the clock. (B4/B6)
- Concurrency-cap aware. Never dispatch more subagents at once than the platform allows — over-cap dispatches fail silently.
- Prompts are written once to disk, referenced by path — never hardcoded.
The general rule: whenever you will reuse a prompt, you write it to disk ONCE
and thereafter reference it BY PATH in every identical situation — you never
re-compose or re-type it. The four standard role prompts (initialiser, builder,
sub-subagent, measurement) are produced once by the scaffold command (Phase 1a);
if you ever compose a specialized prompt for a recurring unit type, write it
into
<harness>/prompts/once and dispatch it by path too. Every dispatch is a role-prompt PATH plus a short unit delta — never a re-typed template. (E1/E4/D3/C2) - Orchestrator = pure dispatch. You never ingest a full artifact, transcript, or large return into your own context. Subagents persist results to disk and hand you a tiny status; you read only the digest tail + those one-liners. Your context is the resource this skill exists to protect. (E3)
Inputs
- Goal — what to do (e.g., "distill a fixed list of source documents into notes", "fix every lint error", "improve test coverage", "harden the API").
- Duration — how long (e.g., "4 hours", "overnight" = 8 hours, "90 minutes").
If the duration is vague, interpret "overnight" as 8 hours. If the goal is genuinely ambiguous, ask one question. Otherwise pick and proceed.
The Process
digraph timeboxed {
rankdir=TB;
node [shape=box];
classify [label="Phase 0: Classify goal\nFINITE vs OPEN-ENDED\nrun scaffold: workspace + prompts/ + digest + cheatsheet + clock" shape=doublecircle];
front [label="Phase 1: Setup + Front-load\nscaffold produced prompts/ ONCE;\nsuccess-bar pilot (numeric OR textual) + enabling infra +\nscope/validity bar + repo sync\n(seeds cheatsheet; then it grows dynamically)"];
brake [label="Brake + Stop-guard\n(deadline? finite list done?\nremaining time fit a useful unit?)" shape=diamond];
plan [label="Phase 2a: Plan iteration\nread digest; select independent units;\npartition parallel/serial; size a model each;\ncap batch at concurrency limit"];
dispatch [label="Phase 2b: Dispatch BATCH in parallel\neach subagent: role-prompt PATH + unit-file path +\ngap line (short delta) — NO inline templates"];
collect [label="Phase 2c: Read TINY statuses (never full artifacts)\nspot-check each commit via git log"];
consol [label="Phase 2d: Consolidate (minimal footprint)\nsubagents already appended to digest+cheatsheet;\nflip finite-list done only after the success gate PASSes"];
done [label="Phase 3: Stop\nfinal summary" shape=doublecircle];
classify -> front -> brake;
brake -> plan [label="OPEN-ENDED and a useful unit fits\nOR FINITE and list not exhausted"];
brake -> done [label="deadline passed / user stop /\nFINITE list exhausted /\nno useful unit fits remaining time"];
plan -> dispatch -> collect -> consol -> brake;
}
Every path returns to the brake check. done is reachable only from the
brake check — there is no quality-based or "feels complete" exit anywhere in the
graph. Where the diagram and the prose disagree, the Stop Machine below is
authoritative.
Phase 0: Classify + Setup
0a. Classify the goal — FINITE vs OPEN-ENDED (C4)
This is the first decision and it governs the entire stop behavior. Write the classification into the digest header; it is not revisable on a whim.
- FINITE — the goal is a precise/exhaustive spec or a finite, enumerable list of items. "Process these 25 documents." "Fix all 40 lint errors." "Port every endpoint in this file." "Implement the 12 facts tagged @spec." For finite goals, enumerate the item list explicitly into the digest at setup — the list is the completion authority (Iron Law 2). Finishing when the list is exhausted is CORRECT.
- OPEN-ENDED — the goal has no fixed terminus; there is always more. "Improve test coverage." "Harden security." "Reduce AI slop." "Find bugs." For open-ended goals, the clock is the only completion authority (Iron Law 1). Use the full duration; do not stop because it "looks good enough."
If a goal is finite in one dimension and open-ended in another (e.g. "review these 10 files for bugs" — finite file list, open-ended depth per file), treat the enumerable dimension as the list and the depth as open-ended within each item: the run ends when the list is covered to a defined depth or the clock fires, whichever first.
0b. Setup the harness — run the scaffold command (E4)
You do not hand-build the workspace or paste template text. ONE command produces
the entire ready-to-run workspace at ~/.harness/timeboxed/<slug>/ from a few
variables — see The Scaffold Command below for the full contract. Run it now:
bash <skill-dir>/scaffold/init.sh \
--slug <slug> --goal "<goal>" --mode <finite|open-ended> [--duration <e.g. 4h|90m>]
<skill-dir> is the directory containing the loaded SKILL.md, including its
scaffold/ folder. Resolve it from the installed skill path rather than assuming
a global install. If scaffold/init.sh is missing, stop setup and reinstall with
npx skills add av/skills --skill timeboxed-iterating. Do not rebuild it by hand.
It creates and variable-substitutes:
progress.md — the STATE DIGEST: compact, single source of truth for
volatile values (iteration count, per-unit status, commits,
the finite item list + what's done). Subagents append one-line
statuses; you read only its tail. NOT a pile of ledgers.
run-card.md — the static RUN CARD: run identity + workspace map + resume
pointer. Holds NO volatile values (those live only in
progress.md). Read it once to orient.
cheatsheet.md — persistent, growing: environment recipes, working commands,
tool quirks, known gotchas, auth workarounds. Seeded with known
tool errors and their next step; read by every subagent,
appended to by every subagent.
prompts/ — role prompt files, produced ONCE by the scaffold from the
filesystem templates in `scaffold/`: initialiser.md (read FIRST
by every subagent), builder.md, sub-subagent.md, measurement.md.
Dispatches pass these BY PATH, never re-typed.
units/<unit-id>.md — one file PER UNIT: its scope on dispatch, its full result on
return. Per-unit files exist so parallel subagents never write
to the same file (no write contention), and so full results live
on disk instead of in the orchestrator's context.
After scaffolding, fill the two placeholders the scaffold left in progress.md:
the concurrency cap and the real success bar (numeric OR textual — Phase 1
pilots it; write none if the goal has no statable bar). Dispatch a subagent for
anything non-trivial — you author nothing.
Create the target repo context: the artifact is always under git (existing repo
in place, or mkdir ~/code/<slug> && git init for from-scratch work). Every
subagent commits; your spot-checks depend on it.
0c. Clock
date +%s, compute the deadline epoch, write both to the digest. You check it at
the top of every iteration (the brake), before dispatching the batch — never
after, never "when convenient."
Phase 1: Setup + Front-Load (B5 + B8 + D1 + D3)
Do this before the main loop, in the first iteration(s). You author nothing — the front-loading work itself runs via dispatched subagents (Iron Law 3).
1a. Prompts already exist on disk — written once, referenced by path (E1/E4/D3)
The scaffold command (Phase 0b) already produced the four role prompts under
<harness>/prompts/, variable-substituted:
initialiser.md— the preamble EVERY dispatched subagent reads first.builder.md— the builder role prompt.sub-subagent.md— the fan-out role prompt.measurement.md— the independent measurement role prompt.
You do not re-type or re-compose them. Thereafter every dispatch hands the subagent a role-prompt PATH plus a short unit delta (2b). Re-typing one burns your context (the resource this skill protects) and is a Red Flag.
The general rule (E1): write any reusable prompt to disk ONCE, then reference it
by path in every identical situation. The scaffold covers the four standard
roles. If you ever find yourself composing a specialized prompt for a recurring
unit type, do not paste it into each dispatch — write it into <harness>/prompts/
one time and dispatch it by path exactly like the standard roles.
1b. Front-load ONLY genuine enabling setup (D1)
Front-load only what is a real ENABLER and provably exists — not a speculative "run the whole task once to see what breaks." A pilot may surface no issues, and issues surface continuously, not at t=0. In priority order:
- Real success-bar pilot (B5). Identify the bar that actually decides whether
the goal succeeded — the expensive discriminating judgment, not a cheap
pass-shaped proxy. That bar may be numeric (a threshold, score, count, pass
rate) OR qualitative/textual (a rubric, an acceptance description, an
LLM-judge verdict, a checklist, "reads like X and covers Y"). Dispatch a
subagent to apply it on a small pilot (one item, one sample) and prove the
real bar actually discriminates a good unit from a bad one on ONE representative
item before producing the rest. This bar then gates the loop: subsequent
batches produce only against a bar that already works. Never mass-produce, then
judge at the end. If the goal genuinely has no statable success bar (pure
open-ended qualitative churn with nothing to judge against), record
noneand skip the gate — but prefer to state a bar wherever one exists. - Enabling infrastructure (B8). Runners, harnesses, environment setup, API
access, the in-cloud runner if the run needs one — stand it up now. The recipes
discovered here seed
cheatsheet.md; the rest grows dynamically thereafter. - Scope / validity bar IF one exists (B8). If the goal has a definition of a valid unit of output (what's in scope, what a real finding/fix/artifact looks like), record it up front. A run that culls a large pile of raw candidates down to a handful of valid ones only AFTER the box closes wasted the box; put the validity bar in the FIRST iteration so every later unit is pre-filtered.
- Repo sync (B8). Sync to the branch you'll finalize against now. Do not let a stale main branch turn into conflict theater at the end.
Everything else is dynamic, not front-loaded. Environment recipes beyond the
initial standup, tool quirks, gotchas, and reusable findings are discovered
continuously by subagents that read prompts/initialiser.md first and append what
they learn to the cheatsheet (D1). Do not try to enumerate every gotcha up front
from one test run — that is what the initialiser+cheatsheet loop is for. Keep
B8's real point (never defer a genuine enabler to the final hour) without turning
issue-discovery into a t=0 test run.
Record in the digest that front-loading ran and what it established. The cheatsheet is seeded; from here it grows itself, batch over batch.
Phase 2: The Iteration Loop
The loop is linear: one batch at a time, brake-checked at the top. Within a batch, subagents run in parallel.
Brake + Stop-guard (top of every iteration)
Run date +%s, compare to the deadline, and evaluate the Stop Machine. If
any stop condition holds → Phase 3. Otherwise continue to 2a.
A batch already in flight when the deadline passes soft-stops: let its subagents finish and consolidate their returns, then stop. Never strand committed work unrecorded.
2a. Plan the iteration
Read the digest (the compact one, not a heap of ledgers — B3). From it, select the next set of units — the smallest pieces of real work that move the goal. For a FINITE run, units are the next unclaimed items from the list. For an OPEN-ENDED run, units are the next highest-leverage angles.
Partition units into parallel vs. serial (C1 / B1) — the independence rule:
- Separate files / disjoint surfaces → PARALLEL. Units that touch different files, different modules, different topics, or independent attack surfaces have no write conflict — dispatch them in the same batch, at once.
- Shared file / shared resource → SERIAL, round-robin. Units that edit the same file, the same document, or the same scene run one at a time across successive batches. Do not try to partition a shared file into "regions" for parallel writers — that produces corruption and lost edits.
- Within a single unit, the subagent's own steps are sequential; but that subagent may itself fan out sub-subagents over independent sub-units (C1).
Respect the concurrency cap. Never put more than the platform's cap of subagents in one batch. If you have 20 independent units and a cap of 6, dispatch 6, let them return, dispatch the next 6. Over-cap dispatches fail silently and you'll redispatch blind. The cap is in the digest header.
Size a model per unit (C3). For each unit choose the smallest model that can do it well:
| Unit character | Model |
|---|---|
| Mechanical / narrow (rename, mechanical edit, run a known command, format, apply a known fix, scrape one page) | Small / cheap model |
| Standard implementation, moderate reasoning | Mid model |
| Deep design, novel analysis, hard debugging, judgment | Orchestrator-tier |
Hard cap: never dispatch a model more powerful than the orchestrator itself. If you are running on a mid-tier model, "orchestrator-tier" IS your ceiling — you cannot summon a stronger model than yourself; asking for one silently fails or wastes the dispatch. Size down freely, never up past your own tier.
Write each unit's scope into its own units/<unit-id>.md before dispatch.
2b. Dispatch the batch (in parallel)
Dispatch all units in the batch in a single step (one message, multiple subagent calls) so they run concurrently. Every dispatch is a SHORT message — a role-prompt PATH plus a small unit-specific delta, never a re-typed template:
- Role-prompt path —
<harness>/prompts/builder.md(ormeasurement.mdfor the measurement gate). That file already tells the subagent to read<harness>/prompts/initialiser.mdfirst, which points it at the digest and cheatsheet by reference and makes it write findings back. - Unit delta — the unit id, its unit-file path
<harness>/units/<unit-id>.md(you wrote the scope there in 2a), and one line naming this unit's gap/target.
That is the whole dispatch. You never paste a template, the digest, or the cheatsheet into the message (C2/D3) — you pass paths. Re-typing a template into a dispatch is a Red Flag: it burns your context, the exact resource this skill exists to protect.
The role prompts already instruct each subagent to persist its full result to disk (its unit file), append its findings to the cheatsheet, append one status line to the digest, and return only a tiny status — not a wall of prose (E3). You depend on that: your context stays small only because results land on disk, not in returns.
Do not give subagents the deadline or any time awareness. They do one unit and return. Time is your concern alone.
2c. Collect tiny statuses and spot-check (never ingest artifacts — E3)
When the batch returns, read each subagent's tiny status line — not its
artifact, not its transcript. The full result is in the unit file if anyone ever
needs it; you do not pull it into your context. Spot-check each claimed commit
with git log (the commit is there / it is not) — a cheap on-disk check, not a
read of the produced content. Subagents hallucinate deliveries; 30 seconds of
git log saves a wasted iteration. A unit that claims a commit not in git log
is re-dispatched, not recorded as done. If a subagent tries to hand you the
artifact itself, ignore the body and read the digest tail instead.
Files in this skill
9timeboxed-iterating skill questions
How do I install the timeboxed-iterating skill in Claude Code?
Run npx degit av/skills/timeboxed-iterating ~/.claude/skills/timeboxed-iterating. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the timeboxed-iterating skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How does the orchestrator manage context limits?
The orchestrator avoids ingesting large content by having subagents persist results to disk and returning only tiny, structured statuses. It only reads the compact digest tail and one-line statuses to keep its context small.
What is the difference between finite and open-ended goals?
Finite goals are based on an exhaustive list or precise spec and stop once the list is exhausted. Open-ended goals have no fixed terminus and use the full specified duration as the completion authority.
How is knowledge shared between subagents without re-learning?
Shared state, including a progress digest and an environment cheatsheet, lives on disk and is passed to every subagent by reference. Subagents read an initialiser preamble that points them to this state.