# Agents Domain

This domain contains PydanticAI agent definitions and orchestration.

## Agent Types

### Explore Agent (`explore/`)
**Purpose:** Fast codebase exploration and navigation.

**Capabilities:**
- Find files by glob patterns (e.g., `src/**/*.py`)
- Search code for keywords and patterns
- Answer questions about codebase structure
- Quick context gathering before deeper work

**Thoroughness Levels:**
- `quick` - Basic searches, first matches
- `medium` - Moderate exploration across key locations
- `very thorough` - Comprehensive analysis, multiple naming conventions

**Tools Available:** Glob, Grep, Read

**Example Use Cases:**
- "Where are API endpoints defined?"
- "Find all files related to authentication"
- "What's the project structure?"

---

### Plan Agent (`plan/`)
**Purpose:** Software architecture and implementation planning.

**Capabilities:**
- Design implementation strategies for complex tasks
- Identify critical files and dependencies
- Consider architectural trade-offs
- Create step-by-step implementation plans
- Multi-file change coordination

**When to Use:**
- New feature implementation requiring architectural decisions
- Multiple valid approaches exist
- Changes affect existing behavior or structure
- Task will touch more than 2-3 files
- Requirements are unclear and need exploration first

**Tools Available:** All tools (read-only exploration)

**Output:** Step-by-step plan for user approval before implementation.

---

### Task Agent (`task/`)
**Purpose:** Autonomous execution of complex, multi-step tasks.

**Capabilities:**
- Handle tasks requiring multiple tool calls
- Work autonomously with full context
- Return consolidated results to parent agent
- Execute implementation after plan approval

**Sub-Agent Types (from Task tool):**
- `Bash` - Command execution, git operations
- `general-purpose` - Research, code search, multi-step tasks
- `Explore` - Fast codebase exploration (see above)
- `Plan` - Implementation design (see above)

**Tools Available:** Varies by sub-agent type

---

## Structure

```
agents/
├── router.py                    # Agent routes (list, run)
├── controller.py                # Agent orchestration logic
├── schemas.py                   # Request/response models
├── main-system-prompt-reference.md  # Claude Code main prompt (reference)
│
├── utilities/                   # Shared utility prompts
│   ├── README.md
│   ├── todowrite-prompt.md      # Task management
│   ├── askuserquestion-prompt.md # User clarification
│   ├── conversation-summarization-prompt.md
│   ├── session-title-prompt.md
│   └── security-review-prompt.md
│
├── explore/
│   ├── __init__.py
│   ├── agent.py                 # PydanticAI agent definition
│   ├── prompts.py               # System prompts
│   └── example-prompt.md        # Reference from claude-code
│
├── plan/
│   ├── __init__.py
│   ├── agent.py
│   ├── prompts.py
│   └── example-prompt.md        # Plan mode + system reminders
│
└── task/
    ├── __init__.py
    ├── agent.py
    ├── prompts.py
    └── example-prompt.md        # Task agent prompts
```

## PydanticAI Pattern

```python
from pydantic_ai import Agent
from pydantic_ai.models.ollama import OllamaModel
from src.shared.config import get_settings

settings = get_settings()

explore_agent = Agent(
    OllamaModel(settings.ollama_agent_model, base_url=settings.ollama_url),
    system_prompt='You are a code exploration assistant...',
)

@explore_agent.tool
async def search_files(ctx, pattern: str) -> str:
    """Search for files matching pattern."""
    # Implementation uses tools from src/domains/tools/
    pass
```

## Adding a New Agent

1. Create a new directory under `agents/` (e.g., `agents/review/`)
2. Create `agent.py` with PydanticAI Agent definition
3. Create `prompts.py` with system prompts
4. Register in `controller.py`
5. Add tests in `tests/domains/test_agents/`

## Reference Prompts

Each agent directory contains an `example-prompt.md` file with reference prompts
from the claude-code-system-prompts repository. These serve as templates for
implementing the PydanticAI agents.

See also: `main-system-prompt-reference.md` for the core system prompt patterns.