mdd
DocsUse CasesGitHubOpen App

Orchestration maps for multi-agent systems

Agent builders wire orchestrators, subagents, tools, and memory — and the wiring changes weekly. An mdd orchestration map is agent-native documentation: the JSON model is ground truth the system itself can read and update, and the ASCII renders in the README, the context file, and the terminal.

Open AppRead the Docs

An orchestrator and its subagents

An orchestrator dispatching to three subagents inside a cluster boundary, with shared memory and a tool sandbox below. The JSON beside it is what your agent edits when the wiring changes.

<!-- mdd:begin id=agents src=docs/agents.diagram.json -->
```

                        ┌──────────────┐
                        │ Orchestrator │
                        └───────┬─────▲┘
            ┌───────────────────┤  verdict──┐
            │                   │     └─────┤
 ┌┄ subagents ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
 ┆ ┌────────▼───────┐   ┌───────▼──────┐   ┌▼─────────────┐ ┆
 ┆ │ Research Agent │   │ Coding Agent │   │ Review Agent │ ┆
 ┆ └────────▲───────┘   └───────┬──────┘   └──────────────┘ ┆
 └┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
            │                   │
            │                   │
    ┌───────▼───────┐   ┌───────▼──────┐
    │ Shared Memory │   │ Tool Sandbox │
    └───────────────┘   └──────────────┘

```
[diagram source](docs/agents.diagram.json)
<!-- mdd:end -->

The model your agent edits

{
  "version": 1,
  "boxes": [
    {
      "id": "orchestrator",
      "label": "Orchestrator",
      "row": 0,
      "connections": [
        {
          "to": "researcher",
          "arrow": "to"
        },
        {
          "to": "coder",
          "arrow": "to"
        },
        {
          "to": "reviewer",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "researcher",
      "label": "Research Agent",
      "row": 1,
      "connections": [
        {
          "to": "memory",
          "arrow": "both"
        }
      ]
    },
    {
      "id": "coder",
      "label": "Coding Agent",
      "row": 1,
      "connections": [
        {
          "to": "sandbox",
          "arrow": "to"
        }
      ]
    },
    {
      "id": "reviewer",
      "label": "Review Agent",
      "row": 1,
      "connections": [
        {
          "to": "orchestrator",
          "arrow": "to",
          "label": "verdict"
        }
      ]
    },
    {
      "id": "memory",
      "label": "Shared Memory",
      "row": 2
    },
    {
      "id": "sandbox",
      "label": "Tool Sandbox",
      "row": 2
    }
  ],
  "clusters": [
    {
      "id": "workers",
      "label": "subagents",
      "members": [
        "researcher",
        "coder",
        "reviewer"
      ]
    }
  ]
}

Your agent draws it, you review it

  1. Model the orchestration — agents, hand-offs, tools, memory — as JSON in the repo.
  2. Splice the map into your README or AGENTS.md with mdd render.
  3. When you add an agent or rewire a hand-off, your agent edits the JSON and re-renders.
  4. mdd check in CI fails when the map goes stale relative to the model.

A prompt to hand your agent

Maintain the orchestration map in AGENTS.md with mdd. When agents, tools, or hand-offs change, edit docs/agents.diagram.json, then run: npx mdd render --json docs/agents.diagram.json --file AGENTS.md --id agents.

Why mdd here

A multi-agent system is the most agent-native thing there is to document — the maintainer of the diagram can be the system it describes. mdd gives it a structured model with a validation loop instead of a hand-drawn sketch, cluster boxes group the subagent pool, and the output reads identically in every terminal and diff.

More use cases