diff --git a/references/agent-orchestration.md b/references/agent-orchestration.md new file mode 100644 index 0000000..5f0710d --- /dev/null +++ b/references/agent-orchestration.md @@ -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 diff --git a/references/agents-registry.md b/references/agents-registry.md new file mode 100644 index 0000000..581b31f --- /dev/null +++ b/references/agents-registry.md @@ -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 diff --git a/references/agents.md b/references/agents.md index 75a28d7..043e01b 100644 --- a/references/agents.md +++ b/references/agents.md @@ -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. diff --git a/references/inter-agent-messaging.md b/references/inter-agent-messaging.md deleted file mode 100644 index 0a6f9c3..0000000 --- a/references/inter-agent-messaging.md +++ /dev/null @@ -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 - - - ---- - -## [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 - - - -*(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