mirror of
https://github.com/gnekt/My-Brain-Is-Full-Crew.git
synced 2026-09-10 07:46:20 +00:00
a7e5625250
- Fix call-chain example consistency in CLAUDE.md and agent-orchestration.md (chain lists already-invoked agents, "step N" matches chain length + 1) - Renumber architect.md Task Checklist (was skipping 3) and replace "Leave messages" step with dispatcher-driven "Suggested next agent" - Replace "Leave a message to the Sorter" with signal via Suggested next agent - Clarify "Do NOT write to other agents' files" → only prompt/config files (.claude/agents/*.md), normal vault edits still allowed - Fix agent count 10→8 in docs/getting-started.md - Initialize SKILL_COUNT before conditional block in launchme.sh
112 lines
4.5 KiB
Markdown
112 lines
4.5 KiB
Markdown
# 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:
|
|
|
|
```markdown
|
|
### 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
|
|
|
|
```markdown
|
|
### 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.
|
|
```
|
|
|
|
```markdown
|
|
### 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
|