Three Rules for Agent Teams

Depth was solved; breadth wasn’t. The pair could ship a feature, but not a large cross-domain one, and new features often “reinvented the wheel”, duplicating features leading to spaghetti, and the codebase had the scars to prove it. This installment recurses the pair one level up into an orchestrator team, walks through the delegation failures that came with it, and lands on the three rules that actually held: split ownership before writing, make handoffs persistent, require explicit permission before action.

Stage 7: The Teams

Over the course of the four or so months building with the agent-pair+ framework, its shortcomings, over time, snowballed and resulted in the codebase, in some places, being more tangled than TF2’s legendary coconut.jpg.¹

Just recently, while working on something new, I took a step back and asked for a general audit of this one data pipeline before starting work. Turns out independent sessions had each reimplemented the same component several times. Another example was an incomplete database migration that reached deployment and silently dropped data before it was caught… oops.

These failures were obviously due to independent sessions touching the same surface area at different times, i.e. fragmented context. The pair + reviewer excelled at depth in a single local track, but it alone was incapable of the vast breadth that was required to properly build out large multi-domain features or refactors.

The immediate naive solution was, of course, to just have one single agent manage everything. Buuuuuuuuut (big but, again) this is impossible due to context limitations.

Sure with the introduction of each successive frontier model comes more context, better context management, better one-shotting, and by extension, wider breadth that a single agent could take on in one go. However, as many people who have actually worked with the agents know, this is mostly just a marketing stunt and the “one-shots” typically don’t work very well when placed inside of an already existing codebase since making just one new feature would require knowledge of how exactly everything remotely related to it connects.

This, of course, would far exceed the average ~256k token context limit of a single agent from half a year ago, and even the 1M context window that most frontier models can capably support now was not enough to store all the detail. This is also assuming that agents had perfect recall near max context length, which isn’t the case. According to research done in mid-2025 by Chroma, then frontier agents like Claude Opus 4, GPT-4.1/o3, and Gemini 2.5 Pro had suffered from serious performance degradation as context grew.

Note that, while the study was done nearly a year ago (a long time in the world of AI development), context rot is still an issue to this day — even according to Anthropic’s own introduction of Opus 4.6 where, while admitting to context rot being a problem, one of their top headline figures on a needle-in-a-haystack retrieval benchmark with 1M context was only 76% — a one-in-four error rate!² On top of that, real life is often far rougher than a clean haystack so the true de facto number is probably way below that; and that isn’t even factoring in the possibility of ‘benchmaxxing’.³

Going back to the Chroma paper, its run of the LongMemEval benchmark showed that a focused input of ~300 tokens beat out an entire context of ~113k tokens when agents were asked to both retrieve an answer and reason on it. The key takeaway is that models, even when given the information, reason worse when it’s surrounded by a lot of other irrelevant stuff. In our development setup, that would be the main thing holding back our agents from just having super long spec docs and implementation plans to build the entirety of a large, cross-domain feature with lots of sub features and lots of outgoing connections.⁴

Anyways, to solve this issue, I took inspiration from how DeepSeek V4 tackled the long-context tractability problem. V4 had just dropped and my YouTube feed was littered with videos about the release — in particular, its “revolutionary” solution to context rot. Naturally I watched a few of them (here’s one I remember watching), and a couple described the following method V4 uses to manage long context. In their architecture, they use heavily compressed attention (HCA) and compressed sparse attention (CSA),⁵ along with the typical sliding window context, to build three layers of context to be traversed, all at different depths. To illustrate this, take a book as a metaphor for session context, and suppose you’re in the middle of reading a book. The context is organized (roughly) like this:

1. HCA compresses every chapter to a sentence, and you read all of them, producing a dense but coarse summary of the entire book.

2. CSA then compresses every paragraph into a phrase, but you actually only read the ones most relevant to whatever questions you may have.

3. The local window is essentially the most recently read page, word for word.

A grossly oversimplified execution trace of an already oversimplified version of the system when you ask a question would go like this:

1. the model goes through HCA to find the chapters your question most likely relates to,

2. then uses CSA within that to find the most relevant paragraphs to your question,

3. and then, depending on how far back it is, the compressed context and/or the local exact context is read to help answer your questions.⁶

The third layer is rather irrelevant for our purposes here since we’re not developing inside of the context of some LLM; thus, we can keep an exact copy of the codebase — our “context” — on hand at all times, which we do; it’s just the local checkout you keep on your dev machine and/or origin/main. The main thing to lift from this context management architecture is the high level design behind using HCA and CSA. In short, to manage a large amount of context, you need to have one guy manage a high level overview of the entire thing, and then dispatch more detailed and specific overviews relating to what you’re trying to do.

Before the machinery, the principle it all reduces to: by the end, the team ran on three rules: split ownership before writing, make handoffs persistent, and require explicit permission before action. Everything below is just the apparatus that enforces those three.

To facilitate this, I elected to recurse the general agent-pair structure one level higher. The structure I eventually converged on was the following:

1. At the top was a top level orchestrator-pair consisting of a ‘planner’, and a ‘reviewer’. In day to day work, I assigned Claude Opus 4.8 as the planner, and GPT-5.5 as the adversarial reviewer.

2. Then, the layer under consisted of two to five of the worker-pairs on the agent-pair+ framework, again with Opus 4.8 as the planner and GPT-5.5 as the implementer.

When developing a new feature, I would feed the pair a spec doc that simply listed what the feature had to include. Sometimes, that would go through a separate step of being passed to a chat model, like ChatGPT-5.5 on Pro Extended thinking and/or deep research,⁷ to suggest tried-and-true architectures and designs, as well as suggested sequencing and timelines before getting passed into the orchestrator-pair. The planner would then dispatch auditing relays for codebase exploration — reviewed by the reviewer and me — to the subservient worker-pairs, who would each separately produce a pre-planning audit of their part of the codebase. The audit would then get passed back to the orchestrator-pair, where the planner would reconcile and consolidate the audits before using this info to generate and persist a more complete spec + roadmap document from the initially inputted spec doc. This doc would be the key point of reference for the orchestrator-pair in what to dispatch.

On each new item in the roadmap, the orchestrator-pair ran the following loop (starting off from fresh context each time):

1. The planner cut the item into one or more work bundles, partitioned so that no two simultaneously-active pairs owned the same surface area.

2. For each bundle, the planner drafted a dispatch down to a subservient worker-pair to either start the Superpowers cycle (from Stage 6 above) from the auditing phase, the design phase, or the planning phase, reviewed and checked off by the reviewer and me before it went out.

3. Each receiving pair kicked off the Superpowers cycle from the designated starting point on its own independent bundle.

4. On the PR(s) being deemed merge ready by the worker-planner and the panel of reviewers, it gets passed up to the orchestrator-pair (and me) for a light final review.

5. The orchestrator planner or I would then give a merge signal to the agent team.

The loop repeated, item by item, until the roadmap was exhausted.

Note that the roadmap was also a live document, meaning that, as agents run into something while doing their more focused audits, implementing, or reviewing, it would get passed up to the orchestrator-pair to fold into the roadmap.

The particularly observant would notice that the orchestrator-pair was basically, in a sense, just a slimmed-down version of the agent-pair framework — it just had no implementation and no independent review panel of the artifacts it produced. My reasoning for not having a panel review the pair’s work was simple — they merely produced sequencing, short dispatch relays, and maintained an easily parsable high-level spec/roadmap doc.⁸ These were all in prose too so they were really easy for me to personally read and review whenever needed.

Really, this was just a purified reincarnation of the old swarm from a few stages back. Now, instead of me attempting to micromanage a team of largely uncorrelated agents attempting to tackle the same task in parallel, a large part of management got offloaded onto an orchestrator-pair and the uncorrelated agents were reduced to just a handful of worker-pairs that were more or less capable of standing on their own, leading to them being able to be dispatched individually to larger, non-overlapping portions of the specs at the same time, while also being able to coordinate with each other (though through the orchestrator) if needed. This dramatically increased breadth — by extension, throughput — and also basically removed the context fragmentation issue at the global level that every stage before this had. Though, at this point, each subservient worker-pair was still somewhat locally confined (more on that in a bit).

On the other hand, this orchestrator-team framework also reintroduced an issue from the swarm era: I still had to manually copy + paste relay everything by hand, though the dispatches were now written with better context and were also adversarially reviewed. I couldn’t use Claude Code’s Agent Teams to spawn pairs with a non-Anthropic model and I didn’t trust the planners to use codex exec to launch their own adversarial reviewer, let alone the agents within the Agent Teams doing that themselves.

And, as always, tokens were now burning close to swarm-level rates, though mostly due to the increase in the number of distinct worker-pairs working simultaneously on non-overlapping work. This kept the token cost per task the same, and only looks to be more expensive in any given time period only because the number of tasks done grew.

However, over the course of running this for a week or so, several new delegation-specific failure points came up repeatedly:

1. Implementer agents were jumping the gun. Dispatches would typically be given to both the planner and implementer agents in the worker-pairs and, before the planner even started designing/planning, the implementer just read it as if it was directed to them. They sometimes started planning even AFTER I reminded them that their job was to review the planner’s work, or worse, they would sometimes treat it as a one-shot directive and go straight to implementing and opening PRs without any plans at all!

2. No direct way to facilitate cross domain context transfer. Each subservient worker-pair only had the context it gained on its own exploration and whatever the orchestrator passed down and had little to no idea of what its peer pairs were doing — they couldn’t communicate with one another without having to go through the orchestrator. Needless to say, this was also a huge burden on the orchestrator-planner agent.

3. The orchestrator-planner agent had inconsistent relays. Over different orchestrator instances and even within the same instance over time, the exact format of the relays varied wildly, and sometimes they would even leave out crucial information like the exact stage it was at or to whom it was addressed. It would also sometimes confuse itself over what pair was supposed to get what relay.

Overall, there is nothing new here, at least in terms of structure. A simple way to look at this orchestrator-team framework is just the pair but recursed: the same separation of authoring from reviewing, the same targeted distribution of context throughout specialized agents, applied to the act of handing work out rather than the act of doing it. Now, going back to Stage 6’s maxim of parallelizing reads and not writes, we have shown that we can also parallelize writes, though only partitioned writes as write collisions can’t really be fixed unless you wanted a copy of each file for each agent and then handle 5 different merge conflicts on each file — absolutely ludicrous.

The board

Problem	Status
Post-impl churn (PIC)	🟨 smallest it’s ever been — gates + scope shrink the ouroboros to a trickle, but stochastic agents mean it never fully closes
Coordination	🟨 no longer mine to hold — the orchestrator-pair owns routing, I’m on exceptions + merge — but I’m still the one hand-relaying between agents
Context fragmentation	🟩 ownership-partitioned bundles + reconciled status
Edit collisions	🟩 structural at team scale, via ownership decomposition
Mid-flight visibility	🟨 reopened — more agents in flight at once than I can watch
Token burn	🟨 orchestration adds overhead; by-exception engagement keeps it bounded
Correlated errors	🟨 review panels (Stage 6), yellow only due to below
Same-model review panel	🟨 still deferred — panels remain single-family; a third family still isn’t worth the tokens
Implementer jumping the gun	🟨 new — a dispatch is supposed to be context, not a start signal
Cross-pair context transfer	🟨 new — isolation’s flip side; pairs can’t share context with each other except by routing through the orchestrator, which overloads it
Inconsistent relays	🟨 new — the orchestrator-planner’s relays vary in format and sometimes drop crucial fields like the stage or who they’re addressed to
Orchestrator as single point of failure	🟨 new — everything gets routed through it and everything rides on this, mitigated somewhat by being paired with a reviewer but still a bit fragile

That board still had quite a few unresolved issues, and I wasn’t going to just end it here staring. The two that nagged at me most were coordination — I was still the one hand-relaying every dispatch between agents — and the freshly arrived delegation-specific failures the team’s structure had just introduced. Most of them, it turned out, were fixable. Here’s how the worst of them got closed.

Firstly, to address the issue of coordination, the handoffs/dispatches became files. Instead of having to /copy,⁹ and paste entire prompts that could potentially get mangled by latent issues with the TUI render, the agents could just write relays in a file and all I’d have to do is copy + paste the relay over to the recipient. Some unanticipated, but welcome, benefits came in the form of persistence and editability. Now, relays were actually easy to access and stored permanently as a markdown file, and I could also easily read and edit them through nvim. Additionally, agents now had a stable reference instead of keeping it ephemeral in their memory, further mitigating the context rot disaster.

Secondly, the handoffs got email-style headers. In order to enforce this without having to police every handoff myself, I loaded each agent with a mini-skill to preface its relays with an email-style header like

FROM:
TO:
CC:

and this actually solved two problems at once. The first issue solved was that the orchestrator now had to include information about, not only which pair the relay was for, but also which one of the pair it was directly for. This led nicely into the second issue fixed — the one of implementers jumping the gun. I reasoned that, since LLMs are probably trained on a bunch of email data, it would be able to understand that, if they were CC’d, it meant that they were only being kept in the loop without needing to respond. This hunch was right as, all of a sudden, the implementer agent stopped treating planning/design relays as signals for them to start.

Finally, standardized templates for relays were made, each with examples of what a relay of a sort should do. Like how a relay to audit should tell the agent READ ONLY or how a relay to plan/design would always have the implementation agent be CC’d and never be put as a direct recipient. This was an easy upgrade as now implementation agents could also just fill out a template rather than having to come up with one each time I asked.

Let’s take a look at the board now.

The board, again

Problem	Status
Post-impl churn (PIC)	🟨 smallest it’s ever been — gates + evidence + scope shrink the ouroboros to a trickle, but stochastic agents mean it never fully closes
Coordination	🟨 better — file-first relays kill the mangling and leave a persistent trail; still my copy-paste, but no longer fragile
Context fragmentation	🟩 ownership-partitioned bundles + reconciled status
Edit collisions	🟩 structural at team scale, via ownership decomposition
Mid-flight visibility	🟨 file-first relays + status reconciliation, but still too many agents to manually oversee each
Token burn	🟨 orchestration adds overhead; by-exception engagement keeps it bounded
Correlated errors	🟨 review panels (Stage 6), now standing, yellow only due to below
Same-model review panel	🟨 still deferred — panels remain single-family; a third family still isn’t worth the tokens
Implementer jumping the gun	🟩 closed — a CC’d agent stays in its lane, and acting now takes an explicit go-signal, not just a dispatch landing in its lap — so a hand-off stopped doubling as a cue to one-shot a PR
Cross-pair context transfer	🟨 better — addressing lets the orchestrator route peer context where it’s needed, but pairs still can’t reach each other directly
Inconsistent relays	🟩 closed — standardized templates; the format stopped drifting
Orchestrator as single point of failure	🟨 everything still routes through it and rides on it, mitigated by the reviewer but not gone

None of those three fixes were some ingenious invention. They all followed the same pattern: take a discipline that kept failing, and turn it into structure that holds whether or not anyone’s paying attention. Here’s why that works.

The failures above sort into two piles, split by the solutions for each.

The first pile is substantive: a wrong architecture, mismatching schemas, deviations from documentation, etc. Issues like these can be caught by just having a second set of eyes hunting for what’s wrong, and that’s pretty much the whole premise of the review gates from the last two stages where we just stacked mandatory adversarial review over pretty much every gate.

The second pile, the issues Stage 7 kept surfacing, is mechanical. That is, a failure of decorum and not correctness: an implementer misinterprets a doc meant for the planner as a go-signal for itself, a gate gets skipped because the agent assumes permission to skip it, or relays drop crucial fields that can compound the previous two problems. These issues were caused by the structure just being too loose and lax in its enforcement of decorum, and the fix is simple — just tighten it up. You could add a third reviewer to each pair to check relays but that’s inefficient and quite frankly overkill when a couple of persistent one-line rules enforcing behaviors (cough cough skills) would suffice.

As an aside, the fact that nearly every Superpowers cycle I’ve run had no issue with agents jumping steps was enough proof for me that just having a couple lines of markdown persisting as skills was enough to induce strict discipline, so I took this idea for myself.

By tightening the structure, the team regained and retained full structure throughout working sessions and I slowly got to trust the team’s ability to self-manage. Over time, the following lessons became apparent from the now disciplined and structured approach these teams were forced to take:

1. Permission should never be implied. The email headers were an example of this — an implementer mistaking being handed context for being told to build, and a CC’d agent learning to stay in its lane. But the stubborn version was me. So the act of going — actually writing code, actually merging — became something that only counts when it arrives as an explicit, unmistakable signal, and never something an agent should have to infer from a tone, a mood, or just the fact that a document landed in your lap. Eventually, due to other instances of assuming permissions — like going directly from a design doc into immediately writing a plan, merging after taking in just a single review without passing it back for a re-review, or checking off the task on the orchestrator owned roadmap as “done” (more on this in a bit) before it gets passed up there — this idea of making permissions clear, explicit, and persistent was extended to every single gate we had, from documents to merge confirmations.

2. “Done” became a claim, not a fact. The issue that’s been bugging me since the very beginning, the issue that motivated everything all the way back in Stage 1, was literally “Done” isn’t done. Now, we have a formal definition. Agents will tell you, with total serenity, that they did things they did not do — not lying exactly, just narrating the plausible. I recall several instances of the words “shipped” and “done” being tossed around to just describe a task completed within a PR without having been merged. So naturally, I had to define the word “done” to mean “merged cleanly” after the entire post-implementation review and fold cycle, and I required the implementer to provide evidence they had merged and the planning agent to verify it, and then the final state, again with all the evidence, was passed up to the orchestrator to finally check it off on the roadmap, as well as folding in any new findings from the agents. This discipline of evidence gradually expanded to other signifiers of completed actions; words like “done,” “fixed,” and “shipped” stopped being allowed to travel as bare words as each one has to arrive carrying what kind of proof stands behind it. The proof for “I changed the code” is the real state of the repository, not the agent’s summary of it. Still, that “done” was only ever dev-loop done — a claim promoted to a stronger tier of evidence, not proven correct in production; the last mile, QA and watching the deployed thing, stayed its own separate gate completely manned by me before it ever gets to prod.

3. Finally, sometimes you didn’t need all that pomp and circumstance. Not every single task needed to get involved with the level of ceremony of the full loop. Almost all of the time, it would be utterly ridiculous to run through an entire Superpowers cycle with the complete audit + design + plan + the independent review panel on a single line diff, let alone having to wire the relays all back and forth between the worker-pair, the orchestrator-pair, and me. Sometimes, especially with the introduction of new next-gen frontier models like Fable 5 (R.I.P.) that were essentially optimized for one-shotting, it was sufficient for the orchestrator just to produce a handoff and direct the agent to go ahead and one-shot; though the review gates after the PR gets created were still absolutely mandatory, especially so for these one-shot runs. What I’m getting at here is that, with sufficient evidence, the level of ceremony required to run through an entire task can be downgraded.

Roles

Role	Owns	Forbidden from
Orchestrator-planner (Opus 4.8)	decomposing work into ownership-partitioned bundles, dispatch, reconciling audits + status into the live spec/roadmap, the merge signal	writing code; reaching into a bundle’s internals; acting on its own decomposition unreviewed
Orchestrator-reviewer (GPT-5.5)	adversarially reviewing the orchestration itself — bundle boundaries, routing, framing, the order work has to land in	planning, implementing, or reviewing the pairs’ code — it only ever checks the hand-out
Agent-pairs (x2-5) — each a full Stage 6 setup	running the full Stage 6 cycle on one bundle, in isolation from its peers	touching another pair’s files; talking to a peer except through the orchestrator; merging its own work
Me	the exceptions, the light final review, the merge gate	real-time routing (the orchestrator holds it now); merging on vibes; treating “done” as a fact

Gates

1. Audit reconcile (orchestrator-planner + reviewer + me)
2. Spec + roadmap sign-off (orchestrator-reviewer + me)
3. Dispatch review — bundle ownership, routing, sequencing (orchestrator-reviewer + me)
4. The full Stage 6 cycle, run per bundle (inherited)
5. Final review + merge gate (orchestrator-planner + me)

Wiring

flowchart TD
    SPEC["Feature spec doc"]
    RESEARCH["Optional research<br/>prompt / doc"]
    YOU(["You<br/>exceptions + merge gate"])

    subgraph ORCH["Orchestrator pair"]
        ORCH_PLAN["Planner<br/>(Opus 4.8)"]
        ORCH_REVIEW["Reviewer<br/>(GPT-5.5)"]
        ORCH_PLAN <-->|"review"| ORCH_REVIEW
    end

    AUDITS["Agent-pairs<br/>audit codebase slices"]
    AUDIT_RECONCILE{"Audit reconcile"}
    ROADMAP[("Live spec + roadmap doc")]
    DISPATCH_REVIEW{"Dispatch review<br/>(ownership-partitioned)"}

    subgraph TEAM["Agent-pairs -- one per non-overlapping bundle (2-5 typical, scales out)"]
        PAIR_A["Pair A: bundle A<br/>(Stage 6 cycle, isolated)"]
        PAIR_B["Pair B: bundle B<br/>(Stage 6 cycle, isolated)"]
        PAIR_N["Pair N: bundle N<br/>(...as many as the work partitions into)"]
    end

    FINAL_REVIEW{"Light final review"}
    SHIP(["Merge / ship"])

    SPEC --> ORCH_PLAN
    SPEC -.->|"optional"| RESEARCH
    RESEARCH -.-> ORCH_PLAN

    ORCH_PLAN -->|"audit prompts"| AUDITS
    AUDITS -->|"audit docs"| AUDIT_RECONCILE
    AUDITS -.->|"discoveries"| ROADMAP
    AUDIT_RECONCILE -->|"spec + roadmap"| ROADMAP

    ROADMAP -->|"next items"| ORCH_PLAN
    ORCH_PLAN -->|"work prompts / docs"| DISPATCH_REVIEW
    ORCH_REVIEW -.-> DISPATCH_REVIEW
    YOU -.-> DISPATCH_REVIEW

    DISPATCH_REVIEW -->|"bundle A"| PAIR_A
    DISPATCH_REVIEW -->|"bundle B"| PAIR_B
    DISPATCH_REVIEW -->|"bundle N"| PAIR_N

    PAIR_A -->|"merge-ready PR"| FINAL_REVIEW
    PAIR_B --> FINAL_REVIEW
    PAIR_N --> FINAL_REVIEW
    TEAM -.->|"discoveries"| ROADMAP

    ORCH_PLAN -.-> FINAL_REVIEW
    YOU -.-> FINAL_REVIEW
    FINAL_REVIEW -->|"rework"| ORCH_PLAN
    FINAL_REVIEW -->|"merge signal"| SHIP

---

Previous: Part 2 — Parallelize Reads, Not Writes
Next: Part 4 — It’s Not an Engineer. It’s a Prosthesis.

In a hurry? Continue from this exact point in the complete edition.

The combined list of references and supplementary reading can be found here.

Image credits:

• coconut.jpg (Stage 7) — texture asset from Team Fortress 2 (Valve); cultural reference, removed on request.

Footnotes

1. The coconut file is real; the ‘deleting it crashes TF2’ story is the meme — the point here is tangled-code folklore, not the literal crash claim. ↩

2. Anthropic reported 76% on the 8-needle, 1M-token MRCR v2 benchmark for Opus 4.6 (vs 18.5% for Sonnet 4.5). Impressive, but still a one-in-four miss on a clean benchmark, before real-codebase messiness. ↩

3. Note Training a model — intentionally or not — to maximize a benchmark score rather than the underlying capability the benchmark is supposed to measure. ↩

4. Note The uncomfortable point isn’t that long-context models can’t retrieve anything; it’s that irrelevant surrounding context degrades retrieval AND reasoning. In codebases that maps painfully well to giant specs and whole-repo dumps. ↩

5. Caution HCA/CSA are real DeepSeek V4 compressed-attention mechanisms (building on the earlier NSA); I’m borrowing the shape, not claiming the architecture literally solves codebase context rot. In model terms they make very long context cheaper and more tractable; in my workflow analogy they become coarse global context plus selective mid-level detail plus exact local context. ↩

6. Yes, I know this doesn’t do the ingenious mechanism justice, and that it isn’t exactly sequential — HCA and CSA actually work together in tandem. But that’s a bit too complex for what this blog is going for; this isn’t a technical explanation of DeepSeek V4’s write-up, it’s how to vibecode properly!! ↩

7. Tip This was even more powerful when the chat model had access to the codebase itself via a GitHub integration. ↩

8. Though simple enough to skip a panel, a structural check turned out to be necessary — as it soon did. ↩

9. Or, even worse, manually selecting text when working through an ssh session — or just getting copy-to-clipboard to work in the first place. ↩