oh-my-opencode-slim/src/agents/codemap.md

Agents Directory Codemap

Responsibility

src/agents/ defines built-in specialists plus custom agents and converts configuration into OpenCode SDK registration data.

Responsibilities:

• Build orchestrator and specialist agent definitions from factory functions.
• Resolve overrides for model, variant, temperature, options, prompt, and display name.
• Normalize/validate custom agent names and custom-orchestrator-facing aliases.
• Compose permissions, MCP allow-lists, and visibility metadata for OpenCode.

Core architecture

Construction flow (createAgents)

1. Compute the disabled set via getDisabledAgents():
   • from config.disabled_agents
   • with protected-agent guard (orchestrator, councillor never disabled)
2. Build built-in subagents from SUBAGENT_FACTORIES (SUBAGENT_NAMES).
3. Discover custom agent names from config.agents keys that are not built-ins or aliases.
4. Validate custom names (/^[a-z][a-z0-9_-]*$/i) and model presence: skip with warning if model missing.
5. Load prompt files for each agent:
   • <agent>.md replacement prompt
   • <agent>_append.md append prompt
6. Apply override handling:
   • string model → config.model
   • array model → agent._modelArray and clear config.model
   • merge temperature, variant, options, displayName.
7. Apply permission defaults per agent (applyDefaultPermissions).
8. Apply compatibility fallbacks:
   • fixer may inherit librarian model when not explicitly configured.
   • council may inherit deprecated council.master.model when no explicit council override and default remains unresolved.
9. Build orchestrator using prompt files + disabled-agent filtering.
10. Normalize/collect display names and inject @displayName references into: orchestrator prompt and all custom orchestratorPrompt snippets.
11. Validate display-name collisions/agent-name conflicts.
12. Return [orchestrator, ...subagents].

Runtime model behavior

• _modelArray is used as the ordered runtime failover chain when supplied.
• orchestrator may start unresolved (model undefined) to allow downstream runtime resolution.
• subagent overrides preserve per-model variants inside _modelArray while optionally keeping top-level variant as default fallback.

Delegation and registration semantics

• getAgentConfigs(config) converts definitions to SDK configs and sets:
  • orchestrator → mode: primary
  • built-in specialists → mode: subagent
  • council → mode: all
  • councillor → mode: subagent, hidden: true
• If displayName is set:
  • internal key remains registered but hidden
  • host-facing key becomes normalized display name

Permission defaults:

• question defaults to allow unless existing explicit deny.
• council_session defaults to allow only for council.
• Nested skill permissions come from getSkillPermissionsForAgent and are merged with existing permission maps.

Capability and policy inputs

• MCP allow-lists:
  • getAgentMcpList(name, config) from src/config/agent-mcps.ts
  • agent-mcps defaults in src/config/agent-mcps.ts
• Agent metadata/aliases:
  • AGENT_ALIASES, SUBAGENT_NAMES, PROTECTED_AGENTS
  • getAgentOverride, getCustomAgentNames from src/config/utils.ts
• Skills:
  • cli/skills.ts

Flow and integration

src/index.ts
  └─> loadPluginConfig()
      └─> createAgents(config) / getAgentConfigs(config)
          └─> registration + runtime chat hooks

  loadPluginConfig()
    └─> prompt overrides + presets
        └─> createAgents/create custom/orchestrator prompts

Utilities and helpers

• isSubagent(name) — type guard for subagent names.
• getDisabledAgents(config) and getEnabledAgentNames(config).
• resolvePrompt() in orchestrator.ts centralizes replacement vs append behavior.

File structure

• index.ts (agent registry, overrides, classification, custom agents)
• orchestrator.ts (base prompts, prompt resolution, model-array type)
• council.ts, councillor.ts (council tool orchestration + formatting)
• explorer.ts, librarian.ts, oracle.ts, designer.ts, fixer.ts, observer.ts (specialist factory prompts/config)