OPTIMIZATION.md - Token Usage & Subagent Strategy

## SUBAGENT USAGE STRATEGY

Subagents run in separate contexts and preserve main conversation tokens.

### When to Use Subagents

**Use Subagents for:**
- Large-scale codebase exploration and analysis
- Complex multi-step investigations across many files
- Detailed code pattern searches and refactoring analysis
- Gathering comprehensive information before main conversation work
- When total tokens would exceed 30,000 in main conversation

**Keep in Main Conversation:**
- Direct file edits (1-3 files)
- Simple code changes and debugging
- Architecture decisions
- Security reviews and approvals
- User-facing responses and recommendations
- Questions requiring reasoning about codebase
- Frontend UI work (use `frontend-design` skill for new components)

### Subagent Types & When to Use

**Explore Agent** (Haiku 3.5)
- Codebase exploration and file discovery
- Pattern searching across large codebases
- Gathering information about file structure
- Finding references and relationships

**General-Purpose Agent** (Haiku 3.5)
- Multi-step code analysis tasks
- Summarizing findings from exploration
- Complex searches requiring multiple strategies
- Collecting data for main conversation decisions

---

## MODEL SELECTION STRATEGY

### Main Conversation (Sonnet 4.5)
- **Always use Sonnet 4.5 in main conversation**
- Direct file edits and modifications
- Architecture and design decisions
- Security analysis and approvals
- Complex reasoning and recommendations
- Final user responses

### Subagent Models

**Haiku 4.5** (Default for subagents)
- Code exploration and pattern searching
- File discovery and structure analysis
- Simple codebase investigations
- Gathering information and summarizing
- Task: Use Haiku first for subagent work

**Sonnet 4.5** (For subagents - when needed)
- Security-critical analysis within subagents
- Complex architectural decisions needed in exploration
- High-risk code analysis
- When exploration requires advanced reasoning

---

## RATE LIMITING GUIDANCE

### API Call Throttling
- 5 seconds minimum between API calls
- 10 seconds minimum between web searches
- Batch similar work whenever possible
- If you hit 429 error: STOP and wait 5 minutes

### Budget Management
- Track tokens used across all agents
- Main conversation should stay under 100,000 tokens
- Subagent work can extend to 50,000 tokens per agent
- Batch multiple subagent tasks together when possible

---

## TOKEN PRESERVATION RULES

### Best Practices for Long-Running Conversations

**In Main Conversation:**
1. Start with subagent for exploration (saves ~20,000 tokens)
2. Request subagent summarize findings
3. Use summary to inform main conversation edits/decisions
4. Keep main conversation focused on decisions and actions

**Information Gathering:**
- Use subagents to explore before asking for analysis in main conversation
- Have subagent provide condensed summaries (250-500 words max)
- Main conversation uses summary + provides feedback/decisions

**File Editing:**
- For <3 files: Keep in main conversation
- For 3+ files: Split between subagent (finding/analysis) and main (approval/execution)
- Simple edits (1-5 lines per file): Main conversation
- Complex refactoring (10+ lines per file): Subagent analysis + main approval

**Code Review Workflow:**
1. Subagent explores and analyzes code patterns
2. Subagent flags issues and suggests improvements
3. Main conversation reviews suggestions
4. Main conversation executes approved changes

### Token Budget Allocation Example
- Main conversation: 0-100,000 tokens (soft limit)
- Per subagent task: 0-50,000 tokens
- Critical work (security): Use Sonnet in main conversation
- Exploratory work: Use Explore agent (Haiku) in subagent

---

## DECISION TREE

```
Is this a direct file edit request?
├─ YES (1-3 files, <10 lines each) → Main conversation
├─ NO
└─ Is this exploratory analysis?
   ├─ YES (finding files, patterns) → Use Explore agent (Haiku)
   ├─ NO
   └─ Is this complex multi-step work?
      ├─ YES (3+ steps, many files) → Use General agent (Haiku)
      ├─ NO
      └─ Is this security-critical?
         ├─ YES → Main conversation (Sonnet)
         └─ NO → Subagent (Haiku) or Main conversation
```

---

## SUMMARY

**Main Conversation (You):** Architecture, decisions, edits, reviews
**Subagents:** Exploration, analysis, information gathering
**Sonnet 4.5:** Security, complexity, final decisions
**Haiku 4.5:** Exploration, gathering, analysis support