AGENTS.md

1---
2name: agents-directory
3description: Developer reference for all 11 Oh My OpenAgent agent definitions, factory patterns, tool restrictions, and model routing.
4---
5 
6# src/agents/ — 11 Agent Definitions
7 
8**Generated:** 2026-05-15
9 
10## OVERVIEW
11 
1211 built-in agents. Type enum: [`src/config/schema/agent-names.ts`](../config/schema/agent-names.ts) `BuiltinAgentNameSchema`. 10 of them register via [`builtin-agents.ts`](builtin-agents.ts) `agentSources` record (factory functions). **Prometheus is special-cased** — it has no `createPrometheusAgent` factory; instead [`prometheus-agent-config-builder.ts`](../plugin-handlers/prometheus-agent-config-builder.ts) constructs its config directly during `agent-config-handler` Phase 3.
13 
14All factories follow `createXXXAgent(model) → AgentConfig`. Each carries a static `mode` property (`AgentFactory` type in [`src/agents/types.ts`](types.ts)). Composed via `buildAgent()`.
15 
16## AGENT INVENTORY
17 
18Modes verified from each agent file's `const MODE: AgentMode = ...` and (for Prometheus) [`prometheus-agent-config-builder.ts:100`](../plugin-handlers/prometheus-agent-config-builder.ts#L100). Chains verified from [`src/shared/model-requirements.ts`](../shared/model-requirements.ts).
19 
20| Agent | Default Model | Temp | Mode | Fallback (after default) | Purpose |
21|-------|---------------|------|------|--------------------------|---------|
22| **Sisyphus** | claude-opus-5 max | (model default) | primary | kimi-k3 → gpt-5.6-sol medium → glm-5.2 → big-pickle | Main orchestrator, plans + delegates; `thinking: { type: "enabled", budgetTokens: 32000 }` |
23| **Hephaestus** | gpt-5.6-sol medium | (model default) | primary | GPT-5.6 Sol only (`requiresProvider`: openai \| github-copilot \| opencode \| vercel) | Autonomous deep worker |
24| **Oracle** | gpt-5.6-sol xhigh (high on Copilot) | 0.1 | subagent | gemini-3.1-pro high → claude-opus-5 max → glm-5.2 | Read-only consultation |
25| **Librarian** | gpt-5.6-luna-fast | 0.1 | subagent | qwen3.7-plus → minimax-m2.7-highspeed → minimax-m3 → minimax-m2.7 → claude-haiku-4-5 → gpt-5.4-nano | External docs/code search |
26| **Explore** | gpt-5.6-luna-fast | 0.1 | subagent | qwen3.7-plus → minimax-m2.7-highspeed → minimax-m3 → minimax-m2.7 → claude-haiku-4-5 → gpt-5.4-nano | Contextual grep |
27| **Multimodal-Looker** | gpt-5.6-sol low | 0.1 | subagent | kimi-k3 → glm-4.6v → gpt-5-nano | PDF/image analysis |
28| **Metis** | claude-opus-5 high | **0.3** | subagent | kimi-k3 low | Pre-planning consultant |
29| **Momus** | gpt-5.6-terra high | 0.1 | subagent | gpt-5.6-sol xhigh (high on Copilot) → claude-opus-5 max → gemini-3.1-pro high → glm-5.2 | Plan reviewer |
30| **Atlas** | claude-sonnet-5 | 0.1 | primary | kimi-k3 → gpt-5.6-sol medium → minimax-m3 → MiniMax-M3 → minimax-m2.7 | Todo-list orchestrator |
31| **Prometheus** | claude-fable-5 xhigh | (override-only) | primary | kimi-k3 max | Strategic planner (interview); built via `buildPrometheusAgentConfig` (not in `agentSources`) |
32| **Sisyphus-Junior** | claude-sonnet-5 | 0.1 (`SISYPHUS_JUNIOR_DEFAULTS`) | subagent | kimi-k3 → gpt-5.6-sol medium → minimax-m3 → MiniMax-M3 → minimax-m2.7 → big-pickle | Category-spawned executor |
33 
34## TOOL RESTRICTIONS
35 
36Defined in [`src/shared/agent-tool-restrictions.ts`](../shared/agent-tool-restrictions.ts).
37 
38| Agent | Denied Tools |
39|-------|-------------|
40| Oracle | write, edit, task, call_omo_agent |
41| Librarian | write, edit, task, call_omo_agent |
42| Explore | write, edit, task, call_omo_agent |
43| Multimodal-Looker | ALL except read |
44| Atlas | task, call_omo_agent |
45| Momus | write, edit, task |
46| Prometheus | enforces `.md`-only writes via `prometheus-md-only` hook (path-based, not tool-based) |
47 
48## TEAM-MODE ELIGIBILITY
49 
50Authoritative registry: [`AGENT_ELIGIBILITY_REGISTRY`](../features/team-mode/types.ts) in `team-mode/types.ts`. Three verdict tiers:
51 
52| Verdict | Agents |
53|---------|--------|
54| `eligible` | sisyphus, atlas, sisyphus-junior |
55| `conditional` | hephaestus (lacks `teammate: "allow"` permission by default — see D-36 / `tool-config-handler.ts`; use `subagent_type: "sisyphus"` instead) |
56| `hard-reject` | oracle, librarian, explore, multimodal-looker, metis, momus, prometheus (each with a specific rejection message) |
57 
58Read-only agents are rejected at TeamSpec parse time. For those, the lead delegates via `task` (delegate-task) instead. See [`team-mode/AGENTS.md`](../features/team-mode/AGENTS.md).
59 
60## STRUCTURE
61 
62```
63agents/
64├── sisyphus.ts                                # Main orchestrator router
65├── sisyphus/                                  # Model-specific variant prompts
66│   ├── default.ts, gemini.ts, gpt-5-4.ts, gpt-5-5.ts
67├── hephaestus.ts                              # Routes to model variant
68├── hephaestus/                                # gpt.ts, gpt-5-4.ts, gpt-5-5.ts, gpt-5-6.ts
69├── oracle.ts                                  # Read-only consultant
70├── librarian.ts                               # External search
71├── explore.ts                                 # Codebase grep
72├── multimodal-looker.ts                       # Vision/PDF
73├── metis.ts                                   # Pre-planning
74├── momus.ts                                   # Plan review
75├── atlas/agent.ts                             # Todo orchestrator
76├── prometheus/                                # Strategic planner prompt router; prompt content in packages/prompts-core/prompts/prometheus/
77├── types.ts                                   # BuiltinAgentName, AgentMode, AgentConfig
78├── builtin-agents.ts                          # agentSources registry (10 → 11 with sisyphus-junior)
79├── builtin-agents/                            # maybeCreateXXXConfig conditional factories + general-agents.ts + available-skills.ts
80├── agent-builder.ts                           # buildAgent() composition
81├── utils.ts                                   # agent utilities
82├── env-context.ts                             # environment context for prompts
83├── dynamic-agent-prompt-builder.ts            # dynamic prompt builder
84├── dynamic-agent-core-sections.ts             # core prompt sections
85├── dynamic-agent-policy-sections.ts           # policy sections
86├── dynamic-agent-tool-categorization.ts       # tool categorization for prompt
87└── dynamic-agent-category-skills-guide.ts     # category-skill guidance
88```
89 
90## FACTORY PATTERN
91 
92```typescript
93const createXXXAgent: AgentFactory = (model: string) => ({
94  instructions: "...",
95  model,
96  temperature: 0.1,
97  // ...config
98})
99createXXXAgent.mode = "subagent" // or "primary" or "all"
100```
101 
102Model resolution: 4-step pipeline → override → category-default → provider-fallback → system-default. Defined in [`shared/model-resolution-pipeline.ts`](../shared/model-resolution-pipeline.ts).
103 
104## MODES
105 
106Definition (from [`src/agents/types.ts`](types.ts)):
107 
108- **`primary`** — respects user's UI-selected model. Used by: sisyphus, hephaestus, atlas, prometheus.
109- **`subagent`** — uses own fallback chain, ignores UI selection. Used by: oracle, librarian, explore, multimodal-looker, metis, momus, sisyphus-junior.
110- **`all`** — declared in the type for OpenCode compatibility but no built-in agent currently uses it.
111 
112## CANONICAL ORDER
113 
114`Sisyphus → Hephaestus → Prometheus → Atlas` (primary core agents) then alphabetical for the rest. Enforced by [`installAgentSortShim()`](../shared/agent-sort-shim.ts) — patches `Array.prototype.{toSorted,sort}` narrowly when ≥2 canonical core agents are in the array. See [`src/plugin-handlers/AGENTS.md`](../plugin-handlers/AGENTS.md) for the full history.
115 
116## DYNAMIC PROMPT BUILDER
117 
118`dynamic-agent-prompt-builder.ts` composes per-agent system prompts at runtime by stitching:
119- Core sections (identity, mode, restrictions)
120- Policy sections (citation, verification, anti-patterns)
121- Tool categorization (per-domain tool guidance)
122- Category-skills guide (which skills load with which categories)
123 
124This is what the Sisyphus prompt's "AGENTS / CATEGORY + SKILLS" tables come from.
125