claude-mpm 4.1.0__py3-none-any.whl → 4.1.2__py3-none-any.whl

claude_mpm/agents/WORKFLOW.md

@@ -21,267 +21,34 @@
 
 ### Phase 3: Quality Assurance (AFTER Implementation)
 
-**Intelligent QA Agent Selection**:
-
-The PM must analyze the implementation context to route to the appropriate QA agent based on a comprehensive decision tree. This ensures that each QA type focuses on their area of expertise while maintaining comprehensive coverage.
-
-#### QA Agent Types and Capabilities
-
-1. **API QA Agent** - Specialized for server-side and backend testing:
-   - **Primary Focus**: REST APIs, GraphQL, server routes, authentication systems
-   - **Triggered by keywords**: API, endpoint, route, REST, GraphQL, server, backend, authentication, authorization, database, microservice, webhook
-   - **File indicators**: 
-     - Directories: `/api`, `/routes`, `/controllers`, `/services`, `/models`, `/middleware`
-     - Files: `.py` (FastAPI/Flask/Django), `.js/.ts` (Express/NestJS), `.go`, `.java`, `.php`, `.rb`
-   - **Testing capabilities**:
-     - REST endpoint validation (CRUD operations, status codes, headers)
-     - GraphQL query and mutation testing
-     - Authentication and authorization flows (JWT, OAuth2, API keys)
-     - Database operation validation and data integrity
-     - Request/response schema validation (OpenAPI/Swagger)
-     - API performance and load testing
-     - Contract testing between services
-     - Security testing (OWASP API Security Top 10)
-   - **Tools and frameworks**: Postman/Newman, curl, HTTPie, Jest/Mocha for API tests
-   - **Required Output**: "API QA Complete: [Pass/Fail] - [Endpoints tested: X, Avg response time: Xms, Auth flows: X, Security checks: X, Issues: X]"
-
-2. **Web QA Agent** - Specialized for browser-based and frontend testing:
-   - **Primary Focus**: Web pages, UI components, browser testing, user experience
-   - **Triggered by keywords**: web, UI, page, frontend, browser, component, responsive, accessibility, user interface, client-side, SPA
-   - **File indicators**:
-     - Directories: `/components`, `/pages`, `/views`, `/public`, `/assets`, `/styles`
-     - Files: `.jsx/.tsx` (React), `.vue` (Vue.js), `.svelte`, `.html`, `.css/.scss`, `.js` (client-side)
-   - **Testing capabilities**:
-     - UI component functionality and rendering
-     - User flow validation (registration, login, checkout, etc.)
-     - Responsive design testing across devices and screen sizes
-     - Cross-browser compatibility (Chrome, Firefox, Safari, Edge)
-     - Accessibility compliance (WCAG 2.1 AA standards)
-     - Client-side performance (Core Web Vitals, load times)
-     - Interactive element testing (forms, buttons, navigation)
-     - Visual regression testing
-   - **Tools and frameworks**: Selenium, Playwright, Cypress, browser dev tools
-   - **Required Output**: "Web QA Complete: [Pass/Fail] - [Browsers tested: X, Pages validated: X, Accessibility score: X%, Performance score: X%, Issues: X]"
-
-3. **General QA Agent** - Default for comprehensive testing needs:
-   - **Primary Focus**: Libraries, CLI tools, utilities, integration testing
-   - **Default selection**: When neither API nor Web indicators are present
-   - **File indicators**: CLI tools, libraries, utilities, scripts, configuration files, test files
-   - **Testing capabilities**:
-     - Unit test execution and coverage analysis
-     - Integration testing between components
-     - CLI functionality and command validation
-     - Library method and function testing
-     - Configuration file validation
-     - Build and deployment process testing
-     - Cross-platform compatibility
-   - **Tools and frameworks**: pytest, Jest, JUnit, Mocha, CLI testing frameworks
-   - **Required Output**: "QA Complete: [Pass/Fail] - [Tests run: X, Coverage: X%, CLI commands: X, Issues: X]"
-
-4. **Full-Stack Testing** - Coordinated testing for complete features:
-   - **Triggered when**: Both backend AND frontend changes detected in implementation
-   - **Sequential execution order**:
-     a. **First: API QA** validates backend functionality and data flows
-     b. **Then: Web QA** validates frontend integration and user experience
-     c. **Finally: Integration validation** between all layers
-   - **Coordination requirements**:
-     - API QA must complete successfully before Web QA begins
-     - Both agents receive original user requirements
-     - Integration testing covers end-to-end user workflows
-     - Data consistency validation across frontend and backend
-   - **Required Output**: "Full-Stack QA Complete: [Pass/Fail] - API: [API results], Web: [Web results], Integration: [End-to-end results]"
-
-#### QA Selection Decision Tree
-
-The PM follows this decision logic to route QA testing appropriately:
-
-```
-📊 QA ROUTING DECISION TREE
-│
-├─ 🔍 ANALYZE IMPLEMENTATION CONTEXT
-│   ├─ Keywords Analysis
-│   ├─ File Path Analysis  
-│   ├─ Technology Stack Detection
-│   └─ Feature Scope Assessment
-│
-├─ 🌐 BACKEND INDICATORS → API QA Agent
-│   ├─ Keywords: api, endpoint, route, rest, graphql, server, backend, auth, database, microservice
-│   ├─ File Paths: /api/, /routes/, /controllers/, /services/, /models/, /middleware/
-│   ├─ Extensions: .py, .js/.ts (server), .go, .java, .php, .rb
-│   ├─ Content: @app.route, router.get, API decorators, database schemas
-│   └─ Output: "API QA Complete: [detailed API testing results]"
-│
-├─ 💻 FRONTEND INDICATORS → Web QA Agent  
-│   ├─ Keywords: web, ui, page, frontend, browser, component, responsive, accessibility, spa
-│   ├─ File Paths: /components/, /pages/, /views/, /public/, /assets/, /styles/
-│   ├─ Extensions: .jsx/.tsx, .vue, .svelte, .html, .css/.scss, .js (client)
-│   ├─ Content: React components, Vue templates, CSS frameworks, client-side logic
-│   └─ Output: "Web QA Complete: [detailed UI/UX testing results]"
-│
-├─ 🔄 FULL-STACK INDICATORS → Sequential QA (API → Web)
-│   ├─ Mixed Context: Both backend AND frontend changes
-│   ├─ User Stories: End-to-end feature requirements
-│   ├─ Integration: Frontend consumes backend APIs
-│   ├─ Execution: API QA first, then Web QA, then integration validation
-│   └─ Output: "Full-Stack QA Complete: [combined testing results]"
-│
-└─ ⚙️  DEFAULT → General QA Agent
-    ├─ No specific indicators detected
-    ├─ CLI tools, libraries, utilities
-    ├─ Configuration files, scripts
-    ├─ Pure logic/algorithm implementations
-    └─ Output: "QA Complete: [general testing results]"
-```
-
-**Detailed Detection Logic**:
-
-```
-Backend Indicators → Route to API QA:
-- API route definitions (e.g., @app.route, router.get, @api.route)
-- Database models, migrations, or ORM configurations
-- Authentication/authorization middleware and logic
-- GraphQL schemas, resolvers, or mutations
-- Server configuration files (server.js, app.py, main.go)
-- Backend service implementations and business logic
-- Microservice definitions and inter-service communication
-- API documentation or OpenAPI specifications
-
-Frontend Indicators → Route to Web QA:
-- React/Vue/Angular/Svelte components and pages
-- HTML templates, views, or page definitions
-- CSS/SCSS/Tailwind style files and responsive design
-- Client-side JavaScript for user interactions
-- Static assets (images, fonts, icons) and asset optimization
-- Frontend build configurations (webpack, vite, rollup)
-- Progressive Web App (PWA) configurations
-- Client-side routing and navigation logic
-
-Mixed Indicators → Sequential QA (API QA → Web QA → Integration):
-- Both backend and frontend files modified in implementation
-- Full-stack feature implementation (e.g., auth system, e-commerce)
-- End-to-end user stories spanning multiple layers
-- Features requiring backend API and frontend UI coordination
-- Real-time features (WebSocket, SSE) with client-server interaction
-- Data flow from database through API to user interface
-
-Default Indicators → General QA:
-- CLI tools and command-line applications
-- Libraries, utilities, and helper functions
-- Configuration file processing
-- Data processing scripts and algorithms
-- Testing frameworks and test utilities
-- Build tools and automation scripts
-```
-
-#### Practical Usage Examples
-
-**Example 1: API Implementation**
-```
-User Request: "Create a REST API for user management with CRUD operations"
-Engineer Output: "Implemented FastAPI endpoints in /api/users.py with authentication"
-
-PM Analysis:
-✅ Backend Keywords: "REST API", "endpoints", "authentication"
-✅ File Indicators: "/api/users.py"
-✅ Technology: FastAPI (Python backend)
-
-PM Decision: Route to API QA Agent
-API QA Tasks:
-- Test GET /users (list users)
-- Test POST /users (create user) 
-- Test PUT /users/{id} (update user)
-- Test DELETE /users/{id} (delete user)
-- Validate authentication headers
-- Check error responses (400, 401, 404, 500)
-- Verify response schemas match OpenAPI spec
-- Performance test with 100 concurrent requests
-
-API QA Output: "API QA Complete: Pass - [Endpoints tested: 4, Avg response time: 45ms, Auth flows: 2, Security checks: 3, Issues: 0]"
-```
-
-**Example 2: Web UI Implementation**
-```
-User Request: "Build a responsive dashboard with charts and user profile"
-Web UI Output: "Created React dashboard in /components/Dashboard.tsx with mobile-first design"
-
-PM Analysis:
-✅ Frontend Keywords: "responsive dashboard", "charts", "user profile"
-✅ File Indicators: "/components/Dashboard.tsx"
-✅ Technology: React (frontend framework)
-
-PM Decision: Route to Web QA Agent
-Web QA Tasks:
-- Test dashboard rendering on desktop (1920x1080)
-- Test mobile responsiveness (375x667, 768x1024)
-- Verify chart interactivity and data visualization
-- Test user profile edit functionality
-- Check accessibility (WCAG 2.1 AA compliance)
-- Cross-browser testing (Chrome, Firefox, Safari)
-- Measure Core Web Vitals (LCP, FID, CLS)
-
-Web QA Output: "Web QA Complete: Pass - [Browsers tested: 3, Pages validated: 2, Accessibility score: 95%, Performance score: 88%, Issues: 1 minor]"
-```
-
-**Example 3: Full-Stack Feature**
-```
-User Request: "Implement complete authentication system with login UI and JWT backend"
-Engineer Output: "Built auth API in /api/auth.py and login components in /components/auth/"
-
-PM Analysis:
-✅ Backend Keywords: "JWT backend", "auth API"
-✅ Frontend Keywords: "login UI", "components"
-✅ File Indicators: "/api/auth.py", "/components/auth/"
-✅ Full-Stack Feature: Both backend and frontend implementation
-
-PM Decision: Sequential QA (API QA → Web QA → Integration)
-
-Phase 1 - API QA:
-- Test POST /auth/login endpoint
-- Test POST /auth/register endpoint  
-- Test JWT token generation and validation
-- Test protected endpoint access with tokens
-- Verify password hashing and security
-
-API QA Output: "API QA Complete: Pass - [Endpoints tested: 3, Auth flows: 2, Security checks: 5, Issues: 0]"
-
-Phase 2 - Web QA:
-- Test login form submission and validation
-- Test registration form with field validation
-- Test token storage and automatic logout
-- Test protected route navigation
-- Test error handling for invalid credentials
-
-Web QA Output: "Web QA Complete: Pass - [Forms tested: 2, User flows: 3, Error states: 4, Issues: 0]"
-
-Phase 3 - Integration:
-- Test end-to-end user registration flow
-- Test login → protected page access flow
-- Test token refresh and session management
-- Test logout and token cleanup
-
-PM Final Output: "Full-Stack QA Complete: Pass - API: [3 endpoints validated], Web: [2 forms tested], Integration: [E2E flows working]"
-```
-
-**Example 4: CLI Tool Implementation**
-```
-User Request: "Create a command-line tool for file processing"
-Engineer Output: "Built CLI tool in /src/file_processor.py with argparse"
-
-PM Analysis:
-❌ No Backend API Keywords
-❌ No Frontend UI Keywords  
-✅ Default Indicators: CLI tool, file processing, Python script
-
-PM Decision: Route to General QA Agent
-General QA Tasks:
-- Test CLI commands with various arguments
-- Test file input/output operations
-- Test error handling for invalid files
-- Test cross-platform compatibility
-- Verify help documentation and usage
-
-General QA Output: "QA Complete: Pass - [CLI commands: 5, File operations: 3, Error cases: 4, Issues: 0]"
-```
+The PM routes QA work based on agent capabilities discovered at runtime. QA agents are selected dynamically based on their routing metadata (keywords, paths, file extensions) matching the implementation context.
+
+**Available QA Agents** (discovered dynamically):
+- **API QA Agent**: Backend/server testing (REST, GraphQL, authentication)
+- **Web QA Agent**: Frontend/browser testing (UI, accessibility, responsive)  
+- **General QA Agent**: Default testing (libraries, CLI tools, utilities)
+
+**Routing Decision Process**:
+1. Analyze implementation output for keywords, paths, and file patterns
+2. Match against agent routing metadata from templates
+3. Select agent(s) with highest confidence scores
+4. For multiple matches, execute by priority (specialized before general)
+5. For full-stack changes, run specialized agents sequentially
+
+**Dynamic Routing Benefits**:
+- Agent capabilities always current (pulled from templates)
+- New QA agents automatically available when deployed
+- Routing logic centralized in agent templates
+- No duplicate documentation to maintain
+
+The routing metadata in each agent template defines:
+- `keywords`: Trigger words that indicate this agent should be used
+- `paths`: Directory patterns that match this agent's expertise
+- `extensions`: File types this agent specializes in testing
+- `priority`: Execution order when multiple agents match
+- `confidence_threshold`: Minimum score for agent selection
+
+See deployed agent capabilities via agent discovery for current routing details.
 
 **CRITICAL Requirements**:
 - QA Agent MUST receive original user instructions for context
@@ -323,44 +90,6 @@ Context:
   Risk Factors: <Potential issues and mitigation strategies>
 ```
 
-### QA Agent Selection Logic
-
-When delegating QA tasks, the PM must intelligently select the appropriate QA agent based on implementation context:
-
-```python
-# Pseudo-code for QA agent selection
-def select_qa_agent(implementation_context, available_agents):
-    backend_keywords = ['api', 'endpoint', 'route', 'rest', 'graphql', 
-                       'server', 'backend', 'auth', 'database', 'service']
-    frontend_keywords = ['web', 'ui', 'page', 'frontend', 'browser', 
-                        'component', 'responsive', 'accessibility', 'react', 'vue']
-    
-    context_lower = implementation_context.lower()
-    
-    has_backend = any(keyword in context_lower for keyword in backend_keywords)
-    has_frontend = any(keyword in context_lower for keyword in frontend_keywords)
-    
-    # Check file extensions and paths
-    if any(ext in implementation_context for ext in ['.py', '.go', '.java', '/api/', '/routes/']):
-        has_backend = True
-    if any(ext in implementation_context for ext in ['.jsx', '.tsx', '.vue', '/components/', '/pages/']):
-        has_frontend = True
-    
-    # Determine QA agent(s) to use
-    if has_backend and has_frontend:
-        return ['api_qa', 'web_qa']  # Sequential testing for full-stack
-    elif has_backend and 'api_qa' in available_agents:
-        return ['api_qa']
-    elif has_frontend and 'web_qa' in available_agents:
-        return ['web_qa']
-    else:
-        return ['qa']  # Default general QA
-
-# Example usage in delegation
-selected_qa = select_qa_agent(engineer_output, deployed_agents)
-for qa_agent in selected_qa:
-    delegate_to(qa_agent, original_requirements)
-```
 
 ### Research-First Scenarios
 
@@ -378,6 +107,8 @@ Delegate to Research when:
 
 The PM MUST create and maintain tickets for ALL user requests. Failure to track work in tickets is a CRITICAL VIOLATION of PM protocols.
 
+**IMPORTANT**: The ticketing system uses `aitrackdown` CLI directly, NOT `claude-mpm tickets` commands.
+
 **ALWAYS delegate to Ticketing Agent when user mentions:**
 - "ticket", "tickets", "ticketing"
 - "epic", "epics"  
@@ -390,29 +121,29 @@ The PM MUST create and maintain tickets for ALL user requests. Failure to track
 **AUTOMATIC TICKETING WORKFLOW** (when ticketing is requested):
 
 #### Session Initialization
-1. **Single Session Work**: Create an ISS (Issue) ticket for the session
-   - Title: Clear description of user's request
-   - Parent: Attach to appropriate existing epic or create new one
-   - Status: Set to "in_progress"
+1. **Single Session Work**: Delegate to Ticketing Agent to create an ISS (Issue) ticket
+   - Use command: `aitrackdown create issue "Title" --description "Details"`
+   - Attach to appropriate existing epic or create new one
+   - Transition to in_progress: `aitrackdown transition ISS-XXXX in-progress`
    
-2. **Multi-Session Work**: Create an EP (Epic) ticket
-   - Title: High-level objective
-   - Create first ISS (Issue) for current session
+2. **Multi-Session Work**: Delegate to Ticketing Agent to create an EP (Epic) ticket
+   - Use command: `aitrackdown create epic "Title" --description "Overview"`
+   - Create first ISS (Issue) for current session with `--issue EP-XXXX` parent
    - Attach session issue to the epic
 
 #### Phase Tracking
 After EACH workflow phase completion, delegate to Ticketing Agent to:
 
 1. **Create TSK (Task) ticket** for the completed phase:
-   - **Research Phase**: TSK ticket with research findings
-   - **Implementation Phase**: TSK ticket with code changes summary
-   - **QA Phase**: TSK ticket with test results
-   - **Documentation Phase**: TSK ticket with docs created/updated
+   - **Research Phase**: `aitrackdown create task "Research findings" --issue ISS-XXXX`
+   - **Implementation Phase**: `aitrackdown create task "Code implementation" --issue ISS-XXXX`
+   - **QA Phase**: `aitrackdown create task "Testing results" --issue ISS-XXXX`
+   - **Documentation Phase**: `aitrackdown create task "Documentation updates" --issue ISS-XXXX`
    
 2. **Update parent ISS ticket** with:
-   - Comment summarizing phase completion
-   - Link to the created TSK ticket
-   - Update status if needed
+   - Comment: `aitrackdown comment ISS-XXXX "Phase completion summary"`
+   - Transition status: `aitrackdown transition ISS-XXXX [status]`
+   - Valid statuses: open, in-progress, ready, tested, blocked
 
 3. **Task Ticket Content** should include:
    - Agent that performed the work
@@ -422,9 +153,9 @@ After EACH workflow phase completion, delegate to Ticketing Agent to:
    - Any blockers or issues encountered
 
 #### Continuous Updates
-- **After significant changes**: Add comment to relevant ticket
-- **When blockers arise**: Update ticket status to "blocked" with explanation
-- **On completion**: Update ISS ticket to "done" with final summary
+- **After significant changes**: `aitrackdown comment ISS-XXXX "Progress update"`
+- **When blockers arise**: `aitrackdown transition ISS-XXXX blocked`
+- **On completion**: `aitrackdown transition ISS-XXXX tested` or `ready`
 
 #### Ticket Hierarchy Example
 ```
@@ -437,16 +168,25 @@ EP-0001: Authentication System Overhaul (Epic)
 ```
 
 The Ticketing Agent specializes in:
-- Creating and managing epics, issues, and tasks
-- Generating structured project documentation
-- Breaking down work into manageable pieces
-- Tracking project progress and dependencies
+- Creating and managing epics, issues, and tasks using aitrackdown CLI
+- Using proper commands: `aitrackdown create issue/task/epic`
+- Updating tickets: `aitrackdown transition`, `aitrackdown comment`
+- Tracking project progress with `aitrackdown status tasks`
 - Maintaining clear audit trail of all work performed
 
+### Proper Ticket Creation Delegation
+
+When delegating to Ticketing Agent, specify the exact aitrackdown commands:
+- **Create Issue**: "Use `aitrackdown create issue 'Title' --description 'Details'`"
+- **Create Task**: "Use `aitrackdown create task 'Title' --issue ISS-XXXX`"
+- **Update Status**: "Use `aitrackdown transition ISS-XXXX in-progress`"
+- **Add Comment**: "Use `aitrackdown comment ISS-XXXX 'Update message'`"
+
 ### Ticket-Based Work Resumption
 
 **Tickets replace session resume for work continuation**:
-- When starting any session, first check for open ISS tickets
+- Check for open tickets: `aitrackdown status tasks --filter "status:in-progress"`
+- Show ticket details: `aitrackdown show ISS-XXXX`
 - Resume work on existing tickets rather than starting new ones
 - Use ticket history to understand context and progress
 - This ensures continuity across sessions and PMs

claude_mpm/agents/__init__.py

@@ -31,24 +31,24 @@ from .agents_metadata import (
 
 # Available system agents
 __all__ = [
-    # Generic agent interface
-    "get_agent_prompt",
-    # Agent utility functions
-    "list_available_agents",
-    "clear_agent_cache",
-    "validate_agent_files",
+    "ALL_AGENT_CONFIGS",
+    "DATA_ENGINEER_CONFIG",
     # Agent configs
     "DOCUMENTATION_CONFIG",
-    "VERSION_CONTROL_CONFIG",
+    "ENGINEER_CONFIG",
+    "OPS_CONFIG",
     "QA_CONFIG",
     "RESEARCH_CONFIG",
-    "OPS_CONFIG",
     "SECURITY_CONFIG",
-    "ENGINEER_CONFIG",
-    "DATA_ENGINEER_CONFIG",
-    "ALL_AGENT_CONFIGS",
     # System registry
     "SYSTEM_AGENTS",
+    "VERSION_CONTROL_CONFIG",
+    "clear_agent_cache",
+    # Generic agent interface
+    "get_agent_prompt",
+    # Agent utility functions
+    "list_available_agents",
+    "validate_agent_files",
 ]
 
 # System agent registry - using generic agent loading

claude_mpm/agents/agent_loader.py

@@ -40,8 +40,12 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
 # Import modular components
-from claude_mpm.core.unified_agent_registry import AgentTier
-from claude_mpm.core.unified_agent_registry import UnifiedAgentRegistry as AgentRegistry
+from claude_mpm.core.unified_agent_registry import (
+    AgentTier,
+    get_agent_registry,
+)
+from claude_mpm.core.unified_paths import get_path_manager
+from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 
 from ..core.agent_name_normalizer import AgentNameNormalizer
 from .base_agent_loader import prepend_base_instructions
@@ -71,11 +75,11 @@ __all__ = [
     "AgentLoader",
     "AgentTier",
     "get_agent_prompt",
-    "list_available_agents",
-    "validate_agent_files",
-    "reload_agents",
     "get_agent_tier",
     "list_agents_by_tier",
+    "list_available_agents",
+    "reload_agents",
+    "validate_agent_files",
 ]
 
 
@@ -237,8 +241,7 @@ class AgentLoader:
             return None
 
         # Prepend base instructions
-        full_prompt = prepend_base_instructions(instructions)
-        return full_prompt
+        return prepend_base_instructions(instructions)
 
     def get_agent_metadata(self, agent_id: str) -> Optional[Dict[str, Any]]:
         """
@@ -626,9 +629,11 @@ def _get_model_config(
         selected_model = default_model
         model_config = {
             "selection_method": "agent_default",
-            "reason": "dynamic_selection_disabled"
-            if not enable_dynamic_selection
-            else "no_complexity_analysis",
+            "reason": (
+                "dynamic_selection_disabled"
+                if not enable_dynamic_selection
+                else "no_complexity_analysis"
+            ),
             "default_model": default_model,
         }
 
@@ -718,14 +723,13 @@ def get_agent_prompt(
                 actual_agent_id = f"{agent_key}_agent"
             else:
                 actual_agent_id = agent_key  # Use normalized key
+        # Unknown agent name - check both variations
+        elif loader.get_agent(cleaned):
+            actual_agent_id = cleaned
+        elif loader.get_agent(f"{cleaned}_agent"):
+            actual_agent_id = f"{cleaned}_agent"
         else:
-            # Unknown agent name - check both variations
-            if loader.get_agent(cleaned):
-                actual_agent_id = cleaned
-            elif loader.get_agent(f"{cleaned}_agent"):
-                actual_agent_id = f"{cleaned}_agent"
-            else:
-                actual_agent_id = cleaned  # Use cleaned name
+            actual_agent_id = cleaned  # Use cleaned name
 
     # Log the normalization for debugging
     if agent_name != actual_agent_id:
@@ -781,8 +785,7 @@ def get_agent_prompt(
     # Return format based on caller's needs
     if return_model_info:
         return final_prompt, selected_model, model_config
-    else:
-        return final_prompt
+    return final_prompt
 
 
 # Legacy hardcoded agent functions removed - use get_agent_prompt(agent_id) instead
@@ -881,7 +884,7 @@ def clear_agent_cache(agent_name: Optional[str] = None) -> None:
         else:
             # Clear all agent caches by iterating through registry
             loader = _get_loader()
-            for agent_id in loader._agent_registry.keys():
+            for agent_id in loader._agent_registry:
                 cache_key = f"{AGENT_CACHE_PREFIX}{agent_id}"
                 cache.invalidate(cache_key)
             logger.debug("All agent caches cleared")

claude_mpm/agents/agent_loader_integration.py

@@ -12,7 +12,7 @@ from typing import Any, Dict, Optional
 
 from ..models.agent_definition import AgentDefinition
 from ..services import AgentManager
-from .agent_loader import get_agent_prompt, load_agent_prompt_from_md
+from .agent_loader import get_agent_prompt
 
 logger = logging.getLogger(__name__)
 

claude_mpm/agents/agents_metadata.py

@@ -263,6 +263,32 @@ PROJECT_ORGANIZER_CONFIG = {
     },
 }
 
+# ImageMagick Agent Metadata
+IMAGEMAGICK_CONFIG = {
+    "name": "imagemagick_agent",
+    "version": "1.0.0",
+    "type": "optimization_agent",
+    "capabilities": [
+        "image_optimization",
+        "format_conversion",
+        "responsive_image_generation",
+        "batch_processing",
+        "web_performance_optimization",
+        "core_web_vitals_improvement",
+        "avif_webp_conversion",
+        "quality_compression",
+    ],
+    "primary_interface": "imagemagick_cli",
+    "performance_targets": {
+        "single_image_optimization": "30s",
+        "batch_processing_100_images": "10m",
+        "format_conversion": "10s",
+        "responsive_set_generation": "60s",
+        "file_size_reduction": "50-70%",
+        "quality_threshold": "0.95_ssim",
+    },
+}
+
 # Aggregate all configs for easy access
 ALL_AGENT_CONFIGS = {
     "documentation": DOCUMENTATION_CONFIG,
@@ -276,4 +302,5 @@ ALL_AGENT_CONFIGS = {
     "engineer": ENGINEER_CONFIG,
     "data_engineer": DATA_ENGINEER_CONFIG,
     "project_organizer": PROJECT_ORGANIZER_CONFIG,
+    "imagemagick": IMAGEMAGICK_CONFIG,
 }

claude_mpm/agents/async_agent_loader.py

@@ -36,10 +36,8 @@ import aiofiles
 
 from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 
-from ..core.agent_name_normalizer import AgentNameNormalizer
 from ..core.unified_paths import get_path_manager
-from ..validation.agent_validator import AgentValidator, ValidationResult
-from .base_agent_loader import prepend_base_instructions
+from ..validation.agent_validator import AgentValidator
 from .frontmatter_validator import FrontmatterValidator
 
 # Module-level logger
@@ -184,10 +182,9 @@ class AsyncAgentLoader:
             try:
                 if file_path.suffix == ".json":
                     return await self.load_json_agent_async(file_path)
-                elif file_path.suffix == ".md":
+                if file_path.suffix == ".md":
                     return await self.load_md_agent_async(file_path)
-                else:
-                    return None
+                return None
             except Exception as e:
                 logger.error(f"Failed to load {file_path}: {e}")
                 return None
@@ -228,7 +225,7 @@ class AsyncAgentLoader:
         """
         try:
             # Non-blocking file read
-            async with aiofiles.open(file_path, "r") as f:
+            async with aiofiles.open(file_path) as f:
                 content = await f.read()
 
             # Parse JSON in thread pool (CPU-bound)
@@ -261,7 +258,7 @@ class AsyncAgentLoader:
         """
         try:
             # Non-blocking file read
-            async with aiofiles.open(file_path, "r") as f:
+            async with aiofiles.open(file_path) as f:
                 content = await f.read()
 
             # Parse frontmatter in thread pool