My-Brain-Is-Full-Crew/references/agent-orchestration.md

Agent Orchestration Protocol

This document defines how agents coordinate through the dispatcher (CLAUDE.md). Agents do NOT communicate directly with each other — the dispatcher handles all routing and chaining.

---

Overview

The dispatcher is a reactive multi-router:

1. User sends a message → dispatcher picks the best agent by priority
2. Agent executes → returns output to the dispatcher
3. Dispatcher reads the output → decides if another agent should be chained
4. Repeat until done or max depth reached

Agents help the dispatcher by including suggestions in their output when they detect work for other agents.

---

How Agents Signal the Dispatcher

When an agent detects work that another agent should handle, it includes a section at the end of its output:

### Suggested next agent
- **Agent**: {name from agents-registry.md}
- **Reason**: {what needs to be done and why}
- **Context**: {relevant details the next agent would need — note titles, folder paths, specific issues}

Multiple suggestions are allowed — list them all. The dispatcher prioritizes and decides which (if any) to invoke.

Examples

### Suggested next agent
- **Agent**: architect
- **Reason**: No area exists for "Personal Finance" — 3 notes were placed in Inbox as fallback
- **Context**: Notes: "Monthly Budget March.md", "Savings Goals.md", "Expense Tracking.md". Suggest creating 02-Areas/Personal Finance/ with sub-folders and MOC.

### Suggested next agent
- **Agent**: connector
- **Reason**: 5 recently filed notes about "Machine Learning" have no cross-links
- **Context**: Notes in 03-Resources/Technology/ML/. They reference shared concepts (gradient descent, neural networks) but have zero wikilinks between them.

### Suggested next agent
- **Agent**: architect
- **Reason**: MOC for Machine Learning is missing
- **Context**: There are now 8 notes under this topic but no MOC in MOC/ folder.

---

Dispatcher Decision Logic

After each agent returns, the dispatcher:

1. Reads the output — looks for ### Suggested next agent sections
2. Consults agents-registry.md — validates the suggested agent exists and is active
3. Checks the call chain — is this agent already in the chain? Is max depth reached?
4. Decides: invoke next agent OR return results to user

The dispatcher can also chain agents without an explicit suggestion if the output clearly matches another agent's capabilities (e.g., notes created → Sorter might be needed).

---

Call Chain Tracking

Every user request has a call chain — the ordered list of agents invoked so far.

Rules

1. Start: chain is empty []
2. After each agent returns: append its name to the chain (the chain always lists agents already invoked, in order)
3. Pass the chain: when invoking the next agent, tell it the chain and its position — "Call chain so far: [scribe, architect]. You are step 3 of max 3."
4. No duplicates: never invoke the same agent twice in one chain
5. No circular patterns: if Agent A suggests Agent B and B is already in the chain, skip
6. Max depth: 3: no more than 3 agents per user request
7. On overflow: return results to user with a note about what was deferred

What Happens at Max Depth

If the dispatcher would need a 4th agent, it:

• Returns the current results to the user
• Includes a summary of what was deferred: "The Connector also detected 5 orphan notes that need linking — you can say 'connect the notes' to handle that."

---

What Agents Should NOT Do

• ❌ Do NOT reference Meta/agent-messages.md — the shared message board is deprecated
• ❌ Do NOT edit other agents' prompt/config files (e.g., .claude/agents/*.md) — normal vault notes/MOC edits are still allowed per your responsibilities; all coordination goes through the dispatcher
• ❌ Do NOT block waiting for another agent — finish your task and suggest next steps in your output
• ❌ Do NOT call other agents — only the dispatcher invokes agents

---

Migration from Legacy System

If a vault still has the old Meta/agent-messages.md file:

• The Librarian will rename it to Meta/agent-messages-DEPRECATED.md during maintenance
• Agents should ignore this file entirely — all coordination now flows through the dispatcher

---

Reference Files

• Agent registry: .claude/references/agents-registry.md — the single source of truth for all agents
• Agent directory: .claude/references/agents.md — detailed descriptions of each agent's responsibilities