Hierarchies & Teams

d:spatch supports multi-level agent hierarchies. Agents are organized in supervisor/worker trees of arbitrary depth, enabling delegation, specialization, and structured coordination.

Supervisors and workers

The distinction is simple:

• A supervisor is any agent that has sub_agents defined.
• A worker is a leaf node — an agent with no sub-agents.

Supervisors can delegate tasks to their sub-agents via talk_to, receive escalated inquiries from sub-agents, and orchestrate multi-step workflows. Workers focus on execution — writing code, running tests, performing reviews, or any other concrete task.

Defining a hierarchy

Hierarchies are declared in the agents section of dspatch.workspace.yml. Nesting agents under sub_agents establishes the supervisor/worker relationship:

agents:
  lead:
    template: project-manager
    auto_start: true
    sub_agents:
      backend:
        template: claude-code
        sub_agents:
          db-migration:
            template: claude-code
      frontend:
        template: claude-code

This creates a three-level hierarchy:

• lead supervises backend and frontend
• backend supervises db-migration
• frontend and db-migration are workers (leaf nodes)

Auto-start behavior

The auto_start flag controls whether an agent starts automatically when the workspace launches. Typically, only the root agent sets auto_start: true. Sub-agents remain idle until their supervisor delegates work to them via talk_to.

agents:
  lead:
    template: project-manager
    auto_start: true    # starts when workspace launches
    sub_agents:
      coder:
        template: claude-code
        auto_start: false   # waits for delegation

Peers

Agents can also have lateral peers — agents at the same level they can communicate with directly, outside the supervisor/worker relationship. Peers are declared as a list of agent names:

agents:
  lead:
    template: project-manager
    auto_start: true
    sub_agents:
      backend:
        template: claude-code
        peers: [frontend]
      frontend:
        template: claude-code
        peers: [backend]

Here, backend and frontend can talk_to each other directly without routing through their supervisor. This is useful when agents need to coordinate without involving the parent — for example, a frontend agent asking the backend agent about API contracts.

Communication flow

Within a hierarchy, communication follows these rules:

• Downward: supervisors can always talk_to their sub-agents.
• Upward: workers can always respond to their supervisor, but talk to them only when registered as a peer.
• Lateral: agents can talk_to their declared peers.
• Cross-tree: agents cannot communicate with agents they have no relationship with.

For more details on how agents exchange messages, see Inter-Agent Communication.