webber/src/domains/agents/README.md

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

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.