AGENTS.md

1<!-- Parent: ../AGENTS.md -->
2<!-- Generated: 2026-01-28 | Updated: 2026-02-24 -->
3 
4# agents
5 
618 specialized AI agent definitions with 3-tier model routing for optimal cost and performance.
7 
8## Purpose
9 
10This directory defines all agents available in oh-my-claudecode:
11 
12- **18 base agents** with default model assignments
13- **Tiered variants** (LOW/MEDIUM/HIGH) for smart routing
14- Prompts loaded dynamically from `/agents/*.md` files
15- Tools assigned based on agent specialization
16 
17## Key Files
18 
19| File | Description |
20|------|-------------|
21| `definitions.ts` | **Main registry** - `getAgentDefinitions()`, `omcSystemPrompt` |
22| `architect.ts` | Architecture & debugging expert (Opus) |
23| `executor.ts` | Focused task implementation (Sonnet) |
24| `explore.ts` | Fast codebase search (Haiku) |
25| `designer.ts` | UI/UX specialist (Sonnet) |
26| `document-specialist.ts` | Documentation & reference lookup (Sonnet) |
27| `writer.ts` | Technical documentation (Haiku) |
28| `vision.ts` | Visual/image analysis (Sonnet) |
29| `critic.ts` | Critical plan review (Opus) |
30| `analyst.ts` | Pre-planning analysis (Opus) |
31| `planner.ts` | Strategic planning (Opus) |
32| `qa-tester.ts` | CLI/service testing with tmux (Sonnet) |
33| `scientist.ts` | Data analysis & hypothesis testing (Sonnet) |
34| `index.ts` | Exports all agents and utilities |
35 
36## For AI Agents
37 
38### Working In This Directory
39 
40#### Understanding the Agent Registry
41 
42The main registry is in `definitions.ts`:
43 
44```typescript
45// Get all 18 agents
46const agents = getAgentDefinitions();
47 
48// Each agent has:
49{
50  name: 'architect',
51  description: 'Architecture & Debugging Advisor',
52  prompt: '...',  // Loaded from /agents/architect.md
53  tools: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch'],
54  model: 'opus',
55  defaultModel: 'opus'
56}
57```
58 
59#### Agent Selection Guide
60 
61| Task Type | Best Agent | Model | Tools |
62|-----------|------------|-------|-------|
63| Complex debugging | `architect` | opus | Read, Glob, Grep, WebSearch, WebFetch |
64| Quick code lookup | `architect-low` | haiku | Read, Glob, Grep |
65| Standard analysis | `architect-medium` | sonnet | Read, Glob, Grep, WebSearch, WebFetch |
66| Feature implementation | `executor` | sonnet | Read, Glob, Grep, Edit, Write, Bash, TodoWrite |
67| Simple fixes | `executor-low` | haiku | Read, Glob, Grep, Edit, Write, Bash, TodoWrite |
68| Complex refactoring | `executor-high` | opus | Read, Glob, Grep, Edit, Write, Bash, TodoWrite |
69| Fast file search | `explore` | haiku | Read, Glob, Grep |
70| Architectural discovery | `explore-high` | opus | Read, Glob, Grep |
71| UI components | `designer` | sonnet | Read, Glob, Grep, Edit, Write, Bash |
72| Simple styling | `designer-low` | haiku | Read, Glob, Grep, Edit, Write, Bash |
73| Design systems | `designer-high` | opus | Read, Glob, Grep, Edit, Write, Bash |
74| API documentation | `document-specialist` | sonnet | Read, Glob, Grep, WebSearch, WebFetch |
75| README/docs | `writer` | haiku | Read, Glob, Grep, Edit, Write |
76| Image analysis | `vision` | sonnet | Read, Glob, Grep |
77| Plan review | `critic` | opus | Read, Glob, Grep |
78| Requirements analysis | `analyst` | opus | Read, Glob, Grep, WebSearch |
79| Strategic planning | `planner` | opus | Read, Glob, Grep, WebSearch |
80| CLI testing | `qa-tester` | sonnet | Bash, Read, Grep, Glob, TodoWrite |
81| Data analysis | `scientist` | sonnet | Read, Glob, Grep, Bash, python_repl |
82| ML/hypothesis | `scientist-high` | opus | Read, Glob, Grep, Bash, python_repl |
83| Security audit | `security-reviewer` | opus | Read, Grep, Glob, Bash |
84| Quick security scan | `security-reviewer-low` | haiku | Read, Grep, Glob, Bash |
85| Build errors | `debugger` | sonnet | Read, Grep, Glob, Edit, Write, Bash |
86| TDD workflow | `test-engineer` | sonnet | Read, Grep, Glob, Edit, Write, Bash |
87| Test suggestions | `test-engineer` (model=haiku) | haiku | Read, Grep, Glob, Bash |
88| Code review | `code-reviewer` | opus | Read, Grep, Glob, Bash |
89 
90#### Creating a New Agent
91 
921. **Create agent file** (e.g., `new-agent.ts`):
93```typescript
94import type { AgentConfig } from '../shared/types.js';
95 
96export const newAgent: AgentConfig = {
97  name: 'new-agent',
98  description: 'What this agent does',
99  prompt: '', // Will be loaded from /agents/new-agent.md
100  tools: ['Read', 'Glob', 'Grep'],
101  model: 'sonnet',
102  defaultModel: 'sonnet'
103};
104```
105 
1062. **Create prompt template** at `/agents/new-agent.md`:
107```markdown
108---
109name: new-agent
110description: What this agent does
111model: sonnet
112tools: [Read, Glob, Grep]
113---
114 
115# Agent Instructions
116 
117You are a specialized agent for...
118```
119 
1203. **Add to definitions.ts**:
121```typescript
122import { newAgent } from './new-agent.js';
123 
124export function getAgentDefinitions() {
125  return {
126    // ... existing agents
127    'new-agent': newAgent,
128  };
129}
130```
131 
1324. **Export from index.ts**:
133```typescript
134export { newAgent } from './new-agent.js';
135```
136 
137#### Creating Tiered Variants
138 
139For model routing, create LOW/MEDIUM/HIGH variants in `definitions.ts`:
140 
141```typescript
142// Haiku variant for simple tasks
143export const newAgentLow: AgentConfig = {
144  name: 'new-agent-low',
145  description: 'Quick new-agent tasks (Haiku)',
146  prompt: loadAgentPrompt('new-agent-low'),
147  tools: ['Read', 'Glob', 'Grep'],
148  model: 'haiku',
149  defaultModel: 'haiku'
150};
151 
152// Opus variant for complex tasks
153export const newAgentHigh: AgentConfig = {
154  name: 'new-agent-high',
155  description: 'Complex new-agent tasks (Opus)',
156  prompt: loadAgentPrompt('new-agent-high'),
157  tools: ['Read', 'Glob', 'Grep', 'WebSearch'],
158  model: 'opus',
159  defaultModel: 'opus'
160};
161```
162 
163### Modification Checklist
164 
165#### When Adding a New Agent
166 
1671. Create agent file (`src/agents/new-agent.ts`)
1682. Create prompt template (`agents/new-agent.md`)
1693. Add to `definitions.ts` (import + registry)
1704. Export from `index.ts`
1715. Update `docs/REFERENCE.md` (Agents section, count)
1726. Update `docs/CLAUDE.md` (Agent Selection Guide)
1737. Update root `/AGENTS.md` (Agent Summary if applicable)
174 
175#### When Modifying an Agent
176 
1771. Update agent file (`src/agents/*.ts`) if changing tools/model
1782. Update prompt template (`agents/*.md`) if changing behavior
1793. Update tiered variants (`-low`, `-medium`, `-high`) if applicable
1804. Update `docs/REFERENCE.md` if changing agent description/capabilities
1815. Update `docs/CLAUDE.md` (Agent Tool Matrix) if changing tool assignments
182 
183#### When Removing an Agent
184 
1851. Remove agent file from `src/agents/`
1862. Remove prompt template from `agents/`
1873. Remove from `definitions.ts` and `index.ts`
1884. Update agent counts in all documentation
1895. Check for skill/hook references to the removed agent
190 
191### Testing Requirements
192 
193Agents are tested via integration tests:
194 
195```bash
196npm test -- --grep &quot;agent&quot;
197```
198 
199### Common Patterns
200 
201**Prompt loading:**
202```typescript
203function loadAgentPrompt(agentName: string): string {
204  const agentPath = join(getPackageDir(), 'agents', `${agentName}.md`);
205  const content = readFileSync(agentPath, 'utf-8');
206  // Strip YAML frontmatter
207  const match = content.match(/^---[\s\S]*?---\s*([\s\S]*)$/);
208  return match ? match[1].trim() : content.trim();
209}
210```
211 
212**Tool assignment patterns:**
213- Read-only agents: `['Read', 'Glob', 'Grep']`
214- Analysis agents: Add `['WebSearch', 'WebFetch']`
215- Execution agents: Add `['Edit', 'Write', 'Bash', 'TodoWrite']`
216- Data agents: Add `['python_repl']`
217 
218## Dependencies
219 
220### Internal
221- Prompts from `/agents/*.md`
222- Types from `../shared/types.ts`
223 
224### External
225None - pure TypeScript definitions.
226 
227## Agent Categories
228 
229| Category | Agents | Purpose |
230|----------|--------|---------|
231| Analysis | architect, architect-medium, architect-low | Debugging, architecture |
232| Execution | executor, executor-low, executor-high | Code implementation |
233| Search | explore, explore-high | Codebase exploration |
234| Research | document-specialist | External documentation |
235| Frontend | designer, designer-low, designer-high | UI/UX work |
236| Documentation | writer | Technical writing |
237| Visual | vision | Image/screenshot analysis |
238| Planning | planner, analyst, critic | Strategic planning |
239| Testing | qa-tester | Interactive testing |
240| Security | security-reviewer, security-reviewer-low | Security audits |
241| TDD | test-engineer | Test-driven development |
242| Review | code-reviewer | Code quality + style + performance |
243| Data | scientist, scientist-high | Data analysis |
244 
245<!-- MANUAL:
246- Legacy alias wording was removed from active prompts to keep agent naming consistent with current conventions.
247- Consensus planning prompts (planner/architect/critic) now enforce RALPLAN-DR structured deliberation, including `--deliberate` high-risk checks.
248-->
249