feat: prepare for pydantic-ai migration following CUPID principles

AGENTS.md

@@ -39,6 +39,21 @@
       assignee: Optional[str] = None
   ```
 
+## CUPID Programming Principles
+
+- **Composable**: Write small, modular agents and tools with clear interfaces and dependency injection (`RunContext`).
+- **Unix-like**: Each agent or tool has a single responsibility and does one thing well.
+- **Predictable**: Use structured outputs (`result_type` with Pydantic models) to eliminate ambiguous text responses.
+- **Idiomatic**: Follow modern Python type hints (`list[str]`, `dict[str, Any]`), standard Pydantic v2 schemas, and Pydantic AI idioms.
+- **Domain-based**: Structure code and data around domain concepts (`NotificationDecision`, `CoordinatorDecision`, `ExecutionPlan`) rather than LLM framework mechanics.
+
+## Pydantic AI Integration Guidelines
+
+- Use `pydantic_ai.Agent` as the primary execution engine for all AI agents.
+- Define structured result schemas using Pydantic `BaseModel` for predictable output handling.
+- Pass runtime dependencies into tools using `pydantic_ai.RunContext` and typed dependency containers.
+- Register tools using `@agent.tool` or modular toolsets for clean separation of concerns.
+
 ## Follow all instructions provided in the system prompt.
 - Keep responses concise and direct.
 - Minimize output tokens.

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "trafilatura>=1.12",
     "readability-lxml>=0.8",
     "markdownify>=0.13",
+    "pydantic-ai>=2.8.0",
 ]
 
 [project.scripts]