claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/services/framework_claude_md_generator/section_generators/agents.py

@@ -0,0 +1,582 @@
+"""
+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 Dict, Any
+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-pm/agents/project-specific/`
+   - Project-specific 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-pm/agents/user-agents/` (highest user precedence)
+   - **Parent Directories**: Walk up tree checking `../user-agents/`, `../../user-agents/`, etc.
+   - **User Home**: `~/.claude-pm/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 = AgentRegistry()
+
+# Task-specific agent discovery
+task_type = "performance_optimization"
+required_specializations = ["performance", "monitoring"]
+
+# Discover optimal agent
+all_agents = registry.listAgents()
+# 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.listAgents() Method Usage
+
+**Comprehensive Agent Discovery API:**
+```python
+from claude_pm.core.agent_registry import AgentRegistry
+
+# Initialize registry with directory precedence
+registry = AgentRegistry()
+
+# List all available agents with metadata
+agents = registry.listAgents()
+
+# 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-pm/agents/project-specific/`
+2. **Current Directory User Agents**: `$PWD/.claude-pm/agents/user-agents/`
+3. **Parent Directory User Agents**: Walk up tree checking `../user-agents/`, `../../user-agents/`, etc.
+4. **User Home Agents**: `~/.claude-pm/agents/user-defined/`
+5. **System Agents**: `claude_pm/agents/`
+
+**User-Agents Directory Structure:**
+```
+$PWD/.claude-pm/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 = AgentRegistry()
+
+# Discover all agents
+all_agents = registry.listAgents()
+
+# 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.listAgents()
+
+# 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 = AgentRegistry()
+
+# Get all agents (modification timestamps are included by default)
+agents_with_tracking = registry.listAgents()
+
+# 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_pm.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.listAgents()
+
+# 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 = AgentRegistry()
+    
+    # Find agents matching requirements
+    all_agents = registry.listAgents()
+    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.listAgents() 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 = AgentRegistry()
+    
+    # Discover optimal agents
+    all_agents = registry.listAgents()
+    # 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'])
+    )
+```
+
+---"""

claude_mpm/services/framework_claude_md_generator/section_generators/claude_pm_init.py

@@ -0,0 +1,97 @@
+"""
+Claude-PM Init section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class ClaudePmInitGenerator(BaseSectionGenerator):
+    """Generates the Claude-PM Init section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the claude-pm init section."""
+        return """
+## C) CLAUDE-PM INIT
+
+### Core Initialization Commands
+
+```bash
+# Basic initialization check
+claude-pm init
+
+# Complete setup with directory creation
+claude-pm init --setup
+
+# Comprehensive verification of agent hierarchy
+claude-pm init --verify
+```
+
+### 🚨 STARTUP PROTOCOL
+
+**MANDATORY startup sequence for every PM session:**
+
+1. **MANDATORY: Acknowledge Current Date**:
+   ```
+   "Today is [current date]. Setting temporal context for project planning and prioritization."
+   ```
+
+2. **MANDATORY: Verify claude-pm init status**:
+   ```bash
+   claude-pm init --verify
+   ```
+
+3. **MANDATORY: Core System Health Check**:
+   ```bash
+   python -c "from claude_pm.core import validate_core_system; validate_core_system()"
+   ```
+
+4. **MANDATORY: Agent Registry Health Check**:
+   ```bash
+   python -c "from claude_pm.core.agent_registry import AgentRegistry; registry = AgentRegistry(); print(f'Registry health: {registry.health_check()}')"
+   ```
+
+5. **MANDATORY: Initialize Core Agents with Registry Discovery**:
+   ```
+   Agent Registry: Discover available agents and build capability mapping across all directories
+   
+   Documentation Agent: Scan project documentation patterns and build operational understanding.
+   
+   Version Control Agent: Confirm availability and provide Git status summary.
+   
+   Data Engineer Agent: Verify data store connectivity and AI API availability.
+   ```
+
+6. **Review active tickets** using PM's direct ai-trackdown interface with date context
+7. **Provide status summary** of current tasks, framework health, agent registry status, and core system status
+8. **Ask** what specific tasks or framework operations to perform
+
+### Directory Structure and Agent Hierarchy Setup
+
+**Multi-Project Orchestrator Pattern:**
+
+1. **Framework Directory** (`/Users/masa/Projects/claude-multiagent-pm/.claude-pm/`)
+   - Global user agents (shared across all projects)
+   - Framework-level configuration
+
+2. **Working Directory** (`$PWD/.claude-pm/`)
+   - Current session configuration
+   - Working directory context
+
+3. **Project Directory** (`$PROJECT_ROOT/.claude-pm/`)
+   - Project-specific agents in `agents/project-specific/`
+   - User agents in `agents/user-agents/` with directory precedence
+   - Project-specific configuration
+
+### Health Validation and Deployment Procedures
+
+**Framework Health Monitoring:**
+```bash
+# Check framework protection status
+python -c "from claude_pm.services.health_monitor import HealthMonitor; HealthMonitor().check_framework_health()"
+
+# Validate agent hierarchy
+claude-pm init --verify
+
+
+---"""