agent-awareness

# Agent Awareness Guide

You have access to specialized agents that are MORE EFFICIENT than basic tools. You MUST use these agents instead of grep, glob, or generic Task agents.

## Decision Tree

**Finding files or components?**
→ Use `codebase-locator` agent
- Better than: grep, glob, find, ls
- Example: "Find all authentication-related files"

**Understanding how code works?**
→ Use `codebase-analyzer` agent
- Better than: Reading multiple files manually
- Example: "Analyze how the login flow works"

**Finding similar implementations or patterns?**
→ Use `codebase-pattern-finder` agent
- Better than: Searching and reading manually
- Example: "Find examples of API handlers"

**Finding documentation in thoughts/?**
→ Use `thoughts-locator` agent
- Better than: grep in thoughts directory
- Example: "Find research about authentication"

**Understanding specific documents?**
→ Use `thoughts-analyzer` agent
- Better than: Reading docs manually
- Example: "Extract key insights from these research docs"

**Researching external information?**
→ Use `web-search-researcher` agent
- Only when user explicitly asks for web research
- Example: "Research how JWT tokens work"

**Analyzing complex errors or stack traces?**
→ Use `error-analyzer` agent
- Better than: Reading multiple files manually to understand error
- Example: "Analyze this panic: nil pointer dereference at handler.go:42"

## Available Agents

| Task Type | Use This subagent_type |
|-----------|----------------------|
| Finding files/components | `codebase-locator` |
| Understanding code | `codebase-analyzer` |
| Finding similar patterns | `codebase-pattern-finder` |
| Finding documentation | `thoughts-locator` |
| Analyzing documents | `thoughts-analyzer` |
| Web research | `web-search-researcher` |
| Analyzing errors | `error-analyzer` |

## When to Use Agents

### ALWAYS Use Agents For:
- "Find all files that..."
- "Where is the code for..."
- "How does [feature] work?"
- "Find examples of..."
- "Show me simil