THE VAULT / RUN IT LIKE A BUSINESS / PLAYBOOK + PROMPTS
The Agent Team Playbook
I run 3-5 coding agents in parallel most days, and the first month of doing that was pure chaos: corrupted checkouts, agents overwriting each other, one memorable merge that ate an afternoon. This is the playbook that fixed it: a decision table for when parallel actually pays, worktree isolation step by step, and four battle-tested prompts (planner, worker, integrator, reviewer) you can paste today.
LAST VERIFIED 2026-07-08 · FOUNDING MEMBER RESOURCE
NOTE
Use this page as a prompt reference. Every file below is built to be handed straight to an AI. Download it, drop it into Claude, ChatGPT, Cursor, or Lovable, and say "use this as my playbook." The prompts on this page are copy-paste ready.
You are the engineering manager now
The single biggest mindset shift in multi-agent work: you stop being the person who writes code and become the person who runs the team. Your job is decomposition, briefing, and review. The agents' job is execution.
Here's the model that makes everything else click: agents are strong junior engineers with total amnesia. Strong, because they type fast, know every API from training, and never get tired. Junior, because they take instructions literally, overreach when scope is vague, and will confidently claim something works when it doesn't. Amnesia, because every session starts from zero. The agent that built your auth module yesterday remembers none of it today.
You cannot fix the amnesia. You can only compensate for it the way real teams compensate for turnover: written briefs, explicit interfaces, and review gates. That's what this playbook is. Every artifact in it exists because agents don't share memory, and the only channel between them is text you control.
NOTE
One agent doing one task is a tool. Multiple agents with no playbook is a mob. Multiple agents plus this playbook is a team. The playbook IS the difference, there's no emergent coordination coming to save you.
The manager framing also tells you where your time goes. On a well-run parallel session I spend roughly 10% planning, 10% writing briefs, 30% reviewing, and 50% doing something else while agents work. If you're spending most of your time babysitting mid-task, your briefs are underspecified. Fix the brief, not the babysitting.
When parallel pays (and when it burns money)
Parallelism is not free. Every extra agent adds coordination cost: a brief to write, a branch to merge, a review to run. The math only works when the tasks are shaped right. My rule after a year of doing this: the shape of the task decides, not your impatience.
| Task shape | Run it | Why |
|---|---|---|
| Independent features touching different files (new endpoint + new UI page + new email template) | Parallel | Zero shared files means zero merge pain. This is the ideal case, 3 agents finish in roughly the time of 1. |
| Refactor that threads through shared state (rename a core type, change a DB schema, touch the auth middleware) | Sequential | Every agent's mental model of the shared file goes stale the moment another agent edits it. Merge conflicts in logic, not just text. |
| Exploration and research (evaluate 3 libraries, prototype 2 approaches, hunt a bug with 3 hypotheses) | Fan out cheap | Throwaway work on cheap/fast models. You keep the best result and delete the rest, so conflicts don't matter. |
| Bug fix in one module | Single agent | Coordination overhead exceeds the task. Just do it. |
| Big feature with a clean seam (API layer vs. frontend, per an agreed contract) | Parallel with contracts | Works only if you write the interface contract first. Without it, agent B invents agent A's API and you find out at merge time. |
| Anything touching lockfiles, migrations, CI config, or generated code | Sequential, one owner | These files are global state. Two agents editing package.json is a guaranteed conflict, sometimes a silent one. |
The test I actually run before spinning up agents: can I write down, per task, a list of files it owns, with zero overlap? If yes, parallel. If I'm hand-waving ("it mostly touches the billing stuff..."), sequential. The five minutes of listing files has saved me more hours than any other habit in this doc.
WATCH OUT
Watch the exploration trap: fan-out is cheap per branch but you pay for all branches. Fanning 3 hypotheses on a frontier model at agent-loop token volumes adds up fast. Use your cheapest capable model for throwaway exploration and save the expensive one for the branch that wins.
Isolation: one directory per agent, no exceptions
Before the prompts, the plumbing. Two agents in one directory will corrupt each other, and it's worth understanding exactly how, because the failure is sneaky: an agent runs git checkout or edits a file, and the other agent's next file read returns content from a different branch or a half-saved state. Agent B then "fixes" what it sees, and now both branches contain interleaved garbage. Nothing crashes. The code is just quietly wrong.
The fix is git worktrees: multiple working directories attached to one repository. Same history, same remotes, one .git store, but each worktree has its own checked-out branch and its own files on disk. Each agent gets its own worktree and physically cannot see the others' uncommitted changes.
- 1
Start from a clean main checkout
In your normal repo directory:
git statusshould be clean andgit pullcurrent. Worktrees branch off whatever you have locally, so start current. - 2
Create one worktree per agent task
git worktree add -b agent/billing-api ../myapp-billingcreates a sibling directorymyapp-billingwith a new branchagent/billing-apichecked out (branched from your current HEAD). Repeat per task:git worktree add -b agent/email-templates ../myapp-emails. I keep worktrees as siblings of the main repo with amyapp-prefix so they're easy to spot and easy to nuke. - 3
Set up each worktree so the code actually runs
Worktrees share git history but NOT untracked files. That means
node_modules,.env, and local config don't come along. Per worktree: copy your env file (cp ../myapp/.env .env), install deps (pnpm install), and if your app binds a port, give each worktree its own port in the env file so parallel dev servers don't fight. - 4
Launch one agent per worktree
Open a terminal (or terminal tab) per worktree,
cdinto it, start your agent there, and paste that task's worker brief as the first message. The agent's whole world is now that directory. It cannot stomp the others. - 5
Verify isolation before letting agents run long
Quick sanity check in each worktree:
git branch --show-currentshows the right branch, andgit worktree listfrom anywhere shows every worktree and its branch. If two worktrees show the same branch, you made a mistake, git normally refuses this, so investigate before proceeding. - 6
Clean up when the work is merged
After integration:
git worktree remove ../myapp-billing(add--forceif there are stray untracked files you're sure about), thengit branch -d agent/billing-apito delete the merged branch. If you deleted a worktree directory by hand instead, rungit worktree pruneto clear the stale registration. Leftover worktrees rot fast and confuse future sessions, so clean up same-day.
NOTE
Worktrees are cheaper than clones: one shared object store instead of N full copies, and a fetch in any worktree updates all of them. For a big repo that's the difference between 30 seconds and several minutes per parallel lane.
WATCH OUT
Shared local services are the sneaky exception to isolation. Two worktrees pointed at the same local database, redis, or file storage will still interfere even though the code is isolated. If tasks touch data, give each worktree its own database name or run tasks that mutate shared services sequentially.
The four prompts: planner, worker, integrator, reviewer
This is the core of the playbook. Four roles, four prompts, and one rule that matters more than any wording inside them: never let one session play two roles. A session that wrote code will defend that code. The reviewer only works because it has no stake in the claim it's auditing.
The full versions with chaining notes are in the download at the bottom of this section. Fill every [SLOT] before pasting.
1. The PLANNER: decompose into parallel-safe tasks
Run once per feature, before any worktrees exist. Its output is the source of truth for everything downstream: file ownership, interface contracts, merge order. If the planner can't produce non-overlapping file lists, the feature isn't parallel-safe, and that's a result, not a failure.
2. The WORKER brief: scope, contract, definition of done, what NOT to touch
One per agent, pasted as the first message of a fresh session inside that agent's worktree. The load-bearing part is the must-NOT-touch list. Agents don't drift out of scope from malice, they drift because you never drew the line. The brief also forces a structured final report, which is what makes integration mechanical instead of forensic.
3. The INTEGRATOR: merge, resolve, prove it's green
Runs in a fresh session on a clean checkout after all workers report done. Two rules I learned the expensive way: merge one branch at a time and get green after each one (so a break points at exactly one branch), and never let it resolve a real behavior collision alone (a conflict where both sides are "right" is a human decision).
4. The REVIEWER: try to refute that this works
The reviewer is adversarial by design. Asked "does this look good?", agents say yes. Asked "refute the claim that this works", the same model finds real bugs. Framing is the whole trick: credit for problems found, zero credit for praise. Run it in a session that has never seen the code before.
Never merge unreviewed agent work
This is the rule I will not bend on, and the one people bend first because parallel output feels like free velocity. It isn't velocity until it's merged and correct. An agent claiming done is a hypothesis, not a fact. Agents pass their own tests they wrote against their own misunderstanding, they paste plausible test output, and they report success on code that has never actually run.
The gate is two stages, cheap first, so expensive attention only lands on work that survived the free checks:
- 1
Stage 1: cheap automated checks (minutes, no judgment needed)
Build passes, full test suite passes (run by you or CI, not trusted from the agent's paste), lint and typecheck clean, and
git diff --statshows changes only in the files the brief assigned. Any failure bounces the branch straight back to a worker session with the failure pasted in. No human reading required yet. - 2
Stage 2: adversarial review (the reviewer prompt, then your eyes)
Run the reviewer prompt from the section above in a fresh session. Then you personally read two things: the diff of the riskiest seam between tasks, and one reviewer finding chosen at random to verify the reviewer itself isn't hallucinating. That spot check keeps the whole chain honest.
- 3
Merge only on a verified ACCEPT
ACCEPT-WITH-FIXES goes back to a single worker session with the findings as its brief, then re-enters at stage 1. REJECT means the plan was wrong, so go back to the planner, not the workers.
The principle under all of it: verification beats trust. Don't trust the worker's pasted test output, run the suite. Don't trust the reviewer's verdict blind, spot-check a finding. Don't trust that the feature works because tests pass, run the feature. Every trust shortcut in this pipeline is a place a confident hallucination walks through.
PAYOFF
The two-stage gate is also what makes scale safe. Reviewing 5 agents' work sounds like a full-time job until you notice stage 1 is fully automated and stage 2 is one prompt plus a 10-minute spot check per branch. That's the deal: 10 minutes of adversarial review per branch buys you the right to run 5 branches at once.
- [ ]Full test suite run by me or CI, not trusted from the agent's transcript
- [ ]Diff touches only files the brief assigned (git diff --stat against base)
- [ ]Reviewer prompt run in a fresh session, not the session that wrote the code
- [ ]One reviewer finding spot-checked by hand
- [ ]The feature itself executed end to end at least once by a human or the reviewer
- [ ]No test was skipped, deleted, or weakened anywhere in the diff
The three failures you will hit (I hit all of them)
WATCH OUT
Failure 1: two agents editing one file. Symptom: merge conflicts that make no sense, or worse, no conflict but interleaved logic that's wrong in both branches. Cause: the planner (or you) let one file appear in two tasks' scopes, usually a barrel file, a router, a config, or a shared types file. Fix: exclusive file ownership at planning time, and make registration-style files (routers, index exports) owned by exactly one task or handled by the integrator at merge time. Prevention is the planner's rule 1; there is no good cure after the fact.
WATCH OUT
Failure 2: agent B builds on agent A's hallucinated API. Symptom: agent B's branch is beautiful and green, and it imports a function that has never existed. Cause: you told B what A was building instead of giving B a written contract, so B invented a plausible interface, and B's mocks made its tests pass against the invention. Fix: interface contracts written by the planner before any worker starts, workers instructed to code against the contract and stub what's missing, and the reviewer's hallucination sweep (verify every import exists) as the backstop. This one is nasty because everything looks done right up until integration.
WATCH OUT
Failure 3: the integration big-bang. Symptom: five branches, each individually green, merged in one heroic session that is somehow still broken two hours later. Cause: merging everything at once means every failure has five suspects, and interactions between branches only surface at the end. Fix: the integrator merges ONE branch at a time and gets fully green before the next, in the planner's stated order. A break now has exactly one suspect. If you have more than about 5 branches, integrate in waves of 2-3. The big-bang is seductive because each merge feels small; the cost is that debugging becomes archaeology.
Notice the pattern across all three: the failure happens at planning time and gets discovered at integration time. By the time you see the symptom, the cheap moment to fix it is hours behind you. That's why the planner prompt is so pedantic about ownership and contracts. It's not bureaucracy, it's moving the failure to the moment it costs 5 minutes instead of 2 hours.
Scaling past 3 agents
Everything above assumes 2-4 agents on one feature, which is where I'd stay for your first month. Past that, three upgrades matter, in this order.
Scaling up: shared TASKS.md, background agents, and cost control for fleets
When to add a shared TASKS.md
Below about 4 concurrent tasks, your head plus the planner output is enough state. Past that, or the moment work spans more than one day, you need a ledger that survives every agent's amnesia. One file, in the repo root of the base branch, owned by you (agents read it, only you and the integrator write it).
Two rules keep it useful: status changes only at gate transitions (queued, in progress, in review, merged), and every cross-task decision goes in the decisions log the moment it's made. The decisions log is what saves the next amnesiac session from re-litigating settled questions.
Background agents change the review math, not the rules
Most agent tools now offer some form of background or cloud execution: fire a task, get a branch or PR back later, no terminal open. Great for the well-briefed middle of the pipeline (workers with tight briefs), bad for planning and integration, which need you in the loop.
The trap: background agents produce finished-looking branches while you're not watching, and the temptation to skim-merge is strong. The review gate does not relax because the work arrived asynchronously. If anything, tighten it: background work never got mid-course correction, so its error bars are wider. My rule: background agents only get tasks where the brief's definition of done is fully mechanical (tests, diffs, contracts), because nobody was watching for the fuzzy stuff.
Cost control for fleets
Parallel agents multiply spend linearly at best. Five agents is 5x the tokens, and usually more, because integration and review are added stages a solo session doesn't have. What keeps my bill sane:
- [ ]Tier the models by role. Frontier model for the planner and reviewer (judgment-heavy, runs once each). Mid-tier for workers (well-briefed execution). Cheapest capable model for exploration fan-outs you'll mostly throw away.
- [ ]Set a per-task budget in the brief. Add a line like "if you exceed roughly [N] minutes or get stuck twice on the same error, stop and file a BLOCKED report." A blocked report costs cents; a runaway loop retrying the same broken test costs real money.
- [ ]Cap fan-out at what you can review. Unreviewed done work is inventory, not output. If your review throughput is 3 branches a day, running 8 agents just builds a queue of stale branches that conflict with each other by the time you read them.
- [ ]Kill stale branches fast. A parallel branch older than 2-3 days has usually drifted from base enough that re-running the task from a fresh brief is cheaper than rebasing it.
- [ ]Watch the retry loops. The most expensive failure mode I've had wasn't a big task, it was an agent re-running a broken test suite in a loop. The stop condition in the brief is your circuit breaker.
And the meta-rule for scale: every agent you add must pay for its own coordination cost. When adding a fifth agent means writing a fifth brief, a fifth review, and a longer integration chain, sometimes the honest answer is that four agents plus you reviewing faster is the higher-throughput team.
Your first parallel run, this week
- 1
Pick a two-task feature
Something with an obvious seam: an API endpoint plus the UI that calls it, or two independent features. Not your gnarliest refactor. You're learning the workflow, not stress-testing it.
- 2
Run the planner, then actually read its output
Check the file ownership lists for overlap yourself. If the planner couldn't separate them cleanly, believe it and run sequentially. Ten minutes here decides how the whole afternoon goes.
- 3
Two worktrees, two briefs, two sessions
Follow the isolation steps above. Paste one worker brief per session. Then, and this is the hard part, let them work. Resist the urge to hover.
- 4
Integrate one branch at a time, then review adversarially
Fresh session for the integrator, fresh session for the reviewer. Spot-check one finding. Merge only on a verified ACCEPT.
- 5
Do a 5-minute retro on your own briefs
Whatever went sideways traces back to a brief. Which slot was vague? Which file wasn't on a must-not-touch list? Fix the template, not the agent. That loop is how this becomes boring, and boring is the goal.
Grab the two downloads above, run the two-task version once, and you'll have the whole system in muscle memory inside a week. The prompts do the heavy lifting; your job is to stay the manager.
Get the next drop
Every new Vault system ships to the list first. Twice a week, free.