docs: expand agent and tool documentation with detailed descriptions

agents/README.md:
- Added detailed descriptions for Explore, Plan, and Task agents
- Documented capabilities, when to use, and tools available
- Added utilities/ section for shared prompts

tools/README.md:
- Added detailed descriptions for file, shell, and search tools
- Documented key parameters and behaviors
- Added security notes for bash/sandbox

agents/utilities/:
- todowrite-prompt.md - Task list management
- askuserquestion-prompt.md - User clarification
- conversation-summarization-prompt.md - Context compaction
- session-title-prompt.md - Title/branch generation
- security-review-prompt.md - Security analysis

Source: gitea:library/claude-code-system-prompts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/domains/agents/README.md

@@ -2,25 +2,107 @@
 
 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
+├── 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)
 │
-├── explore/         # Explore agent - codebase navigation
-│   ├── agent.py     # PydanticAI agent definition
-│   └── prompts.py   # System prompts
+├── 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
 │
-├── plan/            # Plan agent - implementation design
+├── 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
+│   ├── prompts.py
+│   └── example-prompt.md        # Plan mode + system reminders
 │
-└── task/            # Task agent - execution
+└── task/
+    ├── __init__.py
     ├── agent.py
-    └── prompts.py
+    ├── prompts.py
+    └── example-prompt.md        # Task agent prompts
 ```
 
 ## PydanticAI Pattern
@@ -51,3 +133,11 @@ async def search_files(ctx, pattern: str) -> str:
 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.