# Agent Selection Guide

This directory contains specialized agents for codebase exploration and research. Each agent has a specific purpose and set of tools.

## When to Use Each Agent

### codebase-locator
**Use when you need to find WHERE code lives**

- Locating files relevant to a feature or module
- Finding all components related to a functionality
- Discovering test files, config files, or documentation
- Getting a structured overview of what exists where

**Example queries:**
- "Where is the order cancellation functionality?"
- "Find all files related to product variants"
- "Locate the authentication middleware"

**Output:** Grouped file paths by category (implementation, tests, config, docs, types)

---

### codebase-analyzer
**Use when you need to understand HOW code works**

- Tracing data flow through the system
- Understanding how a feature is implemented
- Explaining technical implementation details
- Following execution paths and call chains
- Understanding complex logic or algorithms

**Example queries:**
- "How does the order creation workflow process payments?"
- "Trace how product prices are calculated"
- "Explain the authentication flow from login to token generation"

**Output:** Detailed technical explanations with file:line references

---

### codebase-pattern-finder
**Use when you need examples to model after**

- Finding similar implementations as templates
- Discovering usage examples of a library or pattern
- Understanding how to implement something based on existing code
- Identifying consistent patterns across the codebase

**Example queries:**
- "Show me examples of API routes with validation"
- "Find similar workflow implementations"
- "How are other modules handling soft deletes?"

**Output:** Concrete code examples with context and usage patterns

---

### web-search-researcher
**Use when you need external information**

- Researching libraries, frameworks, or tools
- Finding documentation for third-party packages
- Understanding industry standards or best practices
- Getting information not available in the codebase

**Example queries:**
- "What are the latest Stripe API payment methods?"
- "Find TypeScript best practices for dependency injection"
- "Research OAuth 2.0 PKCE flow implementation"

**Output:** Synthesized research with source citations

---

## Agent Comparison Matrix

| Agent | Focus | Tools | When to Use |
|-------|-------|-------|-------------|
| **codebase-locator** | WHERE (location) | Grep, Glob, LS | Finding files and directories |
| **codebase-analyzer** | HOW (implementation) | Read, Grep, Glob, LS | Understanding technical details |
| **codebase-pattern-finder** | EXAMPLES (patterns) | Grep, Glob, Read, LS | Finding templates to model after |
| **web-search-researcher** | EXTERNAL (research) | WebSearch, WebFetch | Getting information from the web |

## Constraints

All agents follow these principles:
- **Read-only**: No modifications to code
- **Objective**: No recommendations or critiques
- **Focused**: Stay within their specific domain
- **Accurate**: Provide exact file:line references
- **Complete**: Read files fully, not partially

## Tips

1. **Start with locator**: If you don't know where code lives, use codebase-locator first
2. **Then analyze**: Once you know where, use codebase-analyzer to understand how it works
3. **Find patterns**: Use codebase-pattern-finder to see similar implementations
4. **Research externally**: Use web-search-researcher for non-codebase information
5. **Combine agents**: Use multiple agents in parallel for comprehensive exploration