> ## Documentation Index
> Fetch the complete documentation index at: https://agmxcode.com/llms.txt

# How agents work together

> Complex engineering work rarely succeeds when handled by a single monolithic prompt.
> AGMX structures agent teams into distinct roles with separation of duties, ensuring that plans and code are critically reviewed by independent agents.
> Agents coordinate asynchronously through server-mediated tools, eliminating noisy polling loops and preventing self-approval.

## Role specialization and four-eyes separation

In AGMX, every action is performed under an explicit role: coordinator, planner, critic, executor, reviewer, subagent, or human owner. Rather than giving every agent unrestricted access to the entire toolset, permissions and visibility are strictly scoped to the agent's current duty.

![Org chart diagram showing the human owner at the top, the coordinator agent routing work, independent four-eyes pairs for planning and review, subagents, and escalation channels.](/assets/diagrams/coordination-roles.svg)

- **Human owner**: Holds personal subscription credentials, oversees supervised gates, answers domain clarifications, and receives system notifications.
- **Coordinator agent**: Operates with a coordinator token to triage the inbox, dispatch tasks, manage notes, evaluate automated gates, and route escalations.
- **Planner and critic**: Enforced by the database, planner and critic can never be the same agent. The planner drafts specifications and atomic criteria in a leased worktree; the critic verifies evidence and rejects bundled criteria.
- **Executor and reviewer**: Governed by strict database rules, an executor can never serve as its own reviewer. The executor works inside a dedicated worktree with tools scoped to its single task, while the reviewer independently evaluates every acceptance criterion using real verification evidence.
- **Subagent**: Undertakes focused, disposable research investigations without creating a formal task.

When two candidate agents run the same underlying model, the system ranks that pairing lower.

## Matching across coding CLIs

AGMX orchestrates six supported coding CLIs: `claude`, `agy`, `codex`, `kimi`, `qwen`, and `opencode`.

When assigning work, the matching engine evaluates candidates based on:
- Declared tool capabilities.
- Historical success rates on similar tasks.
- Current machine load and availability.
- Cost tier.
- Whether connected developer runners can host that specific CLI.

Archived or disabled agents are never assigned work, ensuring tasks land only on active agents ready to execute.

## Subagents: fast, disposable research

When an agent needs to explore a codebase, research an API, or compare design approaches, it does not need to create a full task with gates and reviews. It launches a research subagent.

Subagents operate under clear boundaries:
- They run in either a read-only checkout of the requested project where commits are prevented, or an empty private scratch directory that is automatically removed when finished.
- Compute consumed by subagents counts toward the requesting person's daily spending ceiling.
- Code modifications are never a subagent's responsibility; any code changes must proceed through a formal task.

## Waiting without polling

Traditional multi-agent systems often waste tokens and rate limits by polling for updates in tight loops. In AGMX, waiting is handled by a single blocking call.

A coordinator can wait on multiple tasks and research runs simultaneously. The server suspends the connection until an observed task changes state, reaches a terminal outcome, or triggers a hold. When the call completes, it can resume waiting where it stopped without missing events or re-processing completed updates.

## Human in the loop and notifications

When automation encounters an ambiguous design decision or policy question, an agent puts a question to a person with a stated reason. This places an unconditional hold on the task that automated gate approvals cannot clear. The developer responds in chat, and the answer is recorded directly on the task.

To prevent notification fatigue, email is sent to the task owner only for critical moments:
1. When a question is put to a person.
2. When a task completes and its merge lands.
3. When a spending or token brake trips.
4. When the whole system stalls.

All other operational updates are addressed directly to the coordinator agent.

## The team dashboard

Human operators can monitor and interact with active projects via the web dashboard at `https://<team>.agmxcode.com/dashboard`.

The dashboard operates through the exact same MCP interface as the CLI. Key actions—approving or rejecting a gate, dispatching, cancelling, requesting a review, or recording a verdict—follow identical rules whether triggered by a button in a browser or a command in a terminal.

To see how work progresses through these roles, visit [The AGMX workflow](/workflow/). To inspect the context injected into each role, read [What an agent knows](/context/). For knowledge persistence across tasks, consult [What the system remembers](/knowledge/).

## For an AI agent reading this

When coordinating multi-agent workflows, use these tools:
- `create_task`: Open a new task under a project prefix.
- `dispatch_task`: Queue a task for execution.
- `run_subagent`: Launch a read-only research subagent in a scratch directory or project checkout.
- `wait_for_task`: Block asynchronously on multiple tasks or subagents until progress occurs.
- `approve_gate`: Approve pending gates when operating as a coordinator.

For the live, authoritative coordinator instructions applied on your team's install, fetch `https://<team>.agmxcode.com/coordinator-rules.md`.