From 0fb773f745d7e47f9915600b6cc82676d4ee00b8 Mon Sep 17 00:00:00 2001 From: gnekt Date: Mon, 23 Mar 2026 16:08:40 +0100 Subject: [PATCH] Add custom agent support to orchestration references agents-registry.md: - Added "Custom Agents" section with rules for how custom agents are added to the registry (naming, priority, creation flow) - Custom agents always have lower priority than core 8 - Names must be lowercase with hyphens, no conflicts with core names agents.md: - Added "Custom Agents" section explaining what they are, how they coordinate with core agents, and how to create/edit/remove them agent-orchestration.md: - Added "Suggested new agent" signal format so agents can flag when the user needs functionality that no existing agent provides - Added step in Dispatcher Decision Logic to check for this signal - Added "Custom Agent Lifecycle" section covering creation, discovery, routing, chaining, maintenance, and deletion --- references/agent-orchestration.md | 31 ++++++++++++++++++++++++++++++- references/agents-registry.md | 25 ++++++++++++++++++++++++- references/agents.md | 26 ++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 2 deletions(-) diff --git a/references/agent-orchestration.md b/references/agent-orchestration.md index ffbc778..df9238a 100644 --- a/references/agent-orchestration.md +++ b/references/agent-orchestration.md @@ -51,6 +51,21 @@ Multiple suggestions are allowed — list them all. The dispatcher prioritizes a - **Context**: There are now 8 notes under this topic but no MOC in MOC/ folder. ``` +### Suggesting a New Agent + +When an agent detects that the user needs functionality that no existing agent provides, it can suggest creating a new custom agent: + +```markdown +### Suggested new agent +- **Need**: {what capability is missing} +- **Reason**: {why no existing agent can handle this} +- **Suggested role**: {brief description of what the new agent would do} +``` + +The dispatcher reads this and may invoke the **Architect** to start the custom agent creation flow. This is NOT automatic. The dispatcher should confirm with the user first: + +> "The [agent] noticed you might benefit from a custom agent for [need]. Would you like me to create one?" + --- ## Dispatcher Decision Logic @@ -60,7 +75,8 @@ 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 +4. **Checks for `### Suggested new agent`** -- if present, asks the user if they want the Architect to create a custom agent +5. **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). @@ -88,6 +104,19 @@ If the dispatcher would need a 4th agent, it: --- +## Custom Agent Lifecycle + +Custom agents are created by the Architect and stored in `.claude/agents/`. They participate fully in the orchestration system: + +1. **Creation**: the Architect creates the agent file, adds a row to `agents-registry.md`, and updates `agents.md` +2. **Discovery**: Claude Code auto-discovers the agent from its frontmatter in `.claude/agents/` +3. **Routing**: the dispatcher checks `agents-registry.md` for custom agents when no core agent matches +4. **Chaining**: custom agents can suggest (and be suggested by) any other agent, following the same protocol +5. **Maintenance**: the Librarian audits custom agents during vault health checks. For every row in agents-registry.md with status=active, the corresponding file must exist in `.claude/agents/` +6. **Deletion**: only the Architect can remove a custom agent (with user confirmation). The agent file is deleted, and the registry row is set to `disabled` + +--- + ## What Agents Should NOT Do - ❌ **Do NOT reference `Meta/agent-messages.md`** — the shared message board is deprecated diff --git a/references/agents-registry.md b/references/agents-registry.md index 581b31f..52c9921 100644 --- a/references/agents-registry.md +++ b/references/agents-registry.md @@ -33,4 +33,27 @@ The registry is designed to grow: custom agents (see Issue #12) are added as new 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. **Custom agents** are added as new rows by the Architect during the custom agent creation flow + +--- + +## Custom Agents + +Custom agents are created by the Architect through a conversational flow with the user. They follow the exact same schema as core agents and are added as new rows in the Registry table above. + +### How Custom Agents Are Added + +1. The user asks the Architect to create a new agent (or an existing agent suggests one via `### Suggested new agent`) +2. The Architect conducts a detailed conversation to understand requirements +3. The Architect generates the agent file in `.claude/agents/`, adds a row to the Registry table above, and updates `agents.md` +4. Claude Code auto-discovers the new agent from its frontmatter + +### Naming Rules + +- Custom agent names must be lowercase, hyphens only (e.g., `habit-tracker`, `recipe-manager`) +- Names must NOT conflict with core agent names: architect, scribe, sorter, seeker, connector, librarian, transcriber, postman +- Names should be descriptive and concise (1-2 words) + +### Priority + +Custom agents always have lower routing priority than the 8 core agents. The dispatcher checks custom agents only when no core agent matches the user's message. Among custom agents, the dispatcher uses the Input column to find the best match diff --git a/references/agents.md b/references/agents.md index 4933ab7..a3a01dc 100644 --- a/references/agents.md +++ b/references/agents.md @@ -117,3 +117,29 @@ When an agent detects work for another agent, it includes a `### Suggested next | "Need to find an existing note" | Seeker | | "Cross-reference this with email" | Postman | | "This came from a meeting recording" | Transcriber | + +--- + +## Custom Agents + +Custom agents are created by the Architect and live in `.claude/agents/` alongside the core agents. They follow the same conventions: YAML frontmatter, multilingual triggers, inter-agent coordination sections, and dispatcher-driven orchestration. + +For the definitive list of all agents (core + custom) with capabilities, inputs, outputs, and status, see `.claude/references/agents-registry.md`. + +### How Custom Agents Coordinate + +Custom agents participate in the same orchestration protocol as core agents: +- They include `### Suggested next agent` sections when they detect work for other agents +- They include `### Suggested new agent` sections when they detect missing capabilities +- The dispatcher chains them like any other agent, subject to the same anti-recursion rules +- They count toward the max depth of 3 agents per user request + +### Creating a Custom Agent + +Say "create a new agent" or "I need a custom agent" to start the process. The Architect will guide you through a conversation to define the agent's purpose, triggers, permissions, and coordination rules. + +### Managing Custom Agents + +- "Edit my custom agent X" -> the Architect modifies it +- "Remove custom agent X" -> the Architect deactivates it (with user confirmation) +- "List all agents" -> shows core 8 + any custom agents