Team Topology

Team topology

A method for defining a multi-agent team for a task as an explicit topology: not "spawn some agents" but a legible deployment you can draw, hand off, and reason about. Who runs where, who talks to whom, what each node can touch, which model sits in which seat. Substrate-agnostic: the same method applies to a Cotal mesh, harness subagents, workflow stages, or plain processes.

When to use

• The user asks to define / design / lay out a team or formation, or asks "what topology?".
• You are about to stand up more than one or two agents and want them arranged deliberately.
• You need to communicate a running deployment in a scannable form.

Step 1: pick the shape from the dominant risk

A topology is a defense against the way the task fails by default. Name the task's dominant risk, then pick the shape that structurally prevents it:

This catalog is a starting set, not a menu. Hybrids are normal (an audit's repro tier is a small pipeline), and inventing a shape for the task at hand is expected. The number of channels, tiers, and agents is a free parameter: derive it from the task's size, risk, and budget (a quick check might be 1 channel / 2 agents; a deep audit 4 channels / 10). Never copy a previous deployment's headcount out of habit.

Every shape keeps one coordinator: the single node that spans the whole topology, holds the consolidated state, and owns final decisions. Usually that is you, the main session.

Step 2: specify three layers

Survey the live substrate state first - topologies rarely deploy onto a blank slate:

• Who is already up. Roster / process list / task list: live peers from earlier generations, stale managers or supervisors, orphaned nodes. Decide per node: reuse, stop, or ignore - never assume greenfield, and never let a stale sibling silently share a channel with the new team.
• Channel/stream state. Does each channel already exist, and what do its history/replay semantics do to a NEW joiner - does joining backfill old traffic into their context? Replay into a fresh blind reviewer contaminates the lane; replay into a resuming coordinator may be exactly right. Choose fresh vs reused channels deliberately and set the replay/backfill mode per channel as part of the design, not as a discovered surprise.
• Names. Check for collisions against live AND dead/retired nodes. On substrates where teardown races or stale state can bleed onto a same-name successor, a dead name is not reusable - mint fresh generation-suffixed names.

Then specify the three layers:

1. Runtime: what actually executes each node (mesh peers as OS processes, harness subagents, workflow stages, containers) and the facts someone would otherwise assume wrong: shared vs isolated filesystem, one broker or many, per-node credentials or shared, where each node is rooted.
2. Communication: the edges. One channel/stream per team; point-to-point for private lanes; files/artifacts for pipeline handoffs. Name channels <purpose>.<task> (review.control-surface, fix.billing). State which nodes sit on which edge, and that no one else does.
3. Trust: what each node can read and write, enforced by mechanism, not by request: ACL-scoped credentials, read-only roles, isolated worktrees/sandboxes, a single merge authority. If a node must not edit, fence it so it cannot, and name the fence.

Step 3: place capability by lane

First, enumerate what actually exists - never fill a seat from memory. Before naming any model, look up the harnesses, providers, model IDs, and variant/effort levels available in the current environment, and cite where each came from. A seat naming a model that does not exist (a misremembered ID, a variant the provider doesn't offer, a "default" left unspecified) invalidates the proposal. Sources to check, in order:

• Existing persona/agent definitions that have actually run (e.g. .cotal/agents/*.md model:/variant: frontmatter, .claude/agents/*.md) - ground truth for IDs that work on this machine.
• Harness/provider config (e.g. ~/.config/opencode/opencode.json provider blocks with model IDs, limits, and their exact variants; connector configs) for what is wired up.
• The harness's own listing when one exists (e.g. opencode models).

Every seat gets an explicit model + variant; "default" is not a placement. If the user names a preference pool or per-provider caps (e.g. "at most N of provider X"), treat those as hard constraints and show the resulting counts.

Models are not uniform, and no vendor is assumed. Fill each seat by strength class, with whatever vendor/model best provides it in the current environment: adversarial-strong on attack/verify lanes, code-strong on implementation and deep review, research-capable on spec/fidelity lanes, fast-and-cheap on mechanical or high-fan-out runs. Two deliberate reasons to mix vendors across lanes: independent lanes on different vendors have less-correlated blind spots (a diversity mechanism, especially for verify tiers), and no single provider outage or rate limit stalls the whole team. Present placement as a table so it is auditable, and note any per-node override of a persona/stage default: