mirror of
https://github.com/gnekt/My-Brain-Is-Full-Crew.git
synced 2026-09-01 04:55:37 +00:00
Replace peer-to-peer agent messaging with centralized orchestration
Before this change, agents communicated directly with each other by writing to a shared file (Meta/agent-messages.md), following the protocol in references/inter-agent-messaging.md. This was fragile and hard to control. Now the dispatcher (CLAUDE.md) is the only coordinator. Agents do not talk to each other. Instead, when an agent detects work for another agent (e.g. missing vault structure, orphan notes), it outputs a "Suggested next agent" section. The dispatcher reads it, validates it against the agents-registry, and decides whether to chain the next agent. New files added: - references/agent-orchestration.md: the new coordination protocol, including call chain tracking, anti-recursion rules, and a max depth of 3 agents per user request - references/agents-registry.md: a capability registry that maps each agent to its inputs, outputs, and chaining suggestions Deleted: - references/inter-agent-messaging.md: the old peer-to-peer protocol
This commit is contained in:
gnekt
111
references/agent-orchestration.md
Normal file
111
references/agent-orchestration.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# 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. **Before each invocation**: add the agent to the chain
|
||||
3. **Pass the chain**: tell the agent its position — `"Call chain: [scribe, architect]. You are step 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 write to other agents' files** — 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
|
||||
36
references/agents-registry.md
Normal file
36
references/agents-registry.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Agent Registry
|
||||
|
||||
This file is the **single source of truth** for all active agents in the crew. The dispatcher (`CLAUDE.md`) and all agents reference this file for routing decisions and inter-agent coordination.
|
||||
|
||||
The registry is designed to grow: custom agents (see Issue #12) are added as new rows following the same schema.
|
||||
|
||||
---
|
||||
|
||||
## Registry
|
||||
|
||||
| Name | Role | Capabilities | Input | Output | Status |
|
||||
|------|------|-------------|-------|--------|--------|
|
||||
| architect | Vault Structure & Governance | Create/modify folders, templates, MOCs, tag taxonomy, naming conventions. Full Bash access. Runs onboarding. | Vault setup, new areas/projects, structural changes, defrag, onboarding | Folders created, templates defined, structure updated, MOCs generated | active |
|
||||
| scribe | Text Capture & Refinement | Create notes in `00-Inbox/`, format raw text, handle voice-to-note, brainstorm, quotes, reading notes | Raw text, ideas, thoughts, voice input, quotes, brainstorm requests | Structured notes in `00-Inbox/` with frontmatter, tags, suggested connections | active |
|
||||
| sorter | Inbox Triage & Filing | Move notes from inbox to correct locations, update MOCs, batch processing | Inbox triage, filing requests, note organization | Notes moved to correct folders, MOCs updated, triage reports | active |
|
||||
| seeker | Search & Intelligence | Full-text search, metadata queries, relationship navigation, answer synthesis. Read-only by default. | Search queries, "find X", "where did I put", factual questions about vault content | Search results with citations, synthesized answers, knowledge gap reports | active |
|
||||
| connector | Knowledge Graph & Link Analysis | Add/edit wikilinks, analyze graph structure, discover connections, bridge notes | Link analysis, "find connections", graph health, serendipity requests | New wikilinks added, graph health score, connection maps, bridge notes | active |
|
||||
| librarian | Vault Health & Quality Assurance | Detect/merge duplicates, fix broken links, audit frontmatter, growth analytics. Full Bash access. | Maintenance, audit, cleanup, health check, duplicate detection | Health reports, fixed links, merged duplicates, consistency reports | active |
|
||||
| transcriber | Audio & Meeting Intelligence | Process transcriptions into structured notes, extract action items, speaker detection | Audio recordings, transcriptions, meeting notes, lecture/podcast processing | Structured meeting/lecture notes in `00-Inbox/` with action items, decisions, topics | active |
|
||||
| postman | Email & Calendar Intelligence | Read Gmail, search emails, read/create calendar events, draft replies. Uses MCP connectors. | Email triage, calendar queries, deadline tracking, meeting prep, VIP filtering | Email summaries saved as notes in `00-Inbox/`, calendar events created, deadline reports | active |
|
||||
|
||||
---
|
||||
|
||||
## Status Values
|
||||
|
||||
- **active**: Agent is operational and available for dispatch
|
||||
- **disabled**: Agent is temporarily disabled — the dispatcher will skip it
|
||||
|
||||
---
|
||||
|
||||
## How This File Is Used
|
||||
|
||||
1. **Dispatcher** reads the `Input` column to match user messages to agents
|
||||
2. **Dispatcher** reads `Output` + `Capabilities` of other agents to decide if chaining is needed after an agent returns
|
||||
3. **Agents** reference this file when suggesting next agents in their output
|
||||
4. **Custom agents** (Issue #12) are added as new rows — no code changes needed
|
||||
@@ -4,6 +4,12 @@ This reference is shared across all agents. Every agent knows the others, their
|
||||
|
||||
---
|
||||
|
||||
## Agent Registry
|
||||
|
||||
For the definitive list of agents with capabilities, inputs, outputs, and status, see `.claude/references/agents-registry.md`. That file is the single source of truth — it supports both core and custom agents.
|
||||
|
||||
---
|
||||
|
||||
## Language Rule
|
||||
|
||||
**All agents respond in the user's language.** Match the language the user writes in. If the user switches languages mid-conversation, switch with them.
|
||||
@@ -109,3 +115,5 @@ All agents read `Meta/user-profile.md` for personalization. This file is created
|
||||
| "Need to find an existing note" | Seeker |
|
||||
| "Cross-reference this with email" | Postman |
|
||||
| "This came from a meeting recording" | Transcriber |
|
||||
|
||||
**How agents coordinate**: Agents do NOT communicate directly. When an agent detects work for another agent, it includes a `### Suggested next agent` section in its output. The dispatcher reads this and decides whether to chain the next agent. See `.claude/references/agent-orchestration.md` for the full protocol.
|
||||
|
||||
@@ -1,182 +0,0 @@
|
||||
# Inter-Agent Messaging Protocol
|
||||
|
||||
This document defines how agents communicate with each other asynchronously through the vault's shared message board at `Meta/agent-messages.md`.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Every agent has **two mandatory steps** that wrap every task:
|
||||
|
||||
1. **Before starting any task** — read `Meta/agent-messages.md`, check for messages addressed to you, and resolve any pending items first.
|
||||
2. **During a task, when encountering uncertainty or problems** — leave a message for the appropriate agent in `Meta/agent-messages.md`.
|
||||
|
||||
This creates a lightweight coordination layer that lets agents help each other without requiring the user to manually coordinate between them.
|
||||
|
||||
---
|
||||
|
||||
## The Message Board File
|
||||
|
||||
### Location
|
||||
`Meta/agent-messages.md`
|
||||
|
||||
### Format
|
||||
|
||||
```markdown
|
||||
# Agent Message Board
|
||||
|
||||
<!-- Messages are listed newest-first. Resolved messages are marked with a checkmark and kept for 7 days, then archived by the Librarian. -->
|
||||
|
||||
---
|
||||
|
||||
## [pending] [YYYY-MM-DD] FROM: {{AgentName}} -> TO: {{AgentName}}
|
||||
**Subject**: {{Brief subject line}}
|
||||
|
||||
**Context**: {{What I was doing when I encountered this}}
|
||||
|
||||
**Problem**: {{What I don't know or can't resolve}}
|
||||
|
||||
**My Proposed Solution**: {{What I think should be done — always include a suggestion}}
|
||||
|
||||
**Impact if unresolved**: {{What I did instead / what I left pending}}
|
||||
|
||||
---
|
||||
|
||||
## [resolved] [YYYY-MM-DD] FROM: {{AgentName}} -> TO: {{AgentName}}
|
||||
**Subject**: {{Brief subject line}}
|
||||
|
||||
**Resolution**: {{What was decided / done}}
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step: How to Use the Message Board
|
||||
|
||||
### Step 1: Read Your Messages (Always First)
|
||||
|
||||
At the start of **every task**, before doing anything else:
|
||||
|
||||
1. Read `Meta/agent-messages.md`
|
||||
2. Look for messages with `-> TO: {{YourAgentName}}` that are marked `[pending]`
|
||||
3. For each pending message addressed to you:
|
||||
- Read the full message
|
||||
- Act on it (make the structural change, answer the question, create the folder, etc.)
|
||||
- Mark the message as resolved by changing `[pending]` to `[resolved]` and adding a **Resolution** line
|
||||
4. Once all your pending messages are resolved, proceed with the user's task
|
||||
|
||||
If `Meta/agent-messages.md` doesn't exist yet, create it with the header and an empty state:
|
||||
|
||||
```markdown
|
||||
# Agent Message Board
|
||||
|
||||
<!-- Messages are listed newest-first. Resolved messages are marked [resolved] and kept for 7 days, then archived by the Librarian. -->
|
||||
|
||||
*(No messages yet)*
|
||||
```
|
||||
|
||||
### Step 2: Leave Messages When You Need Help
|
||||
|
||||
During your task, if you encounter a situation where:
|
||||
- You don't know where something should go
|
||||
- You're unsure about a structural decision
|
||||
- You find a problem that another agent should fix
|
||||
- You have a suggestion for improving how something is organized
|
||||
|
||||
**Append a message to `Meta/agent-messages.md`** addressed to the right agent.
|
||||
|
||||
Always include:
|
||||
- **Your name** as sender
|
||||
- **The recipient agent's name**
|
||||
- **Context**: what you were doing
|
||||
- **Problem**: what you're uncertain about
|
||||
- **Your proposed solution**: never just report a problem — always suggest what you think should be done
|
||||
- **What you did in the meantime**: what action you took (or didn't take) while waiting for a response
|
||||
|
||||
### Step 3: Continue Your Task
|
||||
|
||||
After leaving a message, don't block — continue with the rest of your task. Either:
|
||||
- Apply your proposed solution provisionally (and note this in the message)
|
||||
- Skip the uncertain item and note it in your report to the user
|
||||
- Handle the simple case and flag the edge case for the appropriate agent
|
||||
|
||||
---
|
||||
|
||||
## Message Writing Rules
|
||||
|
||||
1. **Always propose a solution** — never just say "I don't know". Say "I don't know, but I think we should do X because Y."
|
||||
2. **Be specific** — mention the exact note title, folder path, or tag involved
|
||||
3. **One message per issue** — don't bundle unrelated problems in one message
|
||||
4. **Stay professional** — messages are part of the vault's knowledge system
|
||||
5. **Don't be noisy** — only leave messages for genuine uncertainties, not every minor decision
|
||||
6. **Include enough context** — the recipient agent should be able to act without asking follow-up questions
|
||||
|
||||
---
|
||||
|
||||
## When to Leave a Message vs. When to Decide
|
||||
|
||||
**Leave a message** when:
|
||||
- The decision affects the overall vault structure (new folder, new area, new tag category)
|
||||
- The decision might conflict with work another agent is doing
|
||||
- You've encountered the same uncertainty more than once
|
||||
- The decision has long-term implications for how the vault is organized
|
||||
|
||||
**Decide on your own** when:
|
||||
- It's a minor, local choice with no structural implications
|
||||
- The vault conventions clearly cover this case
|
||||
- You can easily reverse the decision if needed
|
||||
- It would cause significant delay to wait for a response
|
||||
|
||||
---
|
||||
|
||||
## Agent Name Reference
|
||||
|
||||
Use these names in messages:
|
||||
|
||||
| Agent | Use in messages |
|
||||
|-------|----------------|
|
||||
| Architect | `FROM/TO: Architect` |
|
||||
| Scribe | `FROM/TO: Scribe` |
|
||||
| Sorter | `FROM/TO: Sorter` |
|
||||
| Seeker | `FROM/TO: Seeker` |
|
||||
| Connector | `FROM/TO: Connector` |
|
||||
| Librarian | `FROM/TO: Librarian` |
|
||||
| Transcriber | `FROM/TO: Transcriber` |
|
||||
| Postman | `FROM/TO: Postman` |
|
||||
|
||||
---
|
||||
|
||||
## Example Messages
|
||||
|
||||
### Example 1: Sorter -> Architect (structural gap)
|
||||
|
||||
```markdown
|
||||
## [pending] [2026-03-20] FROM: Sorter -> TO: Architect
|
||||
**Subject**: No area for "Personal Finance" notes
|
||||
|
||||
**Context**: While triaging the inbox, I found 3 notes about personal budgeting, monthly expenses, and savings goals.
|
||||
|
||||
**Problem**: No folder exists in `02-Areas/` for personal finance. Existing areas are: Engineering, Marketing, Sales, HR. These notes don't belong to any of them.
|
||||
|
||||
**My Proposed Solution**: Create `02-Areas/Personal Finance/` with an index.md and a dedicated MOC. The 3 notes could live there. Alternatively, if finance is considered too personal for "areas of responsibility", a dedicated category could be created.
|
||||
|
||||
**Impact if unresolved**: I temporarily placed the 3 notes in `03-Resources/Finance/` as a provisional solution. If the Architect creates the dedicated area, they can be moved.
|
||||
```
|
||||
|
||||
### Example 2: Resolution
|
||||
|
||||
```markdown
|
||||
## [resolved] [2026-03-21] FROM: Sorter -> TO: Architect
|
||||
**Subject**: No area for "Personal Finance" notes
|
||||
|
||||
**Resolution**: Created `02-Areas/Personal Finance/` with index.md and `MOC/Personal Finance.md`. Tag taxonomy updated with `#area/personal-finance`. Notes in `03-Resources/Finance/` can be moved by the Sorter in the next session.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Message Retention Policy
|
||||
|
||||
- **[pending] messages**: stay until resolved
|
||||
- **[resolved] messages**: kept for 7 days, then removed by the Librarian during weekly maintenance
|
||||
- **Archived messages**: moved to `Meta/agent-message-archive/{{YYYY-MM}}.md` by the Librarian
|
||||
Reference in New Issue
Block a user