Stop Your AI Coding Agents From Colliding: A Free Starter Kit

I run several AI agents on real work. A Claude Code engineer writes the code. A Codex reviewer checks it. A handful of specialists handle research and marketing. Each of them is good at its job when it works alone.

Put them together and the failures change shape. They stop being "the model wrote bad code" and start being "the work was right and the system lost it." I spent the last few days fixing that second kind of failure, and I packaged what worked into a free kit: six files you can drop into your own setup today.

Where my agents broke down together

None of these failures came from a weak model. Every one came from a gap between agents.

A question nobody could answer. My engineer agent needed a quick opinion from the reviewer halfway through a task. It asked, then waited. The reviewer never started, because my orchestrator runs one agent per task at a time and the engineer still held the task. The engineer polled five times, about eight minutes, then gave up. When I moved the question into its own small task, the reviewer woke in 9 seconds and answered in 43.

"Done" that wasn't done. A design agent closed its task as complete. Nobody could find the PDF it had promised. The next agent in line caught the gap because it went looking for the file.

A review that reviewed a summary. The engineer fixed an issue and told the reviewer, "fixed item 6, all six items pass." The reviewer replied that it had verified the fix. It had read the engineer's message. It had not opened the file.

Two agents thanking each other. After an answer landed, the engineer sent a thank-you as a new message. That woke the reviewer, which acknowledged the thanks. Each message cost a full agent run.

Better prompts would not have fixed any of these. Each one needed a rule both agents follow: where a question goes, what counts as done, who checks the checker, and when a message is worth sending.

The five decisions every multi-agent setup needs

Before any prompt, write down five mechanisms somewhere every agent can read them. The kit calls this step one, and everything else plugs into it.

1. Claim. How an agent marks "I'm on this" so two agents never grab the same task. A status field or a lock file both work.
2. Message. How one agent asks another a question in the middle of a run. My first answer here was wrong, and it cost me the eight minutes above. The question has to reach an agent that can start now.
3. Handoff. How work moves from one agent to the next without the receiver re-reading everything from scratch.
4. Approval. How a human says yes or no to anything irreversible: a send or a spend.
5. Lessons. Where an agent writes down what it learned, so the next run starts with it.

The kit's patterns don't care which mechanism you pick. They care that you pick one and write it down. If a step feels forced later, change the mechanism and keep the pattern.

Inside the kit

Six files, about 4,000 words, plus a designed PDF of the whole thing.

The prompt pack covers the six moments where agents collide: claiming a task, messaging another agent mid-run, handing off, asking a human for approval, recording a lesson, and checking work against a shared definition of done. Each prompt has a "swap in" note for your own mechanism and a description of what a good response looks like. The mid-run messaging prompt reads:

You need input from <Agent/role> before you can finish <specific decision>, but the rest of
your task does not depend on that answer.

1. Send a short, specific question to <Agent/role> — not "can you help" but the exact
   decision you need made and why.
2. Continue with any part of your task that doesn't depend on the answer.
3. When the answer arrives, apply it to the blocked part and note that you did.
4. If no answer arrives before you'd otherwise finish, stop and report the open question
   rather than guessing.

Line 4 matters most. An agent that runs out of time should report the open question. It should never invent the answer it was waiting for.

The handoff checklist lists what every handoff must carry: a named receiver, what changed, why, what was verified and how, what was not verified, the single next action, and the dead ends already tried. The last rule on the list is "no self-closing." If the next step belongs to someone else, the sender does not mark the task done.

The ask-human checklist gets you an approval gate that does not freeze the pipeline. The agent stages the action so your answer is a single yes or no, states what will happen and what a delay costs, and keeps working on everything that does not depend on you. Silence never counts as a yes.

The lesson-recording template keeps lessons short and tied to evidence, so a later agent can trust them. A lesson without a pointer to what proved it is an opinion.

The definition-of-done template is the one file I would keep if I had to delete the rest. You fill it in once per project, with a human, before any agent starts. After that, "done" means the same thing whichever agent says it. Every criterion needs its own evidence, so a "looks good" summary does not pass. I add one line of my own: someone other than the builder checks the output exists. That line alone would have caught my missing PDF.

The setup guide walks through all of it in five steps and runs one real task through the full cycle: a bug fix shared between a builder and a reviewer, with a bad handoff caught mid-flight and the exact checklist line that catches it. It ends with ten troubleshooting entries for the failures you are most likely to hit.

Try it in one afternoon

You do not need to adopt a framework. The kit is plain markdown.

1. Write down your five mechanisms. Use whatever your agents already share, like an issue tracker or a shared folder.
2. Fill in the definition of done with your own checks. Tests pass. The output exists at a named path. Someone other than the builder has looked at it.
3. Paste the prompts you need into each agent's standing instructions (CLAUDE.md or AGENTS.md), so every agent follows them by default instead of when you remember to ask.
4. Pick one small, real task and push it through all six patterns end to end before you roll anything out.

Step 4 is where you find out which mechanism does not fit your setup. Mine was messaging. Yours will be something else.

Where these patterns come from

I did not invent this layer. The model comes from OpenRig, an open-source harness that treats a team of coding agents as one system: named seats, an owned-work queue, required reasons for closing work, and knowledge that one agent can hand to the next. I ported its ideas onto my own setup, which I call paperclip-rig, and wrote down what survived contact with real work. Every failure in this post happened on my own machine while I built it.

Get the kit

The Agent Orchestration Starter Kit is free. Enter your email on the kit page and the download unlocks right there: a zip with the six markdown files and the designed PDF.

Get the free kit

If one of these patterns fixes something in your setup, or breaks, reply to any newsletter email and tell me which one. The next version of the kit will come from those replies.