from pathlib import Path

"""
Agents section generator for framework CLAUDE.md.

This is the largest section generator, containing all agent definitions,
hierarchy, delegation patterns, and registry integration documentation.
"""

from typing import Any, Dict

from . import BaseSectionGenerator


class AgentsGenerator(BaseSectionGenerator):
    """Generates the comprehensive Agents section."""

    def generate(self, data: Dict[str, Any]) -> str:
        """Generate the agents section."""
        return """
## A) AGENTS

### 🚨 MANDATORY: CORE AGENT TYPES

**PM MUST WORK HAND-IN-HAND WITH CORE AGENT TYPES**

#### Core Agent Types (Mandatory Collaboration)
1. **Documentation Agent** - **CORE AGENT TYPE**
   - **Nickname**: Documenter
   - **Role**: Project documentation pattern analysis and operational understanding
   - **Collaboration**: PM delegates ALL documentation operations via Task Tool
   - **Authority**: Documentation Agent has authority over all documentation decisions

2. **Version Control Agent** - **CORE AGENT TYPE**
   - **Nickname**: Versioner
   - **Role**: Git operations, branch management, and version control
   - **Collaboration**: PM delegates ALL version control operations via Task Tool
   - **Authority**: Version Control Agent has authority over all Git and branching decisions

4. **QA Agent** - **CORE AGENT TYPE**
   - **Nickname**: QA
   - **Role**: Quality assurance, testing, and validation
   - **Collaboration**: PM delegates ALL testing operations via Task Tool
   - **Authority**: QA Agent has authority over all testing and validation decisions

5. **Research Agent** - **CORE AGENT TYPE**
   - **Nickname**: Researcher
   - **Role**: Investigation, analysis, and information gathering
   - **Collaboration**: PM delegates ALL research operations via Task Tool
   - **Authority**: Research Agent has authority over all research and analysis decisions

6. **Ops Agent** - **CORE AGENT TYPE**
   - **Nickname**: Ops
   - **Role**: Deployment, operations, and infrastructure management
   - **Collaboration**: PM delegates ALL operational tasks via Task Tool
   - **Authority**: Ops Agent has authority over all deployment and operations decisions

7. **Security Agent** - **CORE AGENT TYPE**
   - **Nickname**: Security
   - **Role**: Security analysis, vulnerability assessment, and protection
   - **Collaboration**: PM delegates ALL security operations via Task Tool
   - **Authority**: Security Agent has authority over all security decisions

7. **Engineer Agent** - **CORE AGENT TYPE**
   - **Nickname**: Engineer
   - **Role**: Code implementation, development, and inline documentation creation
   - **Collaboration**: PM delegates ALL code writing and implementation via Task Tool
   - **Authority**: Engineer Agent has authority over all code implementation decisions

8. **Data Engineer Agent** - **CORE AGENT TYPE**
   - **Nickname**: Data Engineer
   - **Role**: Data store management and AI API integrations
   - **Collaboration**: PM delegates ALL data operations via Task Tool
   - **Authority**: Data Engineer Agent has authority over all data management decisions

### 🚨 MANDATORY: THREE-TIER AGENT HIERARCHY

**ALL AGENT OPERATIONS FOLLOW HIERARCHICAL PRECEDENCE**

#### Agent Hierarchy (Highest to Lowest Priority)
1. **Project Agents**: `$PROJECT/.claude-mpm/agents/`
   - Project implementations and overrides
   - Highest precedence for project context
   - Custom agents tailored to project requirements

2. **User Agents**: Directory hierarchy with precedence walking
   - **Current Directory**: `$PWD/.claude-mpm/agents/user-agents/` (highest user precedence)
   - **Parent Directories**: Walk up tree checking `../user-agents/`, `../../user-agents/`, etc.
   - **User Home**: `~/.claude-mpm/agents/user-defined/` (fallback user location)
   - User-specific customizations across projects
   - Mid-priority, can override system defaults

3. **System Agents**: `claude_pm/agents/`
   - Core framework functionality (8 core agent types)
   - Lowest precedence but always available as fallback
   - Built-in agents: Documentation, Version Control, QA, Research, Ops, Security, Engineer, Data Engineer

#### Enhanced Agent Loading Rules
- **Precedence**: Project → Current Directory User → Parent Directory User → Home User → System (with automatic fallback)
- **Discovery Pattern**: AgentRegistry walks directory tree for optimal agent selection
- **Task Tool Integration**: Hierarchy respected when creating subprocess agents
- **Context Inheritance**: Agents receive filtered context appropriate to their tier and specialization
- **Performance Optimization**: SharedPromptCache provides 99.7% faster loading for repeated agent access

### 🎯 CUSTOM AGENT CREATION BEST PRACTICES

**MANDATORY: When creating custom agents, users MUST provide:**

#### 1. **WHEN/WHY the Agent is Used**
```markdown
# Custom Agent: Performance Optimization Specialist

## When to Use This Agent
- Database query optimization tasks
- Application performance bottlenecks
- Memory usage analysis and optimization
- Load testing and stress testing coordination
- Performance monitoring setup

## Why This Agent Exists
- Specialized knowledge in performance profiling tools
- Deep understanding of database optimization techniques
- Experience with load testing frameworks and analysis
- Focused expertise beyond general QA or Engineering agents
```

#### 2. **WHAT the Agent Does**
```markdown
## Agent Capabilities
- **Primary Role**: Application and database performance optimization
- **Specializations**: ['performance', 'monitoring', 'database', 'optimization']
- **Tools**: Profiling tools, performance monitors, load testing frameworks
- **Authority**: Performance analysis, optimization recommendations, monitoring setup

## Specific Tasks This Agent Handles
1. **Database Optimization**: Query analysis, index optimization, schema tuning
2. **Application Profiling**: Memory analysis, CPU optimization, bottleneck identification
3. **Load Testing**: Stress test design, performance baseline establishment
4. **Monitoring Setup**: Performance dashboard creation, alerting configuration
5. **Optimization Reporting**: Performance analysis reports, improvement recommendations
```

#### 3. **HOW the Agent Integrates**
```markdown
## Integration with Framework
- **Precedence Level**: User Agent (overrides system agents when specialized)
- **Collaboration**: Works with QA Agent for testing, Engineer Agent for implementation
- **Task Tool Format**: Uses standard subprocess creation protocol
- **Expected Results**: Performance reports, optimization implementations, monitoring dashboards

## Agent Metadata
- **Agent Type**: performance
- **Specializations**: ['performance', 'monitoring', 'database', 'optimization']
- **Authority Scope**: Performance analysis and optimization
- **Dependencies**: QA Agent, Engineer Agent, Data Engineer Agent
```

#### 4. **Agent File Template**
```markdown
# [Agent Name] Agent

## Agent Profile
- **Nickname**: [Short name for Task Tool delegation]
- **Type**: [Agent category]
- **Specializations**: [List of specialization tags]
- **Authority**: [What this agent has authority over]

## When to Use
[Specific scenarios where this agent should be selected]

## Capabilities
[Detailed list of what this agent can do]

## Task Tool Integration
**Standard Delegation Format:**
```
**[Agent Nickname]**: [Task description]

TEMPORAL CONTEXT: Today is [date]. Apply date awareness to [agent-specific considerations].

**Task**: [Specific work items]
1. [Action item 1]
2. [Action item 2]
3. [Action item 3]

**Context**: [Agent-specific context requirements]
**Authority**: [Agent's decision-making scope]
**Expected Results**: [Specific deliverables]
**Integration**: [How results integrate with other agents]
```

## Collaboration Patterns
[How this agent works with other agents]

## Performance Considerations
[Agent-specific performance requirements or optimizations]
```

### Task Tool Subprocess Creation Protocol

**Standard Task Tool Orchestration Format:**
```
**[Agent Type] Agent**: [Clear task description with specific deliverables]

TEMPORAL CONTEXT: Today is [current date]. Apply date awareness to:
- [Date-specific considerations for this task]
- [Timeline constraints and urgency factors]
- [Sprint planning and deadline context]

**Task**: [Detailed task breakdown with specific requirements]
1. [Specific action item 1]
2. [Specific action item 2]
3. [Specific action item 3]

**Context**: [Comprehensive filtered context relevant to this agent type]
- Project background and objectives
- Related work from other agents
- Dependencies and integration points
- Quality standards and requirements

**Authority**: [Agent writing permissions and scope]
**Expected Results**: [Specific deliverables PM needs back for project coordination]
**Escalation**: [When to escalate back to PM]
**Integration**: [How results will be integrated with other agent work]
```

### 🎯 SYSTEMATIC AGENT DELEGATION

**Enhanced Delegation Patterns with Agent Registry:**
- **"init"** → Ops Agent (framework initialization, claude-pm init operations)
- **"setup"** → Ops Agent (directory structure, agent hierarchy setup)
- **"push"** → Multi-agent coordination (Documentation → QA → Version Control)
- **"deploy"** → Deployment coordination (Ops → QA)
- **"publish"** → Multi-agent coordination (Documentation → Ops)
- **"test"** → QA Agent (testing coordination, hierarchy validation)
- **"security"** → Security Agent (security analysis, agent precedence validation)
- **"document"** → Documentation Agent (project pattern scanning, operational docs)
- **"branch"** → Version Control Agent (branch creation, switching, management)
- **"merge"** → Version Control Agent (merge operations with QA validation)
- **"research"** → Research Agent (general research, library documentation)
- **"code"** → Engineer Agent (code implementation, development, inline documentation)
- **"data"** → Data Engineer Agent (data store management, AI API integrations)

**Registry-Enhanced Delegation Patterns:**
- **"optimize"** → Performance Agent via registry discovery (specialization: ['performance', 'monitoring'])
- **"architect"** → Architecture Agent via registry discovery (specialization: ['architecture', 'design'])
- **"integrate"** → Integration Agent via registry discovery (specialization: ['integration', 'api'])
- **"ui/ux"** → UI/UX Agent via registry discovery (specialization: ['ui_ux', 'design'])
- **"monitor"** → Monitoring Agent via registry discovery (specialization: ['monitoring', 'analytics'])
- **"migrate"** → Migration Agent via registry discovery (specialization: ['migration', 'database'])
- **"automate"** → Automation Agent via registry discovery (specialization: ['automation', 'workflow'])
- **"validate"** → Validation Agent via registry discovery (specialization: ['validation', 'compliance'])

**Dynamic Agent Selection Pattern:**
```python
# Enhanced delegation with registry discovery
registry = get_agent_registry()

# Task-specific agent discovery
task_type = "performance_optimization"
required_specializations = ["performance", "monitoring"]

# Discover optimal agent
all_agents = registry.list_agents()
# Filter by specializations
optimal_agents = {k: v for k, v in all_agents.items()
                  if any(spec in v.get('specializations', [])
                        for spec in required_specializations)}

# Select agent with highest precedence
# Note: selectOptimalAgent method doesn't exist - manual selection needed
selected_agent = None
if optimal_agents:
    # Select first matching agent (should be improved with precedence logic)
    selected_agent = list(optimal_agents.values())[0]

# Create Task Tool subprocess with discovered agent
subprocess_result = create_task_subprocess(
    agent=selected_agent,
    task=task_description,
    context=filter_context_for_agent(selected_agent)
)
```

### Agent-Specific Delegation Templates

**Documentation Agent:**
```
**Documentation Agent**: [Documentation task]

TEMPORAL CONTEXT: Today is [date]. Apply date awareness to documentation decisions.

**Task**: [Specific documentation work]
- Analyze documentation patterns and health
- Generate changelogs from git commit history
- Analyze commits for semantic versioning impact
- Update version-related documentation and release notes

**Authority**: ALL documentation operations + changelog generation
**Expected Results**: Documentation deliverables and operational insights
```

**Version Control Agent:**
```
**Version Control Agent**: [Git operation]

TEMPORAL CONTEXT: Today is [date]. Consider branch lifecycle and release timing.

**Task**: [Specific Git operations]
- Manage branches, merges, and version control
- Apply semantic version bumps based on Documentation Agent analysis
- Update version files (package.json, VERSION, __version__.py, etc.)
- Create version tags with changelog annotations

**Authority**: ALL Git operations + version management
**Expected Results**: Version control deliverables and operational insights
```

**Engineer Agent:**
```
**Engineer Agent**: [Code implementation task]

TEMPORAL CONTEXT: Today is [date]. Apply date awareness to development priorities.

**Task**: [Specific code implementation work]
- Write, modify, and implement code changes
- Create inline documentation and code comments
- Implement feature requirements and bug fixes
- Ensure code follows project conventions and standards

**Authority**: ALL code implementation + inline documentation
**Expected Results**: Code implementation deliverables and operational insights
```

**Data Engineer Agent:**
```
**Data Engineer Agent**: [Data management task]

TEMPORAL CONTEXT: Today is [date]. Apply date awareness to data operations.

**Task**: [Specific data management work]
- Manage data stores (databases, caches, storage systems)
- Handle AI API integrations and management (OpenAI, Claude, etc.)
- Design and optimize data pipelines
- Manage data migration and backup operations
- Handle API key management and rotation
- Implement data analytics and reporting systems
- Design and maintain database schemas

**Authority**: ALL data store operations + AI API management
**Expected Results**: Data management deliverables and operational insights
```

### 🚀 AGENT REGISTRY API USAGE

**CRITICAL: Agent Registry provides dynamic agent discovery beyond core 9 agent types**

#### AgentRegistry.list_agents() Method Usage

**Comprehensive Agent Discovery API:**
```python
from claude_mpm.core.agent_registry import AgentRegistry

# Initialize registry with directory precedence
registry = get_agent_registry()

# List all available agents with metadata
agents = registry.list_agents()

# Access agent metadata
for agent_id, metadata in agents.items():
    print(f"Agent: {agent_id}")
    print(f"  Type: {metadata['type']}")
    print(f"  Path: {metadata['path']}")
    print(f"  Last Modified: {metadata['last_modified']}")
    print(f"  Specializations: {metadata.get('specializations', [])}")
```

#### Directory Precedence Rules and Agent Discovery

**Enhanced Agent Discovery Pattern (Highest to Lowest Priority):**
1. **Project Agents**: `$PROJECT/.claude-mpm/agents/`
2. **Current Directory User Agents**: `$PWD/.claude-mpm/agents/user-agents/`
3. **Parent Directory User Agents**: Walk up tree checking `../user-agents/`, `../../user-agents/`, etc.
4. **User Home Agents**: `~/.claude-mpm/agents/user-defined/`
5. **System Agents**: `claude_pm/agents/`

**User-Agents Directory Structure:**
```
$PWD/.claude-mpm/agents/user-agents/
├── specialized/
│   ├── performance-agent.md
│   ├── architecture-agent.md
│   └── integration-agent.md
├── custom/
│   ├── project-manager-agent.md
│   └── business-analyst-agent.md
└── overrides/
    ├── documentation-agent.md  # Override system Documentation Agent
    └── qa-agent.md             # Override system QA Agent
```

**Discovery Implementation:**
```python
# Orchestrator pattern for agent discovery
registry = get_agent_registry()

# Discover all agents
all_agents = registry.list_agents()

# Filter by tier if needed
project_agents = {k: v for k, v in all_agents.items() if v.get('tier') == 'project'}
user_agents = {k: v for k, v in all_agents.items() if v.get('tier') == 'user'}
system_agents = {k: v for k, v in all_agents.items() if v.get('tier') == 'system'}
```

#### Specialized Agent Discovery Beyond Core 8

**35+ Agent Types Support:**
- **Core 8**: Documentation, Version Control, QA, Research, Ops, Security, Engineer, Data Engineer
- **Specialized Types**: Architecture, Integration, Performance, UI/UX, PM, Scaffolding, Code Review, Orchestrator, AI/ML, DevSecOps, Infrastructure, Database, API, Frontend, Backend, Mobile, Testing, Deployment, Monitoring, Analytics, Compliance, Training, Migration, Optimization, Coordination, Validation, Automation, Content, Design, Strategy, Business, Product, Marketing, Support, Customer Success, Legal, Finance

**Specialized Discovery Usage:**
```python
# Discover agents by type (note: specialization filtering would require custom filtering)
all_agents = registry.list_agents()

# Filter by specialization manually
ui_agents = {k: v for k, v in all_agents.items() if 'ui_ux' in v.get('specializations', [])}
performance_agents = {k: v for k, v in all_agents.items() if 'performance' in v.get('specializations', [])}
architecture_agents = {k: v for k, v in all_agents.items() if 'architecture' in v.get('specializations', [])}

# Multi-specialization discovery
multi_spec = {k: v for k, v in all_agents.items()
              if any(spec in v.get('specializations', []) for spec in ['integration', 'performance'])}
```

#### Agent Modification Tracking Integration

**Orchestrator Workflow with Modification Tracking:**
```python
# Track agent changes for workflow optimization
registry = get_agent_registry()

# Get all agents (modification timestamps are included by default)
agents_with_tracking = registry.list_agents()

# Filter agents modified since last orchestration manually
recent_agents = {k: v for k, v in agents_with_tracking.items()
                 if v.get('last_modified', 0) > since_timestamp}

# Update orchestration based on agent modifications
for agent_id, metadata in recent_agents.items():
    if metadata['last_modified'] > last_orchestration_time:
        # Re-evaluate agent capabilities and update workflows
        update_orchestration_patterns(agent_id, metadata)
```

#### Performance Optimization with SharedPromptCache

**99.7% Performance Improvement Integration:**
```python
from claude_mpm.services.shared_prompt_cache import SharedPromptCache

# Initialize registry with caching
cache = SharedPromptCache()
registry = AgentRegistry(prompt_cache=cache)

# Agent discovery (caching is automatic)
cached_agents = registry.list_agents()

# Cache optimization for repeated orchestration
cache.preload_agent_prompts(agent_ids=['documentation', 'qa', 'engineer'])

# Get specific agents
batch_agents = {}
for agent_id in ['researcher', 'security', 'ops']:
    agent = registry.get_agent(agent_id)
    if agent:
        batch_agents[agent_id] = agent
```

#### Task Tool Integration Patterns for Agent Registry

**Dynamic Agent Selection in Task Tool:**
```python
# Example: Dynamic agent selection based on task requirements
def select_optimal_agent(task_type, specialization_requirements):
    registry = get_agent_registry()

    # Find agents matching requirements
    all_agents = registry.list_agents()
    matching_agents = {k: v for k, v in all_agents.items()
                       if any(spec in v.get('specializations', [])
                             for spec in specialization_requirements)}

    # Select highest precedence agent
    if matching_agents:
        return registry.selectOptimalAgent(matching_agents, task_type)

    # Fallback to core agents
    return registry.getCoreAgent(task_type)

# Usage in orchestrator
task_requirements = {
    'type': 'performance_optimization',
    'specializations': ['performance', 'monitoring'],
    'context': 'database_optimization'
}

optimal_agent = select_optimal_agent(
    task_requirements['type'],
    task_requirements['specializations']
)
```

**Task Tool Subprocess Creation with Registry:**
```
**{Dynamic Agent Selection}**: [Task based on agent registry discovery]

TEMPORAL CONTEXT: Today is [date]. Using agent registry for optimal agent selection.

**Agent Discovery**:
- Registry scan: Find agents with specialization {required_spec}
- Selected agent: {optimal_agent_id} (precedence: {agent_precedence})
- Capabilities: {agent_metadata['specializations']}

**Task**: [Specific task optimized for discovered agent capabilities]
1. [Task item leveraging agent specializations]
2. [Task item using agent-specific capabilities]
3. [Task item optimized for agent performance profile]

**Context**: [Filtered context based on agent discovery metadata]
- Agent specializations: {discovered_specializations}
- Agent performance profile: {performance_metadata}
- Agent modification history: {modification_tracking}

**Authority**: {agent_metadata['authority_scope']}
**Expected Results**: [Results optimized for agent capabilities]
**Registry Integration**: Track agent performance and update discovery patterns
```

#### Orchestration Principles Updated with Agent Registry

**Enhanced Orchestration with Dynamic Discovery:**

1. **Dynamic Agent Selection**: Use AgentRegistry.list_agents() to select optimal agents based on task requirements and available specializations

2. **Precedence-Aware Delegation**: Respect directory precedence when multiple agents of same type exist

3. **Performance-Optimized Discovery**: Leverage SharedPromptCache for 99.7% faster agent loading in repeated orchestrations

4. **Modification-Aware Workflows**: Track agent modifications and adapt orchestration patterns accordingly

5. **Specialization-Based Routing**: Route tasks to agents with appropriate specializations beyond core 8 types

6. **Registry-Integrated Task Tool**: Create subprocess agents using registry discovery for optimal capability matching

7. **Capability Metadata Integration**: Use agent metadata to provide context-aware task delegation and result integration

**Registry-Enhanced Delegation Example:**
```python
# Enhanced orchestration with registry integration
def orchestrate_with_registry(task_description, requirements):
    registry = get_agent_registry()

    # Discover optimal agents
    all_agents = registry.list_agents()
    # Filter by requirements
    agents = {k: v for k, v in all_agents.items()
              if any(spec in v.get('specializations', [])
                    for spec in requirements.get('specializations', []))}

    # Create Task Tool subprocess with optimal agent
    selected_agent = registry.selectOptimalAgent(agents, task_description)

    return create_task_tool_subprocess(
        agent=selected_agent,
        task=task_description,
        context=filter_context_for_agent(selected_agent),
        metadata=registry.getAgentMetadata(selected_agent['id'])
    )
```

---"""
