diff --git a/claude-code-full-guide/cursor.md b/claude-code-full-guide/cursor.md
new file mode 100644
index 0000000000..2a2bffec81
--- /dev/null
+++ b/claude-code-full-guide/cursor.md
@@ -0,0 +1,759 @@
+# CLAUDE.md
+
+This file provides comprehensive guidance to Claude Code when working with Python code in this repository.
+
+## Core Development Philosophy
+
+### KISS (Keep It Simple, Stupid)
+
+Simplicity should be a key goal in design. Choose straightforward solutions over complex ones whenever possible. Simple solutions are easier to understand, maintain, and debug.
+
+### YAGNI (You Aren't Gonna Need It)
+
+Avoid building functionality on speculation. Implement features only when they are needed, not when you anticipate they might be useful in the future.
+
+### Design Principles
+
+- **Dependency Inversion**: High-level modules should not depend on low-level modules. Both should depend on abstractions.
+- **Open/Closed Principle**: Software entities should be open for extension but closed for modification.
+- **Single Responsibility**: Each function, class, and module should have one clear purpose.
+- **Fail Fast**: Check for potential errors early and raise exceptions immediately when issues occur.
+
+## 🧱 Code Structure & Modularity
+
+### File and Function Limits
+
+- **Never create a file longer than 500 lines of code**. If approaching this limit, refactor by splitting into modules.
+- **Functions should be under 50 lines** with a single, clear responsibility.
+- **Classes should be under 100 lines** and represent a single concept or entity.
+- **Organize code into clearly separated modules**, grouped by feature or responsibility.
+- **Line lenght should be max 100 characters** ruff rule in pyproject.toml
+- **Use venv_linux** (the virtual environment) whenever executing Python commands, including for unit tests.
+
+### Project Architecture
+
+Follow strict vertical slice architecture with tests living next to the code they test:
+
+```
+src/project/
+    __init__.py
+    main.py
+    tests/
+        test_main.py
+    conftest.py
+
+    # Core modules
+    database/
+        __init__.py
+        connection.py
+        models.py
+        tests/
+            test_connection.py
+            test_models.py
+
+    auth/
+        __init__.py
+        authentication.py
+        authorization.py
+        tests/
+            test_authentication.py
+            test_authorization.py
+
+    # Feature slices
+    features/
+        user_management/
+            __init__.py
+            handlers.py
+            validators.py
+            tests/
+                test_handlers.py
+                test_validators.py
+
+        payment_processing/
+            __init__.py
+            processor.py
+            gateway.py
+            tests/
+                test_processor.py
+                test_gateway.py
+```
+
+## 🛠️ Development Environment
+
+### UV Package Management
+
+This project uses UV for blazing-fast Python package and environment management.
+
+```bash
+# Install UV (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment
+uv venv
+
+# Sync dependencies
+uv sync
+
+# Add a package ***NEVER UPDATE A DEPENDENCY DIRECTLY IN PYPROJECT.toml***
+# ALWAYS USE UV ADD
+uv add requests
+
+# Add development dependency
+uv add --dev pytest ruff mypy
+
+# Remove a package
+uv remove requests
+
+# Run commands in the environment
+uv run python script.py
+uv run pytest
+uv run ruff check .
+
+# Install specific Python version
+uv python install 3.12
+```
+
+### Development Commands
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific tests with verbose output
+uv run pytest tests/test_module.py -v
+
+# Run tests with coverage
+uv run pytest --cov=src --cov-report=html
+
+# Format code
+uv run ruff format .
+
+# Check linting
+uv run ruff check .
+
+# Fix linting issues automatically
+uv run ruff check --fix .
+
+# Type checking
+uv run mypy src/
+
+# Run pre-commit hooks
+uv run pre-commit run --all-files
+```
+
+## 📋 Style & Conventions
+
+### Python Style Guide
+
+- **Follow PEP8** with these specific choices:
+  - Line length: 100 characters (set by Ruff in pyproject.toml)
+  - Use double quotes for strings
+  - Use trailing commas in multi-line structures
+- **Always use type hints** for function signatures and class attributes
+- **Format with `ruff format`** (faster alternative to Black)
+- **Use `pydantic` v2** for data validation and settings management
+
+### Docstring Standards
+
+Use Google-style docstrings for all public functions, classes, and modules:
+
+```python
+def calculate_discount(
+    price: Decimal,
+    discount_percent: float,
+    min_amount: Decimal = Decimal("0.01")
+) -> Decimal:
+    """
+    Calculate the discounted price for a product.
+
+    Args:
+        price: Original price of the product
+        discount_percent: Discount percentage (0-100)
+        min_amount: Minimum allowed final price
+
+    Returns:
+        Final price after applying discount
+
+    Raises:
+        ValueError: If discount_percent is not between 0 and 100
+        ValueError: If final price would be below min_amount
+
+    Example:
+        >>> calculate_discount(Decimal("100"), 20)
+        Decimal('80.00')
+    """
+```
+
+### Naming Conventions
+
+- **Variables and functions**: `snake_case`
+- **Classes**: `PascalCase`
+- **Constants**: `UPPER_SNAKE_CASE`
+- **Private attributes/methods**: `_leading_underscore`
+- **Type aliases**: `PascalCase`
+- **Enum values**: `UPPER_SNAKE_CASE`
+
+## 🧪 Testing Strategy
+
+### Test-Driven Development (TDD)
+
+1. **Write the test first** - Define expected behavior before implementation
+2. **Watch it fail** - Ensure the test actually tests something
+3. **Write minimal code** - Just enough to make the test pass
+4. **Refactor** - Improve code while keeping tests green
+5. **Repeat** - One test at a time
+
+### Testing Best Practices
+
+```python
+# Always use pytest fixtures for setup
+import pytest
+from datetime import datetime
+
+@pytest.fixture
+def sample_user():
+    """Provide a sample user for testing."""
+    return User(
+        id=123,
+        name="Test User",
+        email="test@example.com",
+        created_at=datetime.now()
+    )
+
+# Use descriptive test names
+def test_user_can_update_email_when_valid(sample_user):
+    """Test that users can update their email with valid input."""
+    new_email = "newemail@example.com"
+    sample_user.update_email(new_email)
+    assert sample_user.email == new_email
+
+# Test edge cases and error conditions
+def test_user_update_email_fails_with_invalid_format(sample_user):
+    """Test that invalid email formats are rejected."""
+    with pytest.raises(ValidationError) as exc_info:
+        sample_user.update_email("not-an-email")
+    assert "Invalid email format" in str(exc_info.value)
+```
+
+### Test Organization
+
+- Unit tests: Test individual functions/methods in isolation
+- Integration tests: Test component interactions
+- End-to-end tests: Test complete user workflows
+- Keep test files next to the code they test
+- Use `conftest.py` for shared fixtures
+- Aim for 80%+ code coverage, but focus on critical paths
+
+## 🚨 Error Handling
+
+### Exception Best Practices
+
+```python
+# Create custom exceptions for your domain
+class PaymentError(Exception):
+    """Base exception for payment-related errors."""
+    pass
+
+class InsufficientFundsError(PaymentError):
+    """Raised when account has insufficient funds."""
+    def __init__(self, required: Decimal, available: Decimal):
+        self.required = required
+        self.available = available
+        super().__init__(
+            f"Insufficient funds: required {required}, available {available}"
+        )
+
+# Use specific exception handling
+try:
+    process_payment(amount)
+except InsufficientFundsError as e:
+    logger.warning(f"Payment failed: {e}")
+    return PaymentResult(success=False, reason="insufficient_funds")
+except PaymentError as e:
+    logger.error(f"Payment error: {e}")
+    return PaymentResult(success=False, reason="payment_error")
+
+# Use context managers for resource management
+from contextlib import contextmanager
+
+@contextmanager
+def database_transaction():
+    """Provide a transactional scope for database operations."""
+    conn = get_connection()
+    trans = conn.begin_transaction()
+    try:
+        yield conn
+        trans.commit()
+    except Exception:
+        trans.rollback()
+        raise
+    finally:
+        conn.close()
+```
+
+### Logging Strategy
+
+```python
+import logging
+from functools import wraps
+
+# Configure structured logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+logger = logging.getLogger(__name__)
+
+# Log function entry/exit for debugging
+def log_execution(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        logger.debug(f"Entering {func.__name__}")
+        try:
+            result = func(*args, **kwargs)
+            logger.debug(f"Exiting {func.__name__} successfully")
+            return result
+        except Exception as e:
+            logger.exception(f"Error in {func.__name__}: {e}")
+            raise
+    return wrapper
+```
+
+## 🔧 Configuration Management
+
+### Environment Variables and Settings
+
+```python
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+class Settings(BaseSettings):
+    """Application settings with validation."""
+    app_name: str = "MyApp"
+    debug: bool = False
+    database_url: str
+    redis_url: str = "redis://localhost:6379"
+    api_key: str
+    max_connections: int = 100
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = False
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()
+
+# Usage
+settings = get_settings()
+```
+
+## 🏗️ Data Models and Validation
+
+### Example Pydantic Models strict with pydantic v2
+
+```python
+from pydantic import BaseModel, Field, validator, EmailStr
+from datetime import datetime
+from typing import Optional, List
+from decimal import Decimal
+
+class ProductBase(BaseModel):
+    """Base product model with common fields."""
+    name: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    price: Decimal = Field(..., gt=0, decimal_places=2)
+    category: str
+    tags: List[str] = []
+
+    @validator('price')
+    def validate_price(cls, v):
+        if v > Decimal('1000000'):
+            raise ValueError('Price cannot exceed 1,000,000')
+        return v
+
+    class Config:
+        json_encoders = {
+            Decimal: str,
+            datetime: lambda v: v.isoformat()
+        }
+
+class ProductCreate(ProductBase):
+    """Model for creating new products."""
+    pass
+
+class ProductUpdate(BaseModel):
+    """Model for updating products - all fields optional."""
+    name: Optional[str] = Field(None, min_length=1, max_length=255)
+    description: Optional[str] = None
+    price: Optional[Decimal] = Field(None, gt=0, decimal_places=2)
+    category: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+class Product(ProductBase):
+    """Complete product model with database fields."""
+    id: int
+    created_at: datetime
+    updated_at: datetime
+    is_active: bool = True
+
+    class Config:
+        from_attributes = True  # Enable ORM mode
+```
+
+## 🔄 Git Workflow
+
+### Branch Strategy
+
+- `main` - Production-ready code
+- `develop` - Integration branch for features
+- `feature/*` - New features
+- `fix/*` - Bug fixes
+- `docs/*` - Documentation updates
+- `refactor/*` - Code refactoring
+- `test/*` - Test additions or fixes
+
+### Commit Message Format
+
+Never include claude code, or written by claude code in commit messages
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+``
+Types: feat, fix, docs, style, refactor, test, chore
+
+Example:
+```
+
+feat(auth): add two-factor authentication
+
+- Implement TOTP generation and validation
+- Add QR code generation for authenticator apps
+- Update user model with 2FA fields
+
+Closes #123
+
+````
+
+## 🗄️ Database Naming Standards
+
+### Entity-Specific Primary Keys
+All database tables use entity-specific primary keys for clarity and consistency:
+
+```sql
+-- ✅ STANDARDIZED: Entity-specific primary keys
+sessions.session_id UUID PRIMARY KEY
+leads.lead_id UUID PRIMARY KEY
+messages.message_id UUID PRIMARY KEY
+daily_metrics.daily_metric_id UUID PRIMARY KEY
+agencies.agency_id UUID PRIMARY KEY
+````
+
+### Field Naming Conventions
+
+```sql
+-- Primary keys: {entity}_id
+session_id, lead_id, message_id
+
+-- Foreign keys: {referenced_entity}_id
+session_id REFERENCES sessions(session_id)
+agency_id REFERENCES agencies(agency_id)
+
+-- Timestamps: {action}_at
+created_at, updated_at, started_at, expires_at
+
+-- Booleans: is_{state}
+is_connected, is_active, is_qualified
+
+-- Counts: {entity}_count
+message_count, lead_count, notification_count
+
+-- Durations: {property}_{unit}
+duration_seconds, timeout_minutes
+```
+
+### Repository Pattern Auto-Derivation
+
+The enhanced BaseRepository automatically derives table names and primary keys:
+
+```python
+# ✅ STANDARDIZED: Convention-based repositories
+class LeadRepository(BaseRepository[Lead]):
+    def __init__(self):
+        super().__init__()  # Auto-derives "leads" and "lead_id"
+
+class SessionRepository(BaseRepository[AvatarSession]):
+    def __init__(self):
+        super().__init__()  # Auto-derives "sessions" and "session_id"
+```
+
+**Benefits**:
+
+- ✅ Self-documenting schema
+- ✅ Clear foreign key relationships
+- ✅ Eliminates repository method overrides
+- ✅ Consistent with entity naming patterns
+
+### Model-Database Alignment
+
+Models mirror database fields exactly to eliminate field mapping complexity:
+
+```python
+# ✅ STANDARDIZED: Models mirror database exactly
+class Lead(BaseModel):
+    lead_id: UUID = Field(default_factory=uuid4)  # Matches database field
+    session_id: UUID                               # Matches database field
+    agency_id: str                                 # Matches database field
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    model_config = ConfigDict(
+        use_enum_values=True,
+        populate_by_name=True,
+        alias_generator=None  # Use exact field names
+    )
+```
+
+### API Route Standards
+
+```python
+# ✅ STANDARDIZED: RESTful with consistent parameter naming
+router = APIRouter(prefix="/api/v1/leads", tags=["leads"])
+
+@router.get("/{lead_id}")           # GET /api/v1/leads/{lead_id}
+@router.put("/{lead_id}")           # PUT /api/v1/leads/{lead_id}
+@router.delete("/{lead_id}")        # DELETE /api/v1/leads/{lead_id}
+
+# Sub-resources
+@router.get("/{lead_id}/messages")  # GET /api/v1/leads/{lead_id}/messages
+@router.get("/agency/{agency_id}")  # GET /api/v1/leads/agency/{agency_id}
+```
+
+For complete naming standards, see [NAMING_CONVENTIONS.md](./NAMING_CONVENTIONS.md).
+
+## 📝 Documentation Standards
+
+### Code Documentation
+
+- Every module should have a docstring explaining its purpose
+- Public functions must have complete docstrings
+- Complex logic should have inline comments with `# Reason:` prefix
+- Keep README.md updated with setup instructions and examples
+- Maintain CHANGELOG.md for version history
+
+### API Documentation
+
+```python
+from fastapi import APIRouter, HTTPException, status
+from typing import List
+
+router = APIRouter(prefix="/products", tags=["products"])
+
+@router.get(
+    "/",
+    response_model=List[Product],
+    summary="List all products",
+    description="Retrieve a paginated list of all active products"
+)
+async def list_products(
+    skip: int = 0,
+    limit: int = 100,
+    category: Optional[str] = None
+) -> List[Product]:
+    """
+    Retrieve products with optional filtering.
+
+    - **skip**: Number of products to skip (for pagination)
+    - **limit**: Maximum number of products to return
+    - **category**: Filter by product category
+    """
+    # Implementation here
+```
+
+## 🚀 Performance Considerations
+
+### Optimization Guidelines
+
+- Profile before optimizing - use `cProfile` or `py-spy`
+- Use `lru_cache` for expensive computations
+- Prefer generators for large datasets
+- Use `asyncio` for I/O-bound operations
+- Consider `multiprocessing` for CPU-bound tasks
+- Cache database queries appropriately
+
+### Example Optimization
+
+```python
+from functools import lru_cache
+import asyncio
+from typing import AsyncIterator
+
+@lru_cache(maxsize=1000)
+def expensive_calculation(n: int) -> int:
+    """Cache results of expensive calculations."""
+    # Complex computation here
+    return result
+
+async def process_large_dataset() -> AsyncIterator[dict]:
+    """Process large dataset without loading all into memory."""
+    async with aiofiles.open('large_file.json', mode='r') as f:
+        async for line in f:
+            data = json.loads(line)
+            # Process and yield each item
+            yield process_item(data)
+```
+
+## 🛡️ Security Best Practices
+
+### Security Guidelines
+
+- Never commit secrets - use environment variables
+- Validate all user input with Pydantic
+- Use parameterized queries for database operations
+- Implement rate limiting for APIs
+- Keep dependencies updated with `uv`
+- Use HTTPS for all external communications
+- Implement proper authentication and authorization
+
+### Example Security Implementation
+
+```python
+from passlib.context import CryptContext
+import secrets
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def hash_password(password: str) -> str:
+    """Hash password using bcrypt."""
+    return pwd_context.hash(password)
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+def generate_secure_token(length: int = 32) -> str:
+    """Generate a cryptographically secure random token."""
+    return secrets.token_urlsafe(length)
+```
+
+## 🔍 Debugging Tools
+
+### Debugging Commands
+
+```bash
+# Interactive debugging with ipdb
+uv add --dev ipdb
+# Add breakpoint: import ipdb; ipdb.set_trace()
+
+# Memory profiling
+uv add --dev memory-profiler
+uv run python -m memory_profiler script.py
+
+# Line profiling
+uv add --dev line-profiler
+# Add @profile decorator to functions
+
+# Debug with rich traceback
+uv add --dev rich
+# In code: from rich.traceback import install; install()
+```
+
+## 📊 Monitoring and Observability
+
+### Structured Logging
+
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+# Log with context
+logger.info(
+    "payment_processed",
+    user_id=user.id,
+    amount=amount,
+    currency="USD",
+    processing_time=processing_time
+)
+```
+
+## 📚 Useful Resources
+
+### Essential Tools
+
+- UV Documentation: https://github.com/astral-sh/uv
+- Ruff: https://github.com/astral-sh/ruff
+- Pytest: https://docs.pytest.org/
+- Pydantic: https://docs.pydantic.dev/
+- FastAPI: https://fastapi.tiangolo.com/
+
+### Python Best Practices
+
+- PEP 8: https://pep8.org/
+- PEP 484 (Type Hints): https://www.python.org/dev/peps/pep-0484/
+- The Hitchhiker's Guide to Python: https://docs.python-guide.org/
+
+## ⚠️ Important Notes
+
+- **NEVER ASSUME OR GUESS** - When in doubt, ask for clarification
+- **Always verify file paths and module names** before use
+- **Keep CLAUDE.md updated** when adding new patterns or dependencies
+- **Test your code** - No feature is complete without tests
+- **Document your decisions** - Future developers (including yourself) will thank you
+
+## 🔍 Search Command Requirements
+
+**CRITICAL**: Always use `rg` (ripgrep) instead of traditional `grep` and `find` commands:
+
+```bash
+# ❌ Don't use grep
+grep -r "pattern" .
+
+# ✅ Use rg instead
+rg "pattern"
+
+# ❌ Don't use find with name
+find . -name "*.py"
+
+# ✅ Use rg with file filtering
+rg --files | rg "\.py$"
+# or
+rg --files -g "*.py"
+```
+
+**Enforcement Rules:**
+
+```
+(
+    r"^grep\b(?!.*\|)",
+    "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
+),
+(
+    r"^find\s+\S+\s+-name\b",
+    "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
+),
+```
+
+## 🚀 GitHub Flow Workflow Summary
+
+main (protected) ←── PR ←── feature/your-feature
+↓ ↑
+deploy development
+
+### Daily Workflow:
+
+1. git checkout main && git pull origin main
+2. git checkout -b feature/new-feature
+3. Make changes + tests
+4. git push origin feature/new-feature
+5. Create PR → Review → Merge to main
+
+---
+
+_This document is a living guide. Update it as the project evolves and new patterns emerge._
\ No newline at end of file
diff --git a/cursor.md b/cursor.md
new file mode 100644
index 0000000000..f0423f5470
--- /dev/null
+++ b/cursor.md
@@ -0,0 +1,59 @@
+### 🔄 Project Awareness & Context
+- **Always read `PLANNING.md`** at the start of a new conversation to understand the project's architecture, goals, style, and constraints.
+- **Check `TASK.md`** before starting a new task. If the task isn’t listed, add it with a brief description and today's date.
+- **Use consistent naming conventions, file structure, and architecture patterns** as described in `PLANNING.md`.
+- **Use venv_linux** (the virtual environment) whenever executing Python commands, including for unit tests.
+
+### 🧱 Code Structure & Modularity
+- **Never create a file longer than 500 lines of code.** If a file approaches this limit, refactor by splitting it into modules or helper files.
+- **Organize code into clearly separated modules**, grouped by feature or responsibility.
+  For agents this looks like:
+    - `agent.py` - Main agent definition and execution logic 
+    - `tools.py` - Tool functions used by the agent 
+    - `prompts.py` - System prompts
+- **Use clear, consistent imports** (prefer relative imports within packages).
+- **Use clear, consistent imports** (prefer relative imports within packages).
+- **Use python_dotenv and load_env()** for environment variables.
+
+### 🧪 Testing & Reliability
+- **Always create Pytest unit tests for new features** (functions, classes, routes, etc).
+- **After updating any logic**, check whether existing unit tests need to be updated. If so, do it.
+- **Tests should live in a `/tests` folder** mirroring the main app structure.
+  - Include at least:
+    - 1 test for expected use
+    - 1 edge case
+    - 1 failure case
+
+### ✅ Task Completion
+- **Mark completed tasks in `TASK.md`** immediately after finishing them.
+- Add new sub-tasks or TODOs discovered during development to `TASK.md` under a “Discovered During Work” section.
+
+### 📎 Style & Conventions
+- **Use Python** as the primary language.
+- **Follow PEP8**, use type hints, and format with `black`.
+- **Use `pydantic` for data validation**.
+- Use `FastAPI` for APIs and `SQLAlchemy` or `SQLModel` for ORM if applicable.
+- Write **docstrings for every function** using the Google style:
+  ```python
+  def example():
+      """
+      Brief summary.
+
+      Args:
+          param1 (type): Description.
+
+      Returns:
+          type: Description.
+      """
+  ```
+
+### 📚 Documentation & Explainability
+- **Update `README.md`** when new features are added, dependencies change, or setup steps are modified.
+- **Comment non-obvious code** and ensure everything is understandable to a mid-level developer.
+- When writing complex logic, **add an inline `# Reason:` comment** explaining the why, not just the what.
+
+### 🧠 AI Behavior Rules
+- **Never assume missing context. Ask questions if uncertain.**
+- **Never hallucinate libraries or functions** – only use known, verified Python packages.
+- **Always confirm file paths and module names** exist before referencing them in code or tests.
+- **Never delete or overwrite existing code** unless explicitly instructed to or if part of a task from `TASK.md`.
\ No newline at end of file
diff --git a/use-cases/agent-factory-with-subagents/cursor.md b/use-cases/agent-factory-with-subagents/cursor.md
new file mode 100644
index 0000000000..81cf0b6c99
--- /dev/null
+++ b/use-cases/agent-factory-with-subagents/cursor.md
@@ -0,0 +1,717 @@
+# 🏭 Pydantic AI Agent Factory - Global Orchestration Rules
+
+This defines the complete orchestration workflow for the AI Agent Factory system and the principles that apply to ALL Pydantic AI agent development work. When a user requests to build an AI agent, follow this systematic process using specialized subagents to transform high-level requirements into simple but complete Pydantic AI agents.
+
+**Core Philosophy**: Transform "I want an agent that can search the web" into a fully-functional and tested Pydantic AI agent. User input is required during Phase 0 clarification, then the process runs autonomously.
+
+---
+
+## 🎯 Primary Directive
+
+⚠️ **CRITICAL WORKFLOW TRIGGER**: When ANY user request involves creating, building, or developing an AI agent:
+
+1. **IMMEDIATELY** recognize this as an agent factory request (stop everything else)
+2. **MUST** follow Phase 0 first - ask clarifying questions
+3. **WAIT** for user responses
+4. **THEN** check Archon and proceed with workflow
+
+**Factory Workflow Recognition Patterns** (if user says ANY of these):
+- "Build an AI agent that..."
+- "Create an agent for..."  
+- "I need an AI assistant that can..."
+- "Make a Pydantic AI agent..."
+- "I want to build a Pydantic AI agent..."
+- Any request mentioning agent/AI/LLM + functionality
+
+**MANDATORY Archon Integration (happens AFTER Phase 0):**
+1. After getting user clarifications, run `mcp__archon__health_check`
+2. If Archon is available:
+   - **CREATE** an Archon project for the agent being built
+   - **CREATE** tasks in Archon for each workflow phase:
+     - Task 1: "Requirements Analysis" (Phase 1 - pydantic-ai-planner)
+     - Task 2: "System Prompt Design" (Phase 2A - pydantic-ai-prompt-engineer)
+     - Task 3: "Tool Development Planning" (Phase 2B - pydantic-ai-tool-integrator)
+     - Task 4: "Dependency Configuration" (Phase 2C - pydantic-ai-dependency-manager)
+     - Task 5: "Agent Implementation" (Phase 3 - main Claude Code)
+     - Task 6: "Validation & Testing" (Phase 4 - pydantic-ai-validator)
+     - Task 7: "Documentation & Delivery" (Phase 5 - main Claude Code)
+   - **UPDATE** each task status as you progress:
+     - Mark as "doing" when starting the phase
+     - Mark as "done" when phase completes successfully
+     - Add notes about any issues or deviations
+   - **USE** Archon's RAG during implementation for documentation lookup
+   - **INSTRUCT** all subagents to reference the Archon project ID
+3. If Archon is not available: Proceed without it but use TodoWrite for local tracking
+
+**WORKFLOW ENFORCEMENT**: You MUST:
+1. Start with Phase 0 (clarifying questions)
+2. Wait for user response before proceeding
+3. Then systematically progress through ALL phases
+4. Never jump directly to implementation
+
+When you want to use or call upon a subagent, you must invoke the subagent, giving them a prompt and passing control to them.
+
+---
+
+## 🔄 Complete Factory Workflow
+
+### Phase 0: Request Recognition & Clarification
+**Trigger Patterns** (activate factory on any of these):
+- "Build an AI agent that..."
+- "Create an agent for..."
+- "I need an AI assistant that can..."
+- "Make a Pydantic AI agent..."
+- "Develop an LLM agent..."
+- Any request mentioning agent/AI/LLM + functionality
+
+**Immediate Action**:
+```
+1. Acknowledge agent creation request
+2. Ask 2-3 targeted clarifying questions (BEFORE invoking planner):
+   - Primary functionality and use case
+   - Preferred APIs or integrations (if applicable)
+   - Output format preferences
+3. ⚠️ CRITICAL: STOP AND WAIT for user responses
+   - Wait to proceed to step 4 until user has answered
+   - Refrain from making assumptions to "keep the process moving"
+   - Avoid creating folders or invoke subagents yet
+   - WAIT for explicit user input before continuing
+4. Only after user responds: DETERMINE AGENT FOLDER NAME (snake_case, e.g., web_search_agent, asana_manager)
+5. Create agents/[AGENT_FOLDER_NAME]/ directory
+6. Invoke ALL subagents with the EXACT SAME folder name
+7. Tell each subagent: "Output to agents/[AGENT_FOLDER_NAME]/"
+```
+
+### Phase 1: Requirements Documentation 🎯
+**Subagent**: `pydantic-ai-planner`
+**Trigger**: Invoked after Phase 0 clarifications collected
+**Mode**: AUTONOMOUS - Works without user interaction
+**Philosophy**: SIMPLE, FOCUSED requirements - MVP mindset
+**Archon**: Update Task 1 to "doing" before invoking subagent
+
+```
+Actions:
+1. Update Archon Task 1 "Requirements Analysis" to status="doing"
+2. Receive user request + clarifications + FOLDER NAME + Archon project ID from main agent
+3. Analyze requirements focusing on CORE functionality only
+4. Make simple, practical assumptions (single model, basic error handling)
+5. Create minimal INITIAL.md with 2-3 core features maximum
+6. Output: agents/[EXACT_FOLDER_NAME]/planning/INITIAL.md
+   ⚠️ CRITICAL: Output to planning/ subdirectory
+7. Update Archon Task 1 to status="done" after subagent completes
+```
+
+**Quality Gate**: INITIAL.md must include:
+- ✅ Agent classification and type
+- ✅ Functional requirements
+- ✅ Technical requirements
+- ✅ External dependencies
+- ✅ Success criteria
+
+### Phase 2: Parallel Component Development ⚡
+**Execute SIMULTANEOUSLY** (all three subagents work in parallel):
+**Archon**: Update Tasks 2, 3, 4 to "doing" before parallel invocation
+
+**CRITICAL: Use parallel tool invocation:** When invoking multiple subagents, you MUST call all three Task tools in a SINGLE message with multiple tool uses. This ensures true parallel execution.
+- ❌ WRONG: Invoke planner, wait for completion, then invoke prompt engineer
+- ✅ RIGHT: Single message with three Task tool invocations
+- Also update all three Archon tasks (2, 3, 4) to "doing" before the parallel invocation
+
+#### 2A: System Prompt Engineering
+**Subagent**: `pydantic-ai-prompt-engineer`
+**Philosophy**: SIMPLE, CLEAR prompts - typically 100-300 words
+```
+Input: planning/INITIAL.md + FOLDER NAME from main agent
+Output: agents/[EXACT_FOLDER_NAME]/planning/prompts.md
+⚠️ CRITICAL: Output MARKDOWN file with prompt specifications, NOT Python code
+Contents:
+- One simple static system prompt (100-300 words)
+- Skip dynamic prompts unless explicitly needed
+- Focus on essential behavior only
+```
+
+#### 2B: Tool Development Planning
+**Subagent**: `pydantic-ai-tool-integrator`
+**Philosophy**: MINIMAL tools - 2-3 essential functions only
+```
+Input: planning/INITIAL.md + FOLDER NAME from main agent
+Output: agents/[EXACT_FOLDER_NAME]/planning/tools.md
+⚠️ CRITICAL: Output MARKDOWN file with tool specifications, NOT Python code
+Contents:
+- 2-3 essential tool specifications only
+- Simple parameters (1-3 per tool)
+- Basic error handling
+- Single-purpose tools
+```
+
+#### 2C: Dependency Configuration Planning
+**Subagent**: `pydantic-ai-dependency-manager`
+**Philosophy**: MINIMAL config - essential environment variables only
+```
+Input: planning/INITIAL.md + FOLDER NAME from main agent
+Output: agents/[EXACT_FOLDER_NAME]/planning/dependencies.md
+⚠️ CRITICAL: Output MARKDOWN file with dependency specifications, NOT Python code
+Contents:
+- Essential environment variables only
+- Single model provider (no fallbacks)
+- Simple dataclass dependencies
+- Minimal Python packages
+```
+
+**Phase 2 Complete When**: All three subagents report completion
+
+### Phase 3: Agent Implementation 🔨
+**Actor**: Main Claude Code (not a subagent)
+**Archon**: Update Task 5 to "doing" before starting implementation
+
+```
+Actions:
+1. Update Archon Task 5 "Agent Implementation" to status="doing"
+2. Mark Archon Tasks 2, 3, 4 as "done" (after verifying subagents completed)
+3. READ the 4 markdown files from planning phase:
+   - agents/[folder]/planning/INITIAL.md
+   - agents/[folder]/planning/prompts.md
+   - agents/[folder]/planning/tools.md
+   - agents/[folder]/planning/dependencies.md
+4. Use Archon RAG to search for Pydantic AI patterns and examples as needed
+5. IMPLEMENT the actual Python code based on specifications:
+   - Convert prompt specs → prompts.py
+   - Convert tool specs → tools.py
+   - Convert dependency specs → settings.py, providers.py, dependencies.py
+6. Create complete agent implementation:
+   - Combine all components into agent.py
+   - Wire up dependencies and tools
+   - Create main execution file
+7. Update Archon Task 5 to status="done" when implementation completes
+8. Structure final project:
+   agents/[agent_name]/
+   ├── agent.py           # Main agent
+   ├── settings.py        # Configuration
+   ├── providers.py       # Model providers
+   ├── dependencies.py    # Dependencies
+   ├── tools.py          # Tool implementations
+   ├── prompts.py        # System prompts
+   ├── __init__.py       # Package init
+   ├── requirements.txt  # Python deps
+   ├── .env.example      # Environment template
+   └── README.md         # Usage documentation
+```
+
+### Phase 4: Validation & Testing ✅
+**Subagent**: `pydantic-ai-validator`
+**Trigger**: Automatic after implementation
+**Duration**: 3-5 minutes
+**Archon**: Update Task 6 to "doing" before invoking validator
+
+```
+Actions:
+1. Update Archon Task 6 "Validation & Testing" to status="doing"
+2. Invoke validator subagent with agent folder and Archon project ID
+3. Create comprehensive test suite
+4. Validate against INITIAL.md requirements
+5. Run tests with TestModel
+6. Generate validation report
+7. Update Archon Task 6 to status="done" after validation completes
+8. Output: agents/[agent_name]/tests/
+   ├── test_agent.py
+   ├── test_tools.py
+   ├── test_integration.py
+   ├── test_validation.py
+   ├── conftest.py
+   └── VALIDATION_REPORT.md
+```
+
+**Success Criteria**:
+- All requirements validated
+- Core functionality tested
+- Error handling verified
+- Performance acceptable
+
+### Phase 5: Delivery & Documentation 📦
+**Actor**: Main Claude Code
+**Archon**: Update Task 7 to "doing" before final documentation
+**Final Actions**:
+```
+1. Update Archon Task 7 "Documentation & Delivery" to status="doing"
+2. Generate comprehensive README.md
+3. Create usage examples
+4. Document API endpoints (if applicable)
+5. Provide deployment instructions
+6. Update Archon Task 7 to status="done"
+7. Add final notes to Archon project about agent capabilities
+8. Summary report to user with Archon project link
+```
+
+---
+
+## 📋 Archon Task Management Protocol
+
+### Task Creation Flow
+When Archon is available, create all workflow tasks immediately after project creation:
+```python
+# After creating Archon project
+tasks = [
+    {"title": "Requirements Analysis", "assignee": "pydantic-ai-planner"},
+    {"title": "System Prompt Design", "assignee": "pydantic-ai-prompt-engineer"},
+    {"title": "Tool Development Planning", "assignee": "pydantic-ai-tool-integrator"},
+    {"title": "Dependency Configuration", "assignee": "pydantic-ai-dependency-manager"},
+    {"title": "Agent Implementation", "assignee": "Claude Code"},
+    {"title": "Validation & Testing", "assignee": "pydantic-ai-validator"},
+    {"title": "Documentation & Delivery", "assignee": "Claude Code"}
+]
+# Create all tasks with status="todo" initially
+```
+
+### Task Status Updates
+- Set to "doing" immediately before starting each phase
+- Set to "done" immediately after phase completes successfully
+- Add notes if phase encounters issues or deviations
+- Never have multiple tasks in "doing" status (except during parallel Phase 2)
+
+### Subagent Communication
+Always pass the Archon project ID to subagents:
+- Include in the prompt: "Use Archon Project ID: [project-id]"
+- Subagents should reference this in their output for traceability
+
+## 🎭 Subagent Invocation Rules
+
+### Automatic Invocation
+Subagents are invoked AUTOMATICALLY based on workflow phase:
+```python
+if user_request.contains(agent_creation_pattern):
+    # Phase 0 - Main Claude Code asks clarifications
+    clarifications = ask_user_questions()
+    
+    # Phase 1 - Invoke planner with context
+    invoke("pydantic-ai-planner", context={
+        "user_request": original_request,
+        "clarifications": clarifications
+    })
+    
+    # Phase 2 - Parallel automatic
+    parallel_invoke([
+        "pydantic-ai-prompt-engineer",
+        "pydantic-ai-tool-integrator", 
+        "pydantic-ai-dependency-manager"
+    ])
+    
+    # Phase 3 - Main Claude Code
+    implement_agent()
+    
+    # Phase 4 - Automatic
+    invoke("pydantic-ai-validator")
+```
+
+### Manual Override
+Users can explicitly request specific subagents:
+- "Use the planner to refine requirements"
+- "Have the tool integrator add web search"
+- "Run the validator again"
+
+---
+
+## 📁 Output Directory Structure
+
+Every agent factory run creates:
+```
+agents/
+└── [agent_name]/
+    ├── planning/              # All planning documents
+    │   ├── INITIAL.md         # Requirements (planner)
+    │   ├── prompts.md         # Prompt specifications (prompt-engineer)
+    │   ├── tools.md           # Tool specifications (tool-integrator)
+    │   └── dependencies.md    # Dependency specifications (dependency-manager)
+    ├── agent.py               # Main implementation
+    ├── settings.py            # Configuration
+    ├── providers.py           # Model providers
+    ├── dependencies.py        # Dependencies
+    ├── tools.py              # Tools
+    ├── prompts.py            # Prompts
+    ├── cli.py                # CLI interface
+    ├── requirements.txt      # Python packages
+    ├── .env.example          # Environment template
+    ├── README.md             # Documentation
+    └── tests/                # Test suite (if created)
+        ├── test_agent.py
+        └── test_tools.py
+```
+
+---
+
+## 🔧 Implementation Guidelines
+
+### For Simple Agent Requests
+Example: "Build an agent that can search the web"
+```
+1. Planner asks minimal questions (1-2)
+2. Assumes standard patterns (Brave API, string output)
+3. Completes in ~10 minutes total
+4. Delivers working agent with basic tests
+```
+
+### For Complex Agent Requests
+Example: "Build a multi-modal agent with database, caching, and workflow orchestration"
+```
+1. Planner asks comprehensive questions (4-5)
+2. Multiple iterations may be needed
+3. Delivers simple yet complete system with full test coverage
+```
+
+### Error Handling Protocol
+If any subagent fails:
+```
+1. Log error with context
+2. Attempt automatic recovery
+3. If recovery fails, ask user for guidance
+4. Continue with partial implementation if possible
+5. Document limitations in README
+```
+
+---
+
+## 📝 Main Agent Clarification Guidelines
+
+When a user requests an AI agent, the main Claude Code agent should:
+
+### Ask 2-3 Focused Questions
+Keep questions simple and targeted:
+1. **Core Functionality**: "What specific tasks should this agent handle?"
+2. **Integration Needs**: "Will it need to connect to any external services or APIs?"
+3. **Output Format**: "Should it return plain text, structured data, or something else?"
+
+### Avoid Over-Questioning
+- Don't ask about technical details (the planner will handle those)
+- Don't ask about implementation specifics
+- Keep questions high-level and user-friendly
+
+### Pass Context to Planner
+When invoking the planner, provide:
+- Original user request
+- User's answers to clarifying questions
+- Any additional context from the conversation
+
+## 🚀 Quick Start Examples
+
+### Example 1: Web Search Agent
+**User**: "I want to build an AI agent that can search the web"
+
+**Claude Code Response**:
+```
+I'll help you build a web search AI agent using the Pydantic AI framework. Let me ask a few quick questions to better understand your needs:
+
+1. What will the agent primarily search for? (general web content, specific domains, research papers, etc.)
+2. Should the agent summarize the results or return raw search data?
+3. Do you have a preference for which search API to use? (Brave, Google, Bing)
+
+[STOPS HERE AND WAITS FOR USER TO RESPOND]
+
+[After user responds with their answers]
+
+Perfect! Based on your requirements [summarize their answers], I'll now invoke our requirements planner to create a comprehensive specification for your web search agent.
+
+📋 Creating Requirements Document...
+[Invokes pydantic-ai-planner with context]
+
+[Planner works autonomously and creates INITIAL.md]
+
+⚙️ Building Agent Components...
+[Parallel invocation of prompt-engineer, tool-integrator, dependency-manager]
+
+🔨 Implementing Your Agent...
+[Main implementation]
+
+✅ Running Validation...
+[Invokes pydantic-ai-validator]
+
+🎉 Agent Complete!
+Your web search agent is ready at: agents/web_search_agent/
+```
+
+### Example 2: Database Query Agent
+**User**: "Create an agent that can query PostgreSQL databases and explain results"
+
+**Claude Code Response**:
+```
+I'll create a PostgreSQL query agent with explanation capabilities. Let me ask a few quick questions first:
+
+1. What types of queries will this agent need to run? (SELECT only, or also INSERT/UPDATE/DELETE?)
+2. Should it connect to a specific database or handle multiple database connections?
+3. How detailed should the explanations be? (brief summaries or detailed analysis?)
+
+[STOPS HERE AND WAITS FOR USER TO RESPOND]
+
+[After user responds with their answers]
+
+Great! Based on your requirements [summarize their answers], I'll now create a comprehensive requirements document for your PostgreSQL agent.
+
+📋 Creating Requirements Document...
+[Invokes pydantic-ai-planner with context]
+[Process continues autonomously]
+```
+
+---
+
+## 🔍 Monitoring & Debugging
+
+### Progress Tracking
+Claude Code should provide status updates:
+```
+✅ Phase 1: Requirements Complete (INITIAL.md created)
+⏳ Phase 2: Building Components (3 subagents working...)
+  ✅ Prompts: Complete
+  ✅ Tools: Complete
+  ⏳ Dependencies: In progress...
+⏳ Phase 3: Implementation pending...
+⏳ Phase 4: Validation pending...
+```
+
+### Debug Mode
+Enable with: "Build agent in debug mode"
+- Verbose logging from all subagents
+- Intermediate outputs preserved
+- Step-by-step confirmation mode
+- Performance metrics collected
+
+---
+
+## 🛡️ Quality Assurance
+
+### Every Agent MUST Have:
+1. **Comprehensive tests** using TestModel/FunctionModel
+2. **Error handling** for all external operations
+3. **Security measures** for API keys and inputs
+4. **Documentation** for usage and deployment
+5. **Environment template** (.env.example)
+
+### Validation Checklist
+Before delivery, confirm:
+- [ ] All requirements from INITIAL.md implemented
+- [ ] Tests passing with >80% coverage
+- [ ] API keys properly managed
+- [ ] Error scenarios handled
+- [ ] Documentation complete
+- [ ] Usage examples provided
+
+---
+
+## 🎨 Customization Points
+
+### User Preferences
+Users can specify:
+- Preferred LLM provider (OpenAI, Anthropic, Gemini)
+- Output format (string, structured, streaming)
+- Testing depth (basic, comprehensive, exhaustive)
+- Documentation style (minimal, standard, detailed)
+
+### Advanced Features
+For power users:
+- Custom subagent configurations
+- Alternative workflow sequences
+- Integration with existing codebases
+- CI/CD pipeline generation
+
+---
+
+## 📊 Success Metrics
+
+Track factory performance:
+- **Time to Completion**: Target <15 minutes for standard agents
+- **Test Coverage**: Minimum 80% for agents
+- **Validation Pass Rate**: 100% of requirements tested
+- **User Intervention**: Minimize to initial requirements only
+
+---
+
+## 🔄 Continuous Improvement
+
+### Feedback Loop
+After each agent creation:
+1. Analyze what worked well
+2. Identify bottlenecks
+3. Update subagent prompts if needed
+4. Refine workflow based on patterns
+
+### Pattern Library
+Build a library of common patterns:
+- Search agents
+- Database agents
+- Workflow orchestrators
+- Chat interfaces
+- API integrations
+
+---
+
+## 🚨 Important Rules
+
+### ALWAYS:
+- ✅ Use python-dotenv for environment management
+- ✅ Create a .env.example
+- ✅ Follow main_agent_reference patterns
+- ✅ Create comprehensive tests
+- ✅ Document everything
+- ✅ Validate against requirements
+
+### Anti-patterns to ALWAYS avoid:
+- ❌ Hardcode API keys or secrets
+- ❌ Skip testing phase
+- ❌ Ignore error handling
+- ❌ Create overly complex agents
+- ❌ Forget security considerations
+
+---
+
+## 🎯 Final Checklist
+
+Before considering an agent complete:
+- [ ] Requirements captured in INITIAL.md
+- [ ] All components generated by subagents
+- [ ] Agent implementation complete and functional
+- [ ] Tests written and passing
+- [ ] Documentation comprehensive
+- [ ] Security measures in place
+- [ ] User provided with clear next steps
+
+---
+
+
+## 🔄 Pydantic AI Core Principles
+
+**IMPORTANT: These principles apply to ALL Pydantic AI agent development:**
+
+### Research Methodology for AI Agents
+- **Web search extensively** - Always research Pydantic AI patterns and best practices
+- **Study official documentation** - ai.pydantic.dev is the authoritative source
+- **Pattern extraction** - Identify reusable agent architectures and tool patterns
+- **Gotcha documentation** - Document async patterns, model limits, and context management issues
+
+## 📚 Project Awareness & Context
+
+- **Use a virtual environment** to run all code and tests. If one isn't already in the codebase when needed, create it
+- **Use consistent Pydantic AI naming conventions** and agent structure patterns
+- **Follow established agent directory organization** patterns (agent.py, tools.py, models.py)
+- **Leverage Pydantic AI examples extensively** - Study existing patterns before creating new agents
+
+## 🧱 Agent Structure & Modularity
+
+- **Never create files longer than 500 lines** - Split into modules when approaching limit
+- **Organize agent code into clearly separated modules** grouped by responsibility:
+  - `agent.py` - Main agent definition and execution logic
+  - `tools.py` - Tool functions used by the agent
+  - `models.py` - Pydantic output models and dependency classes
+  - `dependencies.py` - Context dependencies and external service integrations
+- **Use clear, consistent imports** - Import from pydantic_ai package appropriately
+- **Use python-dotenv and load_dotenv()** for environment variables - Follow examples/main_agent_reference/settings.py pattern
+- **Never hardcode sensitive information** - Always use .env files for API keys and configuration
+
+## 🤖 Pydantic AI Development Standards
+
+### Agent Creation Patterns
+- **Use model-agnostic design** - Support multiple providers (OpenAI, Anthropic, Gemini)
+- **Implement dependency injection** - Use deps_type for external services and context
+- **Define structured outputs** - Use Pydantic models for result validation
+- **Include comprehensive system prompts** - Both static and dynamic instructions
+
+### Tool Integration Standards
+- **Use @agent.tool decorator** for context-aware tools with RunContext[DepsType]
+- **Use @agent.tool_plain decorator** for simple tools without context dependencies
+- **Implement proper parameter validation** - Use Pydantic models for tool parameters
+- **Handle tool errors gracefully** - Implement retry mechanisms and error recovery
+
+### Environment Variable Configuration with python-dotenv
+```python
+# Use python-dotenv and pydantic-settings for proper configuration management
+from pydantic_settings import BaseSettings
+from pydantic import Field, ConfigDict
+from dotenv import load_dotenv
+from pydantic_ai.providers.openai import OpenAIProvider
+from pydantic_ai.models.openai import OpenAIModel
+
+class Settings(BaseSettings):
+    """Application settings with environment variable support."""
+    
+    model_config = ConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore"
+    )
+    
+    # LLM Configuration
+    llm_provider: str = Field(default="openai", description="LLM provider")
+    llm_api_key: str = Field(..., description="API key for the LLM provider")
+    llm_model: str = Field(default="gpt-4", description="Model name to use")
+    llm_base_url: str = Field(
+        default="https://api.openai.com/v1", 
+        description="Base URL for the LLM API"
+    )
+
+def load_settings() -> Settings:
+    """Load settings with proper error handling and environment loading."""
+    # Load environment variables from .env file
+    load_dotenv()
+    
+    try:
+        return Settings()
+    except Exception as e:
+        error_msg = f"Failed to load settings: {e}"
+        if "llm_api_key" in str(e).lower():
+            error_msg += "\nMake sure to set LLM_API_KEY in your .env file"
+        raise ValueError(error_msg) from e
+
+def get_llm_model():
+    """Get configured LLM model with proper environment loading."""
+    settings = load_settings()
+    provider = OpenAIProvider(
+        base_url=settings.llm_base_url, 
+        api_key=settings.llm_api_key
+    )
+    return OpenAIModel(settings.llm_model, provider=provider)
+```
+
+### Testing Standards for AI Agents
+- **Use TestModel for development** - Fast validation without API calls
+- **Use FunctionModel for custom behavior** - Control agent responses in tests
+- **Use Agent.override() for testing** - Replace models in test contexts
+- **Test both sync and async patterns** - Ensure compatibility with different execution modes
+- **Test tool validation** - Verify tool parameter schemas and error handling
+
+## ✅ Task Management for AI Development
+
+- **Break agent development into clear steps** with specific completion criteria
+- **Mark tasks complete immediately** after finishing agent implementations
+- **Update task status in real-time** as agent development progresses
+- **Test agent behavior** before marking implementation tasks complete
+
+## 📎 Pydantic AI Coding Standards
+
+### Agent Architecture
+```python
+# Follow main_agent_reference patterns - no result_type unless structured output needed
+from pydantic_ai import Agent, RunContext
+from dataclasses import dataclass
+from .settings import load_settings
+
+@dataclass
+class AgentDependencies:
+    """Dependencies for agent execution"""
+    api_key: str
+    session_id: str = None
+
+# Load settings with proper dotenv handling
+settings = load_settings()
+
+# Simple agent with string output (default)
+agent = Agent(
+    get_llm_model(),  # Uses load_settings() internally
+    deps_type=AgentDependencies,
+    system_prompt="You are a helpful assistant..."
+)
+
+@agent.tool
+async def example_tool(
+    ctx: RunContext[AgentDependencies], 
+    query: str
+) -> str:
+    """Tool with proper context access"""
+    return await external_api_call(ctx.deps.api_key, query)
+```
diff --git a/use-cases/mcp-server/cursor.md b/use-cases/mcp-server/cursor.md
new file mode 100644
index 0000000000..c8b7a7e44b
--- /dev/null
+++ b/use-cases/mcp-server/cursor.md
@@ -0,0 +1,835 @@
+# MCP Server with GitHub OAuth - Implementation Guide
+
+This guide provides implementation patterns and standards for building MCP (Model Context Protocol) servers with GitHub OAuth authentication using Node.js, TypeScript, and Cloudflare Workers. For WHAT to build, see the PRP (Product Requirement Prompt) documents.
+
+## Core Principles
+
+**IMPORTANT: You MUST follow these principles in all code changes and PRP generations:**
+
+### KISS (Keep It Simple, Stupid)
+
+- Simplicity should be a key goal in design
+- Choose straightforward solutions over complex ones whenever possible
+- Simple solutions are easier to understand, maintain, and debug
+
+### YAGNI (You Aren't Gonna Need It)
+
+- Avoid building functionality on speculation
+- Implement features only when they are needed, not when you anticipate they might be useful in the future
+
+### Open/Closed Principle
+
+- Software entities should be open for extension but closed for modification
+- Design systems so that new functionality can be added with minimal changes to existing code
+
+## Package Management & Tooling
+
+**CRITICAL: This project uses npm for Node.js package management and Wrangler CLI for Cloudflare Workers development.**
+
+### Essential npm Commands
+
+```bash
+# Install dependencies from package.json
+npm install
+
+# Add a dependency
+npm install package-name
+
+# Add a development dependency
+npm install --save-dev package-name
+
+# Remove a package
+npm uninstall package-name
+
+# Update dependencies
+npm update
+
+# Run scripts defined in package.json
+npm run dev
+npm run deploy
+npm run type-check
+```
+
+### Essential Wrangler CLI Commands
+
+**CRITICAL: Use Wrangler CLI for all Cloudflare Workers development, testing, and deployment.**
+
+```bash
+# Authentication
+wrangler login          # Login to Cloudflare account
+wrangler logout         # Logout from Cloudflare
+wrangler whoami         # Check current user
+
+# Development & Testing
+wrangler dev           # Start local development server (default port 8787)
+
+# Deployment
+wrangler deploy        # Deploy Worker to Cloudflare
+wrangler deploy --dry-run  # Test deployment without actually deploying
+
+# Configuration & Types
+wrangler types         # Generate TypeScript types from Worker configuration
+```
+
+## Project Architecture
+
+**IMPORTANT: This is a Cloudflare Workers MCP server with GitHub OAuth authentication for secure database access.**
+
+### Current Project Structure
+
+```
+/
+├── src/                          # TypeScript source code
+│   ├── index.ts                  # Main MCP server (standard)
+│   ├── index_sentry.ts          # Sentry-enabled MCP server
+│   ├── simple-math.ts           # Basic MCP example (no auth)
+│   ├── github-handler.ts        # GitHub OAuth flow implementation
+│   ├── database.ts              # PostgreSQL connection & utilities
+│   ├── utils.ts                 # OAuth helper functions
+│   ├── workers-oauth-utils.ts   # Cookie-based approval system
+│   └── tools/                   # Tool registration system
+│       └── register-tools.ts    # Centralized tool registration
+├── PRPs/                        # Product Requirement Prompts
+│   ├── README.md
+│   └── templates/
+│       └── prp_mcp_base.md
+├── examples/                    # Example tool creation + registration - NEVER edit or import from this folder
+│   ├── database-tools.ts        # Example tools for a Postgres MCP server showing best practices for tool creation and registration
+│   └── database-tools-sentry.ts # Example tools for the Postgres MCP server but with the Sentry integration for production monitoring
+├── wrangler.jsonc              # Main Cloudflare Workers configuration
+├── wrangler-simple.jsonc       # Simple math example configuration
+├── package.json                # npm dependencies & scripts
+├── tsconfig.json               # TypeScript configuration
+├── worker-configuration.d.ts   # Generated Cloudflare types
+└── CLAUDE.md                   # This implementation guide
+```
+
+### Key File Purposes (ALWAYS ADD NEW FILES HERE)
+
+**Main Implementation Files:**
+
+- `src/index.ts` - Production MCP server with GitHub OAuth + PostgreSQL
+- `src/index_sentry.ts` - Same as above with Sentry monitoring integration
+
+**Authentication & Security:**
+
+- `src/github-handler.ts` - Complete GitHub OAuth 2.0 flow
+- `src/workers-oauth-utils.ts` - HMAC-signed cookie approval system
+- `src/utils.ts` - OAuth token exchange and URL construction helpers
+
+**Database Integration:**
+
+- `src/database.ts` - PostgreSQL connection pooling, SQL validation, security
+
+**Tool Registration:**
+
+- `src/tools/register-tools.ts` - Centralized tool registration system that imports and registers all tools
+
+**Configuration Files:**
+
+- `wrangler.jsonc` - Main Worker config with Durable Objects, KV, AI bindings
+- `wrangler-simple.jsonc` - Simple example configuration
+- `tsconfig.json` - TypeScript compiler settings for Cloudflare Workers
+
+## Development Commands
+
+### Core Workflow Commands
+
+```bash
+# Setup & Dependencies
+npm install                  # Install all dependencies
+npm install --save-dev @types/package  # Add dev dependency with types
+
+# Development
+wrangler dev                # Start local development server
+npm run dev                 # Alternative via npm script
+
+# Type Checking & Validation
+npm run type-check          # Run TypeScript compiler check
+wrangler types              # Generate Cloudflare Worker types
+npx tsc --noEmit           # Type check without compiling
+
+# Testing
+npx vitest                  # Run unit tests (if configured)
+
+# Code Quality
+npx prettier --write .      # Format code
+npx eslint src/            # Lint TypeScript code
+```
+
+### Environment Configuration
+
+**Environment Variables Setup:**
+
+```bash
+# Create .dev.vars file for local development based on .dev.vars.example
+cp .dev.vars.example .dev.vars
+
+# Production secrets (via Wrangler)
+wrangler secret put GITHUB_CLIENT_ID
+wrangler secret put GITHUB_CLIENT_SECRET
+wrangler secret put COOKIE_ENCRYPTION_KEY
+wrangler secret put DATABASE_URL
+wrangler secret put SENTRY_DSN
+```
+
+## MCP Development Context
+
+**IMPORTANT: This project builds production-ready MCP servers using Node.js/TypeScript on Cloudflare Workers with GitHub OAuth authentication.**
+
+### MCP Technology Stack
+
+**Core Technologies:**
+
+- **@modelcontextprotocol/sdk** - Official MCP TypeScript SDK
+- **agents/mcp** - Cloudflare Workers MCP agent framework
+- **workers-mcp** - MCP transport layer for Workers
+- **@cloudflare/workers-oauth-provider** - OAuth 2.1 server implementation
+
+**Cloudflare Platform:**
+
+- **Cloudflare Workers** - Serverless runtime (V8 isolates)
+- **Durable Objects** - Stateful objects for MCP agent persistence
+- **KV Storage** - OAuth state and session management
+
+### MCP Server Architecture
+
+This project implements MCP servers as Cloudflare Workers with three main patterns:
+
+**1. Authenticated Database MCP Server (`src/index.ts`):**
+
+```typescript
+export class MyMCP extends McpAgent<Env, Record<string, never>, Props> {
+  server = new McpServer({
+    name: "PostgreSQL Database MCP Server",
+    version: "1.0.0",
+  });
+
+  // MCP Tools available based on user permissions
+  // - listTables (all users)
+  // - queryDatabase (all users, read-only)
+  // - executeDatabase (privileged users only)
+}
+```
+
+**2. Monitored MCP Server (`src/index_sentry.ts`):**
+
+- Same functionality as above with Sentry instrumentation
+- Distributed tracing for MCP tool calls
+- Error tracking with event IDs
+- Performance monitoring
+
+### MCP Development Commands
+
+**Local Development & Testing:**
+
+```bash
+# Start main MCP server (with OAuth)
+wrangler dev                    # Available at http://localhost:8792/mcp
+```
+
+### Claude Desktop Integration
+
+**For Local Development:**
+
+```json
+{
+  "mcpServers": {
+    "database-mcp": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://localhost:8792/mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+**For Production Deployment:**
+
+```json
+{
+  "mcpServers": {
+    "database-mcp": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://your-worker.workers.dev/mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### MCP Key Concepts for This Project
+
+- **Tools**: Database operations (listTables, queryDatabase, executeDatabase)
+- **Authentication**: GitHub OAuth with role-based access control
+- **Transport**: Dual support for HTTP (`/mcp`) and SSE (`/sse`) protocols
+- **State**: Durable Objects maintain authenticated user context
+- **Security**: SQL injection protection, permission validation, error sanitization
+
+## Database Integration & Security
+
+**CRITICAL: This project provides secure PostgreSQL database access through MCP tools with role-based permissions.**
+
+### Database Architecture
+
+**Connection Management (`src/database.ts`):**
+
+```typescript
+// Singleton connection pool with Cloudflare Workers limits
+export function getDb(databaseUrl: string): postgres.Sql {
+  if (!dbInstance) {
+    dbInstance = postgres(databaseUrl, {
+      max: 5, // Max 5 connections for Workers
+      idle_timeout: 20,
+      connect_timeout: 10,
+      prepare: true, // Enable prepared statements
+    });
+  }
+  return dbInstance;
+}
+
+// Connection wrapper with error handling
+export async function withDatabase<T>(databaseUrl: string, operation: (db: postgres.Sql) => Promise<T>): Promise<T> {
+  const db = getDb(databaseUrl);
+  // Execute operation with timing and error handling
+}
+```
+
+### Security Implementation
+
+**SQL Injection Protection:**
+
+```typescript
+export function validateSqlQuery(sql: string): { isValid: boolean; error?: string } {
+  const dangerousPatterns = [
+    /;\s*drop\s+/i,
+    /;\s*delete\s+.*\s+where\s+1\s*=\s*1/i,
+    /;\s*truncate\s+/i,
+    // ... more patterns
+  ];
+  // Pattern-based validation for safety
+}
+
+export function isWriteOperation(sql: string): boolean {
+  const writeKeywords = ["insert", "update", "delete", "create", "drop", "alter"];
+  return writeKeywords.some((keyword) => sql.trim().toLowerCase().startsWith(keyword));
+}
+```
+
+**Access Control (`src/index.ts`):**
+
+```typescript
+const ALLOWED_USERNAMES = new Set<string>([
+  'coleam00'  // Only these GitHub usernames can execute write operations
+]);
+
+// Tool availability based on user permissions
+if (ALLOWED_USERNAMES.has(this.props.login)) {
+  // Register executeDatabase tool for privileged users
+  this.server.tool("executeDatabase", ...);
+}
+```
+
+### MCP Tools Implementation
+
+**Tool Registration System:**
+
+Tools are now organized in a modular way with centralized registration:
+
+1. **Tool Registration (`src/tools/register-tools.ts`):**
+   - Central registry that imports all tool modules
+   - Calls individual registration functions
+   - Passes server, environment, and user props to each module
+
+2. **Tool Implementation Pattern:**
+   - Each feature/domain gets its own tool file (e.g., `database-tools.ts`)
+   - Tools are exported as registration functions
+   - Registration functions receive server instance, environment, and user props
+   - Permission checking happens during registration
+
+**Example Tool Registration:**
+
+```typescript
+// src/tools/register-tools.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Props } from "../types";
+import { registerDatabaseTools } from "../../examples/database-tools";
+
+export function registerAllTools(server: McpServer, env: Env, props: Props) {
+  // Register database tools
+  registerDatabaseTools(server, env, props);
+  
+  // Future tools can be registered here
+  // registerAnalyticsTools(server, env, props);
+  // registerReportingTools(server, env, props);
+}
+```
+
+**Example Tool Module (`examples/database-tools.ts`):**
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Props } from "../types";
+
+const ALLOWED_USERNAMES = new Set<string>(['coleam00']);
+
+export function registerDatabaseTools(server: McpServer, env: Env, props: Props) {
+  // Tool 1: Available to all authenticated users
+  server.tool(
+    "listTables",
+    "Get a list of all tables in the database",
+    ListTablesSchema,
+    async () => {
+      // Implementation
+    }
+  );
+
+  // Tool 2: Available to all authenticated users
+  server.tool(
+    "queryDatabase",
+    "Execute a read-only SQL query",
+    QueryDatabaseSchema,
+    async ({ sql }) => {
+      // Implementation with validation
+    }
+  );
+
+  // Tool 3: Only for privileged users
+  if (ALLOWED_USERNAMES.has(props.login)) {
+    server.tool(
+      "executeDatabase",
+      "Execute any SQL statement (privileged)",
+      ExecuteDatabaseSchema,
+      async ({ sql }) => {
+        // Implementation
+      }
+    );
+  }
+}
+```
+
+**Available Database Tools in examples:**
+
+1. **`listTables`** - Schema discovery (all authenticated users)
+2. **`queryDatabase`** - Read-only SQL queries (all authenticated users)
+3. **`executeDatabase`** - Write operations (privileged users only)
+
+## GitHub OAuth Implementation
+
+**CRITICAL: This project implements secure GitHub OAuth 2.0 flow with signed cookie-based approval system.**
+
+### OAuth Flow Architecture
+
+**Authentication Flow (`src/github-handler.ts`):**
+
+```typescript
+// 1. Authorization Request
+app.get("/authorize", async (c) => {
+  const oauthReqInfo = await c.env.OAUTH_PROVIDER.parseAuthRequest(c.req.raw);
+
+  // Check if client already approved via signed cookie
+  if (await clientIdAlreadyApproved(c.req.raw, oauthReqInfo.clientId, c.env.COOKIE_ENCRYPTION_KEY)) {
+    return redirectToGithub(c.req.raw, oauthReqInfo, c.env, {});
+  }
+
+  // Show approval dialog
+  return renderApprovalDialog(c.req.raw, { client, server, state });
+});
+
+// 2. GitHub Callback
+app.get("/callback", async (c) => {
+  // Exchange code for access token
+  const [accessToken, errResponse] = await fetchUpstreamAuthToken({
+    client_id: c.env.GITHUB_CLIENT_ID,
+    client_secret: c.env.GITHUB_CLIENT_SECRET,
+    code: c.req.query("code"),
+    redirect_uri: new URL("/callback", c.req.url).href,
+  });
+
+  // Get GitHub user info
+  const user = await new Octokit({ auth: accessToken }).rest.users.getAuthenticated();
+
+  // Complete authorization with user props
+  return c.env.OAUTH_PROVIDER.completeAuthorization({
+    props: { accessToken, email, login, name } as Props,
+    userId: login,
+  });
+});
+```
+
+### Cookie Security System
+
+**HMAC-Signed Approval Cookies (`src/workers-oauth-utils.ts`):**
+
+```typescript
+// Generate signed cookie for client approval
+async function signData(key: CryptoKey, data: string): Promise<string> {
+  const signatureBuffer = await crypto.subtle.sign("HMAC", key, enc.encode(data));
+  return Array.from(new Uint8Array(signatureBuffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// Verify cookie integrity
+async function verifySignature(key: CryptoKey, signatureHex: string, data: string): Promise<boolean> {
+  const signatureBytes = new Uint8Array(signatureHex.match(/.{1,2}/g)!.map((byte) => parseInt(byte, 16)));
+  return await crypto.subtle.verify("HMAC", key, signatureBytes.buffer, enc.encode(data));
+}
+```
+
+### User Context & Permissions
+
+**Authenticated User Props:**
+
+```typescript
+type Props = {
+  login: string; // GitHub username
+  name: string; // Display name
+  email: string; // Email address
+  accessToken: string; // GitHub access token
+};
+
+// Available in MCP tools via this.props
+class MyMCP extends McpAgent<Env, Record<string, never>, Props> {
+  async init() {
+    // Access user context in any tool
+    const username = this.props.login;
+    const hasWriteAccess = ALLOWED_USERNAMES.has(username);
+  }
+}
+```
+
+## Monitoring & Observability
+
+**CRITICAL: This project supports optional Sentry integration for production monitoring and includes built-in console logging.**
+
+### Logging Architecture
+
+**Two Deployment Options:**
+
+1. **Standard Version (`src/index.ts`)**: Console logging only
+2. **Sentry Version (`src/index_sentry.ts`)**: Full Sentry instrumentation
+
+### Sentry Integration (Optional)
+
+**Enable Sentry Monitoring:**
+
+```typescript
+// src/index_sentry.ts - Production-ready with monitoring
+import * as Sentry from "@sentry/cloudflare";
+
+// Sentry configuration
+function getSentryConfig(env: Env) {
+  return {
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1,  // 100% trace sampling
+  };
+}
+
+// Instrument MCP tools with tracing
+private registerTool(name: string, description: string, schema: any, handler: any) {
+  this.server.tool(name, description, schema, async (args: any) => {
+    return await Sentry.startNewTrace(async () => {
+      return await Sentry.startSpan({
+        name: `mcp.tool/${name}`,
+        attributes: extractMcpParameters(args),
+      }, async (span) => {
+        // Set user context
+        Sentry.setUser({
+          username: this.props.login,
+          email: this.props.email,
+        });
+
+        try {
+          return await handler(args);
+        } catch (error) {
+          span.setStatus({ code: 2 }); // error
+          return handleError(error);  // Returns user-friendly error with event ID
+        }
+      });
+    });
+  });
+}
+```
+
+**Sentry Features Enabled:**
+
+- **Error Tracking**: Automatic exception capture with context
+- **Performance Monitoring**: Full request tracing with 100% sample rate
+- **User Context**: GitHub user information bound to events
+- **Tool Tracing**: Each MCP tool call traced with parameters
+- **Distributed Tracing**: Request flow across Cloudflare Workers
+
+### Production Logging Patterns
+
+**Console Logging (Standard):**
+
+```typescript
+// Database operations
+console.log(`Database operation completed successfully in ${duration}ms`);
+console.error(`Database operation failed after ${duration}ms:`, error);
+
+// Authentication events
+console.log(`User authenticated: ${this.props.login} (${this.props.name})`);
+
+// Tool execution
+console.log(`Tool called: ${toolName} by ${this.props.login}`);
+console.error(`Tool failed: ${toolName}`, error);
+```
+
+**Structured Error Handling:**
+
+```typescript
+// Error sanitization for security
+export function formatDatabaseError(error: unknown): string {
+  if (error instanceof Error) {
+    if (error.message.includes("password")) {
+      return "Database authentication failed. Please check credentials.";
+    }
+    if (error.message.includes("timeout")) {
+      return "Database connection timed out. Please try again.";
+    }
+    return `Database error: ${error.message}`;
+  }
+  return "Unknown database error occurred.";
+}
+```
+
+### Monitoring Configuration
+
+**Development Monitoring:**
+
+```bash
+# Enable Sentry in development
+echo 'SENTRY_DSN=https://your-dsn@sentry.io/project' >> .dev.vars
+echo 'NODE_ENV=development' >> .dev.vars
+
+# Use Sentry-enabled version
+wrangler dev --config wrangler.jsonc  # Ensure main = "src/index_sentry.ts"
+```
+
+**Production Monitoring:**
+
+```bash
+# Set production secrets
+wrangler secret put SENTRY_DSN
+wrangler secret put NODE_ENV  # Set to "production"
+
+# Deploy with monitoring
+wrangler deploy
+```
+
+## TypeScript Development Standards
+
+**CRITICAL: All MCP tools MUST follow TypeScript best practices with Zod validation and proper error handling.**
+
+### Standard Response Format
+
+**ALL tools MUST return MCP-compatible response objects:**
+
+```typescript
+import { z } from "zod";
+
+// Tool with proper TypeScript patterns
+this.server.tool(
+  "standardizedTool",
+  "Tool following standard response format",
+  {
+    name: z.string().min(1, "Name cannot be empty"),
+    options: z.object({}).optional(),
+  },
+  async ({ name, options }) => {
+    try {
+      // Input already validated by Zod schema
+      const result = await processName(name, options);
+
+      // Return standardized success response
+      return {
+        content: [
+          {
+            type: "text",
+            text: `**Success**\n\nProcessed: ${name}\n\n**Result:**\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\`\n\n**Processing time:** 0.5s`,
+          },
+        ],
+      };
+    } catch (error) {
+      // Return standardized error response
+      return {
+        content: [
+          {
+            type: "text",
+            text: `**Error**\n\nProcessing failed: ${error instanceof Error ? error.message : String(error)}`,
+            isError: true,
+          },
+        ],
+      };
+    }
+  },
+);
+```
+
+### Input Validation with Zod
+
+**ALL tool inputs MUST be validated using Zod schemas:**
+
+```typescript
+import { z } from "zod";
+
+// Define validation schemas
+const DatabaseQuerySchema = z.object({
+  sql: z
+    .string()
+    .min(1, "SQL query cannot be empty")
+    .refine((sql) => sql.trim().toLowerCase().startsWith("select"), {
+      message: "Only SELECT queries are allowed",
+    }),
+  limit: z.number().int().positive().max(1000).optional(),
+});
+
+// Use in tool definition
+this.server.tool(
+  "queryDatabase",
+  "Execute a read-only SQL query",
+  DatabaseQuerySchema, // Zod schema provides automatic validation
+  async ({ sql, limit }) => {
+    // sql and limit are already validated and properly typed
+    const results = await db.unsafe(sql);
+    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+  },
+);
+```
+
+### Error Handling Patterns
+
+**Standardized error responses:**
+
+```typescript
+// Error handling utility
+function createErrorResponse(message: string, details?: any): any {
+  return {
+    content: [{
+      type: "text",
+      text: `**Error**\n\n${message}${details ? `\n\n**Details:**\n\`\`\`json\n${JSON.stringify(details, null, 2)}\n\`\`\`` : ''}`,
+      isError: true
+    }]
+  };
+}
+
+// Permission error
+if (!ALLOWED_USERNAMES.has(this.props.login)) {
+  return createErrorResponse(
+    "Insufficient permissions for this operation",
+    { requiredRole: "privileged", userRole: "standard" }
+  );
+}
+
+// Validation error
+if (isWriteOperation(sql)) {
+  return createErrorResponse(
+    "Write operations not allowed with this tool",
+    { operation: "write", allowedOperations: ["select", "show", "describe"] }
+  );
+}
+
+// Database error
+catch (error) {
+  return createErrorResponse(
+    "Database operation failed",
+    { error: formatDatabaseError(error) }
+  );
+}
+```
+
+### Type Safety Rules
+
+**MANDATORY TypeScript patterns:**
+
+1. **Strict Types**: All parameters and return types explicitly typed
+2. **Zod Validation**: All inputs validated with Zod schemas
+3. **Error Handling**: All async operations wrapped in try/catch
+4. **User Context**: Props typed with GitHub user information
+5. **Environment**: Cloudflare Workers types generated with `wrangler types`
+
+## Code Style Preferences
+
+### TypeScript Style
+
+- Use explicit type annotations for all function parameters and return types
+- Use JSDoc comments for all exported functions and classes
+- Prefer async/await for all asynchronous operations
+- **MANDATORY**: Use Zod schemas for all input validation
+- **MANDATORY**: Use proper error handling with try/catch blocks
+- Keep functions small and focused (single responsibility principle)
+
+### File Organization
+
+- Each MCP server should be self-contained in a single TypeScript file
+- Import statements organized: Node.js built-ins, third-party packages, local imports
+- Use relative imports within the src/ directory
+- **Import Zod for validation and proper types for all modules**
+
+### Testing Conventions
+
+- Use MCP Inspector for integration testing: `npx @modelcontextprotocol/inspector@latest`
+- Test with local development server: `wrangler dev`
+- Use descriptive tool names and descriptions
+- **Test both authentication and permission scenarios**
+- **Test input validation with invalid data**
+
+## Important Notes
+
+### What NOT to do
+
+- **NEVER** commit secrets or environment variables to the repository
+- **NEVER** build complex solutions when simple ones will work
+- **NEVER** skip input validation with Zod schemas
+
+### What TO do
+
+- **ALWAYS** use TypeScript strict mode and proper typing
+- **ALWAYS** validate inputs with Zod schemas
+- **ALWAYS** follow the core principles (KISS, YAGNI, etc.)
+- **ALWAYS** use Wrangler CLI for all development and deployment
+
+## Git Workflow
+
+```bash
+# Before committing, always run:
+npm run type-check              # Ensure TypeScript compiles
+wrangler dev --dry-run          # Test deployment configuration
+
+# Commit with descriptive messages
+git add .
+git commit -m "feat: add new MCP tool for database queries"
+```
+
+## Quick Reference
+
+### Adding New MCP Tools
+
+1. **Create a new tool module** in your project (following the pattern in `examples/`):
+   ```typescript
+   // src/tools/your-feature-tools.ts
+   export function registerYourFeatureTools(server: McpServer, env: Env, props: Props) {
+     // Register your tools here
+   }
+   ```
+
+2. **Define Zod schemas** for input validation in your types file
+
+3. **Implement tool handlers** with proper error handling using the patterns from examples
+
+4. **Register your tools** in `src/tools/register-tools.ts`:
+   ```typescript
+   import { registerYourFeatureTools } from "./your-feature-tools";
+   
+   export function registerAllTools(server: McpServer, env: Env, props: Props) {
+     // Existing registrations
+     registerDatabaseTools(server, env, props);
+     
+     // Add your new registration
+     registerYourFeatureTools(server, env, props);
+   }
+   ```
+
+5. **Update documentation** if needed
diff --git a/use-cases/pydantic-ai/cursor.md b/use-cases/pydantic-ai/cursor.md
new file mode 100644
index 0000000000..1ad5dfb4b3
--- /dev/null
+++ b/use-cases/pydantic-ai/cursor.md
@@ -0,0 +1,208 @@
+# PydanticAI Context Engineering - Global Rules for AI Agent Development
+
+This file contains the global rules and principles that apply to ALL PydanticAI agent development work. These rules are specialized for building production-grade AI agents with tools, memory, and structured outputs.
+
+## 🔄 PydanticAI Core Principles
+
+**IMPORTANT: These principles apply to ALL PydanticAI agent development:**
+
+### Agent Development Workflow
+- **Always start with INITIAL.md** - Define agent requirements before generating PRPs
+- **Use the PRP pattern**: INITIAL.md → `/generate-pydantic-ai-prp INITIAL.md` → `/execute-pydantic-ai-prp PRPs/filename.md`
+- **Follow validation loops** - Each PRP must include agent testing with TestModel/FunctionModel
+- **Context is King** - Include ALL necessary PydanticAI patterns, examples, and documentation
+
+### Research Methodology for AI Agents
+- **Web search extensively** - Always research PydanticAI patterns and best practices
+- **Study official documentation** - ai.pydantic.dev is the authoritative source
+- **Pattern extraction** - Identify reusable agent architectures and tool patterns
+- **Gotcha documentation** - Document async patterns, model limits, and context management issues
+
+## 📚 Project Awareness & Context
+
+- **Use a virtual environment** to run all code and tests. If one isn't already in the codebase when needed, create it
+- **Use consistent PydanticAI naming conventions** and agent structure patterns
+- **Follow established agent directory organization** patterns (agent.py, tools.py, models.py)
+- **Leverage PydanticAI examples extensively** - Study existing patterns before creating new agents
+
+## 🧱 Agent Structure & Modularity
+
+- **Never create files longer than 500 lines** - Split into modules when approaching limit
+- **Organize agent code into clearly separated modules** grouped by responsibility:
+  - `agent.py` - Main agent definition and execution logic
+  - `tools.py` - Tool functions used by the agent
+  - `models.py` - Pydantic output models and dependency classes
+  - `dependencies.py` - Context dependencies and external service integrations
+- **Use clear, consistent imports** - Import from pydantic_ai package appropriately
+- **Use python-dotenv and load_dotenv()** for environment variables - Follow examples/main_agent_reference/settings.py pattern
+- **Never hardcode sensitive information** - Always use .env files for API keys and configuration
+
+## 🤖 PydanticAI Development Standards
+
+### Agent Creation Patterns
+- **Use model-agnostic design** - Support multiple providers (OpenAI, Anthropic, Gemini)
+- **Implement dependency injection** - Use deps_type for external services and context
+- **Define structured outputs** - Use Pydantic models for result validation
+- **Include comprehensive system prompts** - Both static and dynamic instructions
+
+### Tool Integration Standards
+- **Use @agent.tool decorator** for context-aware tools with RunContext[DepsType]
+- **Use @agent.tool_plain decorator** for simple tools without context dependencies
+- **Implement proper parameter validation** - Use Pydantic models for tool parameters
+- **Handle tool errors gracefully** - Implement retry mechanisms and error recovery
+
+### Environment Variable Configuration with python-dotenv
+```python
+# Use python-dotenv and pydantic-settings for proper configuration management
+from pydantic_settings import BaseSettings
+from pydantic import Field, ConfigDict
+from dotenv import load_dotenv
+from pydantic_ai.providers.openai import OpenAIProvider
+from pydantic_ai.models.openai import OpenAIModel
+
+class Settings(BaseSettings):
+    """Application settings with environment variable support."""
+    
+    model_config = ConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore"
+    )
+    
+    # LLM Configuration
+    llm_provider: str = Field(default="openai", description="LLM provider")
+    llm_api_key: str = Field(..., description="API key for the LLM provider")
+    llm_model: str = Field(default="gpt-4", description="Model name to use")
+    llm_base_url: str = Field(
+        default="https://api.openai.com/v1", 
+        description="Base URL for the LLM API"
+    )
+
+def load_settings() -> Settings:
+    """Load settings with proper error handling and environment loading."""
+    # Load environment variables from .env file
+    load_dotenv()
+    
+    try:
+        return Settings()
+    except Exception as e:
+        error_msg = f"Failed to load settings: {e}"
+        if "llm_api_key" in str(e).lower():
+            error_msg += "\nMake sure to set LLM_API_KEY in your .env file"
+        raise ValueError(error_msg) from e
+
+def get_llm_model():
+    """Get configured LLM model with proper environment loading."""
+    settings = load_settings()
+    provider = OpenAIProvider(
+        base_url=settings.llm_base_url, 
+        api_key=settings.llm_api_key
+    )
+    return OpenAIModel(settings.llm_model, provider=provider)
+```
+
+### Testing Standards for AI Agents
+- **Use TestModel for development** - Fast validation without API calls
+- **Use FunctionModel for custom behavior** - Control agent responses in tests
+- **Use Agent.override() for testing** - Replace models in test contexts
+- **Test both sync and async patterns** - Ensure compatibility with different execution modes
+- **Test tool validation** - Verify tool parameter schemas and error handling
+
+## ✅ Task Management for AI Development
+
+- **Break agent development into clear steps** with specific completion criteria
+- **Mark tasks complete immediately** after finishing agent implementations
+- **Update task status in real-time** as agent development progresses
+- **Test agent behavior** before marking implementation tasks complete
+
+## 📎 PydanticAI Coding Standards
+
+### Agent Architecture
+```python
+# Follow main_agent_reference patterns - no result_type unless structured output needed
+from pydantic_ai import Agent, RunContext
+from dataclasses import dataclass
+from .settings import load_settings
+
+@dataclass
+class AgentDependencies:
+    """Dependencies for agent execution"""
+    api_key: str
+    session_id: str = None
+
+# Load settings with proper dotenv handling
+settings = load_settings()
+
+# Simple agent with string output (default)
+agent = Agent(
+    get_llm_model(),  # Uses load_settings() internally
+    deps_type=AgentDependencies,
+    system_prompt="You are a helpful assistant..."
+)
+
+@agent.tool
+async def example_tool(
+    ctx: RunContext[AgentDependencies], 
+    query: str
+) -> str:
+    """Tool with proper context access"""
+    return await external_api_call(ctx.deps.api_key, query)
+```
+
+### Security Best Practices
+- **API key management** - Use python-dotenv with .env files, never commit keys to version control
+- **Environment variable loading** - Always use load_dotenv() following examples/main_agent_reference/settings.py
+- **Input validation** - Use Pydantic models for all tool parameters
+- **Rate limiting** - Implement proper request throttling for external APIs
+- **Prompt injection prevention** - Validate and sanitize user inputs
+- **Error handling** - Never expose sensitive information in error messages
+
+### Common PydanticAI Gotchas
+- **Async/sync mixing issues** - Be consistent with async/await patterns throughout
+- **Model token limits** - Different models have different context limits, plan accordingly
+- **Dependency injection complexity** - Keep dependency graphs simple and well-typed
+- **Tool error handling failures** - Always implement proper retry and fallback mechanisms
+- **Context state management** - Design stateless tools when possible for reliability
+
+## 🔍 Research Standards for AI Agents
+
+- **Use Archon MCP server** - Leverage available PydanticAI documentation via RAG
+- **Study official examples** - ai.pydantic.dev/examples has working implementations
+- **Research model capabilities** - Understand provider-specific features and limitations
+- **Document integration patterns** - Include external service integration examples
+
+## 🎯 Implementation Standards for AI Agents
+
+- **Follow the PRP workflow religiously** - Don't skip agent validation steps
+- **Always test with TestModel first** - Validate agent logic before using real models
+- **Use existing agent patterns** rather than creating from scratch
+- **Include comprehensive error handling** for tool failures and model errors
+- **Test streaming patterns** when implementing real-time agent interactions
+
+## 🚫 Anti-Patterns to Always Avoid
+
+- ❌ Don't skip agent testing - Always use TestModel/FunctionModel for validation
+- ❌ Don't hardcode model strings - Use environment-based configuration like main_agent_reference
+- ❌ Don't use result_type unless structured output is specifically needed - default to string
+- ❌ Don't ignore async patterns - PydanticAI has specific async/sync considerations
+- ❌ Don't create complex dependency graphs - Keep dependencies simple and testable
+- ❌ Don't forget tool error handling - Implement proper retry and graceful degradation
+- ❌ Don't skip input validation - Use Pydantic models for all external inputs
+
+## 🔧 Tool Usage Standards for AI Development
+
+- **Use web search extensively** for PydanticAI research and documentation
+- **Follow PydanticAI command patterns** for slash commands and agent workflows
+- **Use agent validation loops** to ensure quality at each development step
+- **Test with multiple model providers** to ensure agent compatibility
+
+## 🧪 Testing & Reliability for AI Agents
+
+- **Always create comprehensive agent tests** for tools, outputs, and error handling
+- **Test agent behavior with TestModel** before using real model providers
+- **Include edge case testing** for tool failures and model provider issues
+- **Test both structured and unstructured outputs** to ensure agent flexibility
+- **Validate dependency injection** works correctly in test environments
+
+These global rules apply specifically to PydanticAI agent development and ensure production-ready AI applications with proper error handling, testing, and security practices.
\ No newline at end of file
diff --git a/use-cases/template-generator/cursor.md b/use-cases/template-generator/cursor.md
new file mode 100644
index 0000000000..ebd5fe90a4
--- /dev/null
+++ b/use-cases/template-generator/cursor.md
@@ -0,0 +1,76 @@
+# Template Generator - Global Rules for Context Engineering
+
+This file contains the global rules and principles that apply to ALL context engineering work, regardless of what template or project you're building. These rules never change and should be followed consistently.
+
+## 🔄 Context Engineering Core Principles
+
+**IMPORTANT: These principles apply to ALL context engineering work:**
+
+### PRP Framework Workflow
+- **Always start with INITIAL.md** - Define requirements before generating PRPs
+- **Use the PRP pattern**: INITIAL.md → `/generate-template-prp INITIAL.md` → `/execute-template-prp PRPs/filename.md`
+- **Follow validation loops** - Each PRP must include executable validation steps
+- **Context is King** - Include ALL necessary documentation, examples, and patterns
+
+### Research Methodology
+- **Web search first** - Always do extensive web research before implementation
+- **Documentation deep dive** - Study official docs, best practices, and common patterns
+- **Pattern extraction** - Identify reusable patterns and architectural conventions
+- **Gotcha documentation** - Document common pitfalls and edge cases
+
+## 📚 Project Awareness & Context
+
+- **Use consistent naming conventions** and file structure patterns
+- **Follow established directory organization** patterns
+- **Leverage examples extensively** - Study existing patterns before creating new ones
+
+## 🧱 Code Structure & Modularity
+
+- **Never create files longer than 500 lines** - Split into modules when approaching limit
+- **Organize code into clearly separated modules** grouped by feature or responsibility
+- **Use clear, consistent imports** (prefer relative imports within packages)
+- **Follow established coding standards** and conventions
+
+## ✅ Task Management
+
+- **Break complex tasks into smaller steps** with clear completion criteria
+- **Mark tasks complete immediately** after finishing them
+- **Update task status in real-time** as work progresses
+
+## 📎 Documentation Standards
+
+- **Write comprehensive documentation** for every component
+- **Include clear usage examples** with working code
+- **Document all gotchas and edge cases** to prevent common errors
+- **Maintain up-to-date references** to external documentation
+
+## 🔍 Research Standards
+
+- **Web search is your best friend** - Use it extensively for technology research
+- **Study official documentation thoroughly** before implementation
+- **Research established patterns** and best practices for the technology
+- **Document all findings comprehensively** in PRPs and implementation guides
+
+## 🎯 Implementation Standards
+
+- **Follow the PRP workflow religiously** - Don't skip steps
+- **Always validate before proceeding** to the next step
+- **Use existing patterns as templates** rather than creating from scratch
+- **Include comprehensive error handling** in all implementations
+
+## 🚫 Anti-Patterns to Always Avoid
+
+- ❌ Don't skip research - Always understand the technology deeply first
+- ❌ Don't create generic solutions - Always specialize for the specific use case
+- ❌ Don't ignore validation - Every step must include verification
+- ❌ Don't assume knowledge - Document everything explicitly
+- ❌ Don't skip examples - Always include working code examples
+- ❌ Don't forget edge cases - Include error handling and gotchas
+
+## 🔧 Tool Usage Standards
+
+- **Use web search extensively** for research and documentation
+- **Follow established command patterns** for slash commands
+- **Use validation loops** to ensure quality at each step
+
+These global rules apply regardless of whether you're generating templates, implementing features, or doing research. They form the foundation of effective context engineering work.
\ No newline at end of file