The subagent orchestration prompt I keep reusing

People keep asking me for this, so here it is in full, with the reasoning behind it.

implement @TODO.md

for each phase

1: spawn a subagent to complete the work, mark it complete in TODO.md, and then commit
2: then spawn another subagent to /super-review the work and commit a REVIEW.md with findings
3: then spawn another subagent to triage those changes, eagerly fix as many as appropriate, and delete REVIEW.md then commit
4: then move on to the next phase

once all phases are complete, spawn a subagent to do a final extra-detailed /super-review of the whole
codebase, again writing REVIEW.md; then a final triage agent to make all the necessary changes and commit

as subagents implement, they should eagerly make notes into NOTES.md which future subagents should read
before starting work

This can run effectively on a single plan for hours at a time without needing me in the loop, on a branch or worktree I’ve dedicated to it. I’ll usually have several of these running at once. Here’s why each piece is there.

Subagents, and why they matter

This only really works with Claude Code, because it has the best (arguably the only real) support for subagents right now. The point of a subagent is that it gets its own context window, and the whole game with agentic coding is preserving as much of that window as you can. The general way to do that: exactly one thing per context window.

In this setup, the top-level “main” context window is doing pure orchestration. It doesn’t scan the codebase or try to understand the whole feature - it just ties subagents together. Each subagent does exactly one thing: implement, or review, or triage. That fits inside a 200k context window unless your planning didn’t break the phase down finely enough (planning is a separate topic, worth its own post). Bottom line: get comfortable with subagents, they’re doing a lot of the real work here.

Artefacts instead of conversation

Communication between subagents happens entirely through ephemeral markdown files on disk - REVIEW.md, NOTES.md, TODO.md. One subagent writes a file, the next one reads it. Later, the file gets deleted.

This is by far the least error-prone way I’ve found to hand off state between agents that don’t share a context window. It also has a nice side effect: you can glance at the repo mid-run and see exactly what’s happening, and you end up with a full commit chain you can use afterward to see what went right or wrong - that, plus the underlying agent trace, is a genuinely useful record.

Review

/super-review is a separate skill I use for the actual review step - it just looks over the work for problems or improvement opportunities. Nothing exotic; the value is in forcing it to happen as its own pass, in its own context window, with fresh eyes rather than the implementing agent grading its own homework.

NOTES.md

Worth watching this file as it fills in. It’s often where you first notice friction in the agent experience - recurring confusion, a missing convention, a place your codebase is fighting the agent - and those notes are a good source of ideas for saving tokens down the line.

Branches

I run this on a dedicated branch or worktree per plan, which is what lets me have several of these going simultaneously without them stepping on each other.

The one thing that actually matters

None of the individual pieces here are complicated. What matters is being genuinely happy with the plan before you kick this off - because once it’s running, it’ll burn through a meaningful number of tokens executing that plan faithfully, mistakes and all. Get the plan right, then let it go.

Let me know if it works for you.