vault-sync: 2026-09-16 12:01 (jimmy)

memory-systems/agent-os/.opencode/references/agent-orchestration.md

@@ -0,0 +1,195 @@
+# Agent Orchestration Protocol
+
+This document defines how agents coordinate through the **dispatcher** (`AGENTS.md`). Agents do NOT communicate directly with each other — the dispatcher handles all routing and chaining.
+
+---
+
+## Overview
+
+The dispatcher is a **reactive multi-router** with skill-first routing:
+
+1. **User sends a message** → dispatcher checks the **skill routing table** first
+2. **Skill match found?** → invoke the skill via the **Skill tool** and respond to user
+3. **No skill match?** → dispatcher picks the best **agent** by priority
+4. **Agent executes** → returns output to the dispatcher
+5. **Dispatcher reads the output** → decides if another agent should be chained
+6. **Repeat** until done or max depth reached
+
+Agents help the dispatcher by including **suggestions** in their output when they detect work for other agents.
+
+---
+
+## Skill-First Routing
+
+Skills are checked **before** agents. They handle complex, multi-step workflows that were extracted from agents for better performance.
+
+### How it works
+
+- The dispatcher maintains a **skill routing table** (defined in `AGENTS.md`) with trigger phrases in multiple languages.
+- If a user message matches a skill trigger, the skill is invoked via the **Skill tool** (not the Agent tool). The dispatcher does NOT also invoke the source agent.
+- Skills run in the **main conversation context**, preserving multi-turn state. This is different from agents, which run as subprocesses.
+- If no skill matches, the dispatcher falls through to the **agent routing table**.
+
+### Skill-to-agent chaining
+
+Skills can still produce output that triggers agent chaining:
+- A skill may include `### Suggested next agent` in its output (e.g., `/onboarding` may suggest Connector to link newly created notes).
+- The dispatcher reads this output and applies the same chaining rules as for agents (check registry, check call chain, max depth 3).
+- Skills count as step 1 in the call chain when they produce agent suggestions.
+
+### List of skills
+
+See `.opencode/references/agents.md` (Skills section) for the full table of skills, their source agents, and purposes.
+
+---
+
+## 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.
+```
+
+### 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
+
+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. **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).
+
+---
+
+## 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."_
+
+---
+
+## Custom Agent Lifecycle
+
+Custom agents are created by the Architect and stored in `.opencode/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**: the platform auto-discovers the agent from its frontmatter in `.opencode/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 `.opencode/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
+- ❌ **Do NOT edit other agents' prompt/config files** (e.g., `.opencode/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
+
+---
+
+## Agent State (Post-it Protocol)
+
+Every agent has a personal post-it file at `Meta/states/{agent-name}.md`. This provides continuity between executions.
+
+### Rules
+
+- **One file per agent** — named after the agent (e.g., `Meta/states/scribe.md`)
+- **Always written** — every agent writes its post-it at the end of every execution, no exceptions
+- **Overwrites previous** — each execution replaces the previous post-it (it is not a log)
+- **Max 30 lines** — agents must keep the body under 30 lines to prevent bloat
+- **Read at start** — agents read their post-it at the start of execution for context
+- **Private** — the dispatcher does not read or write agent post-its. Only the owning agent touches its own file
+- **Multi-step flows** — agents that run multi-step conversations (e.g., Architect onboarding) use the post-it to track their current phase and collected answers, so they can resume on re-invocation
+
+### Format
+
+```markdown
+---
+agent: {agent-name}
+last-run: "YYYY-MM-DDTHH:MM:SS"
+---
+
+## Post-it
+
+[Agent's notes — max 30 lines]
+```
+
+---
+
+## Reference Files
+
+- **Agent registry**: `.opencode/references/agents-registry.md` — the single source of truth for all agents
+- **Agent directory**: `.opencode/references/agents.md` — detailed descriptions of each agent's responsibilities

memory-systems/agent-os/.opencode/references/agent-template.md

@@ -0,0 +1,216 @@
+# Custom Agent Template
+
+This file is a reference template for the **Architect** when generating new custom agents. It defines the standard structure, required sections, and conventions that every agent must follow.
+
+**This file is NOT an agent itself.** It is a structural guide with placeholder tokens (`{{...}}`) that the Architect fills in based on the user's answers during the custom agent creation flow.
+
+---
+
+## Template
+
+```yaml
+---
+name: {{agent-name}}
+# RULES:
+# - Lowercase, hyphens only (e.g., habit-tracker, recipe-manager, paper-reader)
+# - Must NOT conflict with core agent names: architect, scribe, sorter, seeker,
+#   connector, librarian, transcriber, postman
+# - Keep it short: 1-2 words
+
+description: >
+  {{One-paragraph description of what the agent does, written in the user's language.}}
+  Triggers: {{comma-separated list of natural phrases that should activate this agent,
+  written in the user's language. Include at least 6-8 trigger phrases.}}
+# NOTE: The description is what the platform reads to auto-trigger the agent.
+# Write it in the language the user speaks. Be specific and include the exact phrases
+# a user would naturally say to invoke this agent.
+
+tools: {{tool list}}
+# Available tools and when to grant them:
+#   Read, Glob, Grep        -> DEFAULT. Every agent gets these (search and read the vault)
+#   Write                   -> Only if the agent CREATES new notes or files
+#   Edit                    -> Only if the agent MODIFIES existing notes or files
+#   Bash                    -> Only if the agent needs filesystem operations (move, rename, mkdir)
+#                              or CLI tool access (e.g., gws for Google Workspace API calls)
+# Principle: grant the MINIMUM tools necessary. Read-only agents should NOT have Write/Edit.
+
+model: sonnet
+# Options: sonnet (default), opus (deep reasoning), haiku (fast/lightweight)
+# Use sonnet unless there is a strong reason not to.
+---
+
+# {{Agent Name}} -- {{Short Subtitle}}
+
+Always respond to the user in their language. Match the language the user writes in.
+
+{{One sentence describing the agent's core purpose and what it does.}}
+
+---
+
+## User Profile
+
+Before doing anything, read `Meta/user-profile.md` to understand the user's context, preferences, and personal information. Use this to personalize your behavior and output.
+
+---
+
+## Inter-Agent Coordination
+
+> **You do NOT communicate directly with other agents. The dispatcher handles all orchestration.**
+
+When you detect work that another agent should handle, include a `### Suggested next agent` section at the end of your output. The dispatcher reads this and decides whether to chain the next agent.
+
+### When to suggest another agent
+
+{{List specific conditions when this agent should signal other agents. Common patterns:}}
+
+- **Architect** -> if the agent detects missing vault structure (no folder, no MOC, no templates for a topic)
+- **Sorter** -> if the agent creates notes that need filing from the Inbox
+- **Connector** -> if the agent creates or finds notes that need cross-linking
+- **Librarian** -> if the agent finds broken links, duplicates, or inconsistencies
+
+### Output format for suggestions
+
+~~~markdown
+### Suggested next agent
+- **Agent**: {{agent name from agents-registry.md}}
+- **Reason**: {{what needs to be done and why}}
+- **Context**: {{relevant details -- note titles, folder paths, specific issues}}
+~~~
+
+### When to suggest a new agent
+
+If you detect that the user needs functionality that NO existing agent provides, include a `### Suggested new agent` section in your output. The dispatcher will consider invoking the Architect to create a custom agent.
+
+**When to signal this:**
+- The user repeatedly asks for something outside any agent's capabilities
+- The task requires a specialized workflow that none of the current agents handle
+- The user explicitly says they wish an agent existed for a specific purpose
+
+**Output format:**
+
+~~~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}}
+~~~
+
+**Do NOT suggest a new agent when:**
+- An existing agent can handle the task (even imperfectly)
+- The user is asking something outside the vault's scope entirely
+- The task is a one-off that does not warrant a dedicated agent
+
+For the full orchestration protocol, see `.opencode/references/agent-orchestration.md`.
+For the agent registry, see `.opencode/references/agents-registry.md`.
+
+---
+
+## Core Responsibilities
+
+{{This is the main section of the agent. Define:}}
+
+1. **What the agent does** -- its primary function and responsibilities
+2. **How it does it** -- step-by-step processes, modes of operation
+3. **Output format** -- what kind of notes/reports it produces, with templates
+4. **Decision rules** -- how it handles edge cases and ambiguity
+
+{{Be EXTREMELY detailed here. This section is what makes the agent good or bad.
+The more specific the instructions, the better the agent performs. Include:}}
+- Concrete examples of input and expected output
+- Templates with frontmatter for any notes the agent creates
+- Rules for edge cases
+- Quality standards
+
+---
+
+## First Run Setup
+
+{{Define what this agent must do the FIRST time it is invoked. This is the agent's
+onboarding flow. It runs once, then never again.}}
+
+### Detection
+
+The agent detects it is running for the first time by checking for a specific marker.
+Options (pick the most appropriate):
+- A config file does not exist yet (e.g., `Meta/{{agent-name}}-config.md`)
+- A required folder does not exist yet
+- A flag in `Meta/user-profile.md` is missing
+
+### What to ask the user
+
+{{List the questions the agent needs to ask the user on first run to configure itself.
+These are questions that only need to be answered once. Examples:}}
+- What are the user's goals or preferences for this domain?
+- What categories, limits, or thresholds should the agent use?
+- Are there existing notes or data the agent should import or be aware of?
+- How often should the agent run or check in?
+
+### What to create
+
+{{List everything the agent must set up on first run. Examples:}}
+- Configuration file in `Meta/` with the user's answers
+- Required folders in the vault (if any)
+- Initial templates (if any)
+- A welcome/summary note in `00-Inbox/` explaining what the agent does and how to use it
+
+### After first run
+
+Once setup is complete, the agent saves its configuration and operates normally
+on all subsequent invocations. It should NEVER repeat the onboarding flow unless
+the user explicitly asks to reconfigure it.
+
+---
+
+## Agent State (Post-it)
+
+You have a personal post-it at `Meta/states/{{agent-name}}.md`. This is your memory between executions.
+
+### At the START of every execution
+
+Read `Meta/states/{{agent-name}}.md` if it exists. It contains notes you left for yourself last time. Use this context to provide continuity. If the file does not exist, this is your first run — proceed without prior context.
+
+### At the END of every execution
+
+**You MUST write your post-it. This is not optional.** Write (or overwrite if it already exists) `Meta/states/{{agent-name}}.md` with:
+
+\`\`\`markdown
+---
+agent: {{agent-name}}
+last-run: "{{ISO timestamp}}"
+---
+
+## Post-it
+
+[Your notes here — max 30 lines]
+\`\`\`
+
+**What to save**: {{Customize based on agent purpose — e.g., notes created, pending tasks, context for next run, active multi-step flows with current phase and collected data.}}
+
+**Max 30 lines** in the Post-it body. If you need more, summarize. This is a post-it, not a journal.
+
+---
+
+## Operational Rules
+
+1. **Always respond in the user's language** -- match whatever language they write in
+2. **Read user profile first** -- always check `Meta/user-profile.md` before acting
+3. **Conservative by default** -- never delete, always archive. Ask before making structural decisions
+4. **File naming convention** -- follow the vault's naming patterns (check `Meta/vault-structure.md`)
+5. **Obsidian compatibility** -- all YAML frontmatter must be Dataview-compatible, use `[[wikilinks]]` for connections
+6. {{Add agent-specific rules here}}
+```
+
+---
+
+## Conventions for the Architect
+
+When generating a custom agent from this template:
+
+1. **The description field** is written in the user's language, with trigger phrases the user would naturally say
+2. **Tools are minimal** by default. Start with `Read, Glob, Grep` and only add more if the user's answers justify it
+3. **The Inter-Agent Coordination section** is mandatory and must be included verbatim (with the When to suggest another agent list customized for this agent)
+4. **The Core Responsibilities section** must be deeply detailed. Ask the user enough questions to fill this section thoroughly. A vague agent is a useless agent
+5. **Every custom agent** gets a row in `.opencode/references/agents-registry.md` and a section in `.opencode/references/agents.md`
+6. **File location**: `.opencode/agents/{{agent-name}}.md`
+7. **Naming conflicts**: if the user picks a name that conflicts with the 8 core agents, suggest an alternative
+8. **Complex multi-step flows**: if an agent has conversational, multi-turn workflows (e.g., onboarding, multi-phase interviews), those should be extracted into **skills** (`.opencode/skills/`) rather than kept in the agent body. Skills run in the main conversation context and preserve multi-turn state, which agents cannot do as subprocesses. See the 13 core skills in `.opencode/references/agents.md` (Skills section) for examples

memory-systems/agent-os/.opencode/references/agents-registry.md

@@ -0,0 +1,91 @@
+# Agent Registry
+
+This file is the **single source of truth** for all active agents in the crew. The dispatcher (`AGENTS.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/archive/delete email (Gmail via `gws`, Hey.com via `hey`), search emails, read/create/update calendar events, draft and send replies. Uses Google Workspace CLI (`gws`) and/or Hey CLI (`hey`) via Bash, with MCP as read-only fallback. | Email triage, calendar queries, deadline tracking, meeting prep, VIP filtering | Email summaries saved as notes in `00-Inbox/`, calendar events created, deadline reports | active |
+<!-- MBIFC:CUSTOM_AGENTS_START -->
+<!-- MBIFC:CUSTOM_AGENTS_END -->
+
+---
+
+## 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** 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 `.opencode/agents/`, adds a row to the Registry table above, and updates `agents.md`
+4. The platform 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
+
+---
+
+## Skills Registry
+
+Skills handle complex, multi-step workflows extracted from agents. They are checked **before** agents by the dispatcher (higher priority). Skills run in the main conversation context via the Skill tool, preserving multi-turn state.
+
+| Skill | Source Agent | Triggers | Purpose | Status |
+|-------|-------------|----------|---------|--------|
+| `/onboarding` | architect | "initialize the vault", "set up the vault", "onboarding", "vault setup" | Full vault setup conversation | active |
+| `/create-agent` | architect | "create a new agent", "custom agent", "I need a new agent", "build an agent", "new crew member" | Custom agent creation (6-phase interview) | active |
+| `/manage-agent` | architect | "edit my agent", "update agent", "remove agent", "delete agent", "list agents", "show my agents" | Edit, remove, list custom agents | active |
+| `/defrag` | architect | "defragment the vault", "reorganize the vault", "structural maintenance", "vault defrag", "weekly defrag" | Weekly vault defragmentation (5-phase audit) | active |
+| `/email-triage` | postman | "check my email", "what's in my inbox", "process emails", "email triage", "anything urgent in email?" | Email scanning, priority scoring, classification | active |
+| `/meeting-prep` | postman | "prepare for meeting", "meeting prep", "brief me for the meeting", "get ready for the call" | Comprehensive meeting brief with context gathering | active |
+| `/weekly-agenda` | postman | "weekly agenda", "what's this week", "week overview", "plan my week" | Day-by-day week overview from calendar, email, vault | active |
+| `/deadline-radar` | postman | "deadline radar", "what are my deadlines", "this week's deadlines", "upcoming deadlines" | Unified deadline timeline with urgency grouping | active |
+| `/transcribe` | transcriber | "transcribe", "I have a recording", "process this audio", "meeting notes from recording", "summarize the call" | Audio/transcript processing with structured notes | active |
+| `/vault-audit` | librarian | "weekly review", "check the vault", "vault audit", "full audit", "vault health" | Full 7-phase vault audit | active |
+| `/deep-clean` | librarian | "deep clean", "deep cleanup", "thorough cleanup", "the vault is a mess" | Extended vault cleanup with stale content detection | active |
+| `/tag-garden` | librarian | "tag garden", "clean up tags", "tag cleanup", "tag audit" | Tag analysis: unused, orphan, near-duplicates | active |
+| `/inbox-triage` | sorter | "triage the inbox", "clean up the inbox", "sort my notes", "empty inbox", "file my notes", "process the inbox" | Inbox note processing, classification, and routing | active |
+| `/contact-sync` | postman | "sync contact", "add to contacts", "save contact", "update contact", "is this person in my contacts" | Sync person to Apple Contacts (search, create, update). Requires `apple-contacts` MCP. | active |
+
+### How Skills Are Routed
+
+1. The dispatcher checks the **skill routing table** (in `AGENTS.md`) before the agent routing table
+2. If a trigger matches, the skill is invoked via the **Skill tool** — not the Agent tool
+3. If no skill matches, the dispatcher falls through to agent routing
+4. Skills can produce `### Suggested next agent` output, which the dispatcher handles using the same chaining rules as agents

memory-systems/agent-os/.opencode/references/agents.md

@@ -0,0 +1,178 @@
+# My Brain Is Full - Crew — Agent Directory
+
+This reference is shared across all agents. Every agent knows the others, their responsibilities, and when to suggest them to the dispatcher.
+
+---
+
+## Agent Registry
+
+For the definitive list of agents with capabilities, inputs, outputs, and status, see `.opencode/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.
+
+---
+
+## User Profile
+
+All agents read `Meta/user-profile.md` for personalization. This file is created during onboarding by the Architect and contains the user's name, language, role, health data (if opted in), and preferences. **Never hardcode personal data in agent files.**
+
+---
+
+## The Eight Agents
+
+### 1. Architect
+
+**Role**: Vault Structure & Governance
+**Agent file**: `architect.md`
+**Responsibilities**: Designs and maintains the vault's folder structure, templates, naming conventions, and tag taxonomy. The constitutional authority — sets the rules that all other agents follow. Creates and manages `Meta/user-profile.md`.
+**Skills**: Complex flows (onboarding, defrag, agent creation/management) are handled by dedicated skills: `/onboarding`, `/defrag`, `/create-agent`, `/manage-agent`.
+**Contact when**: A new folder, area, or project needs to be created. The vault structure seems wrong or incomplete. Template definitions are needed. Tag taxonomy needs updating. Another agent doesn't know where a note should live. The user wants to update their profile.
+
+---
+
+### 2. Scribe
+
+**Role**: Text Capture & Refinement
+**Agent file**: `scribe.md`
+**Responsibilities**: Transforms raw, unstructured text from the user into clean, well-structured Obsidian notes. Handles voice-to-note, brainstorm mode, quote capture, reading notes. Acts as writing proxy for agents that operate in read-only mode. All output lands in `00-Inbox/`.
+**Contact when**: A note needs to be cleaned up or reformatted. Raw text needs to be turned into a structured note.
+
+---
+
+### 3. Sorter
+
+**Role**: Inbox Triage & Filing
+**Agent file**: `sorter.md`
+**Responsibilities**: Processes `00-Inbox/`, classifies notes, and moves them to their correct vault locations. Updates MOC files after filing. Handles smart batching, priority triage, and project pulse reporting.
+**Skills**: Standard inbox triage is handled by the `/inbox-triage` skill.
+**Contact when**: Notes are piling up in the inbox. A note was filed somewhere wrong. MOC files seem out of date.
+
+---
+
+### 4. Seeker
+
+**Role**: Search & Intelligence
+**Agent file**: `seeker.md`
+**Responsibilities**: Finds and retrieves information across the vault using full-text search, metadata queries, and relationship navigation. Synthesizes answers from multiple notes with citations. Can modify notes on request. Handles timeline mode, diff mode, and missing knowledge detection.
+**Contact when**: Information needs to be found or verified before acting. A note's location is unknown. A cross-reference is needed. The user asks a factual question.
+
+---
+
+### 5. Connector
+
+**Role**: Knowledge Graph & Link Analysis
+**Agent file**: `connector.md`
+**Responsibilities**: Analyzes the vault's link structure, discovers missing connections between notes, suggests wikilinks, and strengthens the knowledge graph. Handles serendipity mode, bridge notes, constellation view, and people network analysis.
+**Contact when**: Notes feel isolated and should probably link to each other. After a batch of notes is filed. MOC coverage seems low.
+
+---
+
+### 6. Librarian
+
+**Role**: Vault Health & Quality Assurance
+**Agent file**: `librarian.md`
+**Responsibilities**: Runs periodic audits of the entire vault — detects structural inconsistencies, merges duplicates, fixes broken links, checks frontmatter quality, tracks growth analytics, and produces health reports.
+**Skills**: Full audit, deep clean, and tag garden are handled by skills: `/vault-audit`, `/deep-clean`, `/tag-garden`.
+**Contact when**: Vault-wide quality issues are suspected. Something seems structurally wrong. Duplicates, broken links, or inconsistent tags are detected.
+
+---
+
+### 7. Transcriber
+
+**Role**: Audio & Meeting Intelligence
+**Agent file**: `transcriber.md`
+**Responsibilities**: Processes audio recordings and raw transcriptions into richly structured notes. Handles meeting notes, lecture notes, podcast summaries, voice journals, and interview extraction. All output lands in `00-Inbox/`.
+**Skills**: All transcription processing is handled by the `/transcribe` skill. The agent handles only edge cases.
+**Contact when**: A meeting recording or transcript needs to be structured. A note should be created from an audio source.
+
+---
+
+### 8. Postman
+
+**Role**: Email & Calendar Intelligence
+**Agent file**: `postman.md`
+**Requires**: One of: Google Workspace CLI (`gws`), Hey CLI (`hey`), or MCP connectors (read-only fallback). See `docs/gws-setup-guide.md` for GWS setup; see [Hey CLI](https://github.com/basecamp/hey-cli) for Hey setup.
+**Responsibilities**: Scans email (Gmail or Hey.com) for actionable emails, archives/deletes/labels emails, imports Google Calendar events, creates calendar events. Handles VIP filtering and contact enrichment. When using Hey, leverages pre-sorted mailboxes (Imbox, Feed, Paper Trail, Reply Later, Set Aside, Bubble Up).
+**Skills**: Email triage, meeting prep, weekly agenda, and deadline radar are handled by skills: `/email-triage`, `/meeting-prep`, `/weekly-agenda`, `/deadline-radar`.
+**Contact when**: Important information may have arrived by email. Meeting notes should be cross-referenced with calendar events. An event needs to be created from a note.
+
+---
+
+## Skills
+
+Skills handle complex, multi-step workflows that were extracted from agents for better performance. They run in the main conversation context (not as subprocesses), which allows multi-turn conversations.
+
+The dispatcher routes triggers to skills FIRST, then falls through to agents.
+
+| Skill | Source Agent | Purpose |
+|-------|-------------|---------|
+| `/onboarding` | Architect | Full vault setup conversation |
+| `/create-agent` | Architect | Custom agent creation (6-phase interview) |
+| `/manage-agent` | Architect | Edit, remove, list custom agents |
+| `/defrag` | Architect | Weekly vault defragmentation |
+| `/email-triage` | Postman | Email scanning and prioritization |
+| `/meeting-prep` | Postman | Meeting brief preparation |
+| `/weekly-agenda` | Postman | Week-at-a-glance overview |
+| `/deadline-radar` | Postman | Deadline timeline from all sources |
+| `/transcribe` | Transcriber | Audio/transcript processing |
+| `/vault-audit` | Librarian | Full 7-phase vault audit |
+| `/deep-clean` | Librarian | Extended vault cleanup |
+| `/tag-garden` | Librarian | Tag analysis and gardening |
+| `/inbox-triage` | Sorter | Inbox note processing and routing |
+
+---
+
+## Quick Reference: When to Suggest Another Agent
+
+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 `.opencode/references/agent-orchestration.md` for the full protocol.
+
+| Situation | Suggest |
+|-----------|---------|
+| "Don't know where to file this note" | Architect |
+| "This area/folder doesn't exist" | Architect |
+| "Tag doesn't exist in taxonomy" | Architect |
+| "Template is missing or wrong" | Architect |
+| "User wants to update their profile" | Architect |
+| "Found a duplicate note" | Librarian |
+| "Found a broken link" | Librarian |
+| "Note has wrong frontmatter" | Librarian |
+| "Vault structure seems inconsistent" | Librarian |
+| "This note should link to others" | Connector |
+| "Found related but unlinked notes" | Connector |
+| "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 `.opencode/agents/` alongside the core agents. They follow the same conventions: YAML frontmatter, trigger phrases written in the user's language, inter-agent coordination sections, and dispatcher-driven orchestration.
+
+For the definitive list of all agents (core + custom) with capabilities, inputs, outputs, and status, see `.opencode/references/agents-registry.md`.
+
+<!-- MBIFC:CUSTOM_AGENTS_START -->
+<!-- MBIFC:CUSTOM_AGENTS_END -->
+
+### 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 `/create-agent` skill guides you through a 6-phase interview to define the agent's purpose, triggers, permissions, and coordination rules.
+
+### Managing Custom Agents
+
+Use the `/manage-agent` skill:
+- "Edit my custom agent X" -> modifies it
+- "Remove custom agent X" -> deactivates it (with user confirmation)
+- "List all agents" -> shows core 8 + any custom agents