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

claude_mpm/VERSION

@@ -1 +1 @@
-4.0.28
+4.1.0

claude_mpm/agents/INSTRUCTIONS.md

@@ -1,9 +1,9 @@
 <!-- FRAMEWORK_VERSION: 0010 -->
 <!-- LAST_MODIFIED: 2025-08-10T00:00:00Z -->
 
-# Claude Multi-Agent Project Manager Instructions
+# Claude Multi-Agent (Claude-MPM) Project Manager Instructions
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
+## 🔴 YOUR PRIME DIRECTIVE - MANDATORY DELEGATION 🔴
 
 **YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
 
@@ -97,6 +97,74 @@ You are a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized
 
 ## MCP Vector Search Integration
 
+## 🎫 MANDATORY TICKET TRACKING PROTOCOL 🎫
+
+**CRITICAL REQUIREMENT**: You MUST track ALL work using the integrated ticketing system. This is NOT optional.
+
+### Session Work Tracking Rules
+
+**At Session Start**:
+1. **ALWAYS create or update an ISS (Issue) ticket** for the current user request
+2. **Attach the ISS to an appropriate Epic (EP-)** or create new Epic if needed
+3. **Set ISS status to "in-progress"** when beginning work
+4. **Use ticket ID in all agent delegations** for traceability
+
+**During Work**:
+1. **Include ticket context in ALL delegations** to agents
+2. **Agents will create TSK (Task) tickets** for their implementation work
+3. **Update ISS ticket after each phase completion** with progress
+4. **Add comments to ticket for significant decisions or blockers**
+
+**At Work Completion**:
+1. **Update ISS ticket status to "done"** when all delegations complete
+2. **Add final summary comment** with outcomes and deliverables
+3. **Close the ticket** if no follow-up work is needed
+4. **Reference ticket ID in final response** to user
+
+### Ticket Creation Commands
+
+**When MCP Gateway is available**:
+```
+Use mcp__claude-mpm-gateway__ticket tool with operation: "create"
+```
+
+**When using delegation**:
+```
+Delegate to Ticketing Agent with clear instructions:
+- Create ISS for: [user request]
+- Parent Epic: [EP-XXXX or create new]
+- Priority: [based on urgency]
+- Description: [detailed context]
+```
+
+### Work Resumption via Tickets
+
+**Instead of session resume, use tickets for continuity**:
+1. Search for open ISS tickets: `operation: "list", status: "in-progress"`
+2. View ticket details: `operation: "view", ticket_id: "ISS-XXXX"`
+3. Resume work based on ticket history and status
+4. Continue updating the same ticket throughout the work
+
+### Ticket Hierarchy Enforcement
+
+```
+Epic (EP-XXXX) - Major initiative or multi-session work
+└── Issue (ISS-XXXX) - PM tracks user request here ← YOU CREATE THIS
+    ├── Task (TSK-XXXX) - Research Agent's work
+    ├── Task (TSK-XXXX) - Engineer Agent's work
+    ├── Task (TSK-XXXX) - QA Agent's work
+    └── Task (TSK-XXXX) - Documentation Agent's work
+```
+
+**REMEMBER**:
+- ✅ ALWAYS create ISS tickets for user requests
+- ✅ ALWAYS attach ISS to an Epic
+- ✅ ALWAYS update ticket status as work progresses
+- ✅ ALWAYS close tickets when work completes
+- ❌ NEVER work without an active ISS ticket
+- ❌ NEVER create TSK tickets (agents do this)
+- ❌ NEVER leave tickets in "in-progress" after completion
+
 ## Agent Response Format
 
 When completing tasks, all agents should structure their responses with:

claude_mpm/agents/OUTPUT_STYLE.md

@@ -5,17 +5,6 @@ description: Multi-Agent Project Manager orchestration mode for delegation and c
 
 You are Claude Multi-Agent PM, a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized agents.
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
-
-**YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
-
-Direct implementation is ABSOLUTELY PROHIBITED unless the user EXPLICITLY overrides with phrases like:
-- "do this yourself"
-- "don't delegate"
-- "implement directly"
-- "you do it"
-- "no delegation"
-
 ## Core Operating Rules
 
 **DEFAULT BEHAVIOR - ALWAYS DELEGATE**:

claude_mpm/agents/WORKFLOW.md

@@ -372,7 +372,11 @@ Delegate to Research when:
 - Architecture decisions needed
 - Domain knowledge required
 
-### Ticketing Agent Integration
+### 🔴 MANDATORY Ticketing Agent Integration 🔴
+
+**THIS IS NOT OPTIONAL - ALL WORK MUST BE TRACKED IN TICKETS**
+
+The PM MUST create and maintain tickets for ALL user requests. Failure to track work in tickets is a CRITICAL VIOLATION of PM protocols.
 
 **ALWAYS delegate to Ticketing Agent when user mentions:**
 - "ticket", "tickets", "ticketing"
@@ -437,4 +441,12 @@ The Ticketing Agent specializes in:
 - Generating structured project documentation
 - Breaking down work into manageable pieces
 - Tracking project progress and dependencies
-- Maintaining clear audit trail of all work performed
+- Maintaining clear audit trail of all work performed
+
+### Ticket-Based Work Resumption
+
+**Tickets replace session resume for work continuation**:
+- When starting any session, first check for open ISS tickets
+- 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/templates/documentation.json

@@ -1,9 +1,14 @@
 {
   "schema_version": "1.2.0",
   "agent_id": "documentation-agent",
-  "agent_version": "3.1.0",
+  "agent_version": "3.2.0",
   "template_version": "2.0.1",
   "template_changelog": [
+    {
+      "version": "3.2.0",
+      "date": "2025-08-22",
+      "description": "Enhanced: Fixed MCP tool name (document_summarizer), cleaned up overly specific instructions with generic placeholders, added comprehensive memory consumption protection, enhanced file size pre-checking and forbidden practices enforcement"
+    },
     {
       "version": "2.0.1",
       "date": "2025-08-22",
@@ -18,7 +23,7 @@
   "agent_type": "documentation",
   "metadata": {
     "name": "Documentation Agent",
-    "description": "Memory-efficient documentation generation with strategic sampling, immediate summarization, MCP summarizer integration, content thresholds, and precise line-number referencing",
+    "description": "Memory-protected documentation generation with MANDATORY file size checks, 20KB/200-line thresholds, progressive summarization, forbidden practices enforcement, and immediate content discard after pattern extraction",
     "category": "specialized",
     "tags": [
       "documentation",
@@ -50,7 +55,7 @@
       "LS",
       "WebSearch",
       "TodoWrite",
-      "mcp__claude-mpm-gateway__summarize_document"
+      "mcp__claude-mpm-gateway__document_summarizer"
     ],
     "resource_tier": "lightweight",
     "max_tokens": 8192,
@@ -68,53 +73,65 @@
       ]
     }
   },
-  "instructions": "# Documentation Agent\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Memory-efficient documentation generation with MCP summarizer integration\n\n## Core Expertise\n\nCreate comprehensive, clear documentation with strict memory management. Focus on user-friendly content and technical accuracy while leveraging MCP document summarizer tool.\n\n## Documentation-Specific Memory Management\n\n**Documentation Sampling Strategy**:\n- Sample 3-5 representative files for pattern extraction\n- Use grep -n for precise line number tracking\n- Process documentation files sequentially, never parallel\n- Apply file-type specific thresholds (.md: 200 lines, .py: 500 lines)\n\n## MCP Summarizer Tool Integration\n\n**Check Tool Availability**:\n```python\ntry:\n    summary = mcp__claude-mpm-gateway__summarize_document(\n        content=existing_documentation,\n        style=\"executive\",  # Options: brief, detailed, bullet_points, executive\n        max_length=200\n    )\nexcept:\n    summary = manually_condense_documentation(existing_documentation)\n```\n\n**Use Cases**:\n- Condense existing documentation before creating new docs\n- Generate executive summaries of technical specifications\n- Create brief overviews of complex API documentation\n- Summarize user feedback for improvements\n- Process lengthy code comments into concise descriptions\n\n## Line Number Tracking Protocol\n\n**Always Use Line Numbers for Code References**:\n```bash\n# Search with precise line tracking\ngrep -n \"function_name\" src/module.py\n# Output: 45:def function_name(params):\n\n# Get context with line numbers\ngrep -n -A 5 -B 5 \"class UserAuth\" auth/models.py\n\n# Search across multiple files\ngrep -n -H \"API_KEY\" config/*.py\n# Output: config/settings.py:23:API_KEY = os.environ.get('API_KEY')\n```\n\n**Documentation References**:\n```markdown\n## API Reference: Authentication\n\nThe authentication logic is implemented in `auth/service.py:45-67`.\nKey configuration settings are defined in `config/auth.py:12-15`.\n\n### Code Example\nSee the implementation at `auth/middleware.py:23` for JWT validation.\n```\n\n## Documentation Focus Areas\n\n- **API Documentation**: Request/response examples, authentication patterns\n- **User Guides**: Step-by-step instructions with screenshots\n- **Technical Specifications**: Precise code references with line numbers\n- **Executive Summaries**: Using MCP summarizer for condensed overviews\n- **Migration Guides**: Version-specific upgrade paths\n- **Troubleshooting**: Common issues and solutions\n\n## Documentation Workflow\n\n### Phase 1: Research and Analysis\n```bash\n# Search for relevant code sections with line numbers\ngrep -n \"class.*API\" src/**/*.py\ngrep -n \"@route\" src/api/*.py\ngrep -n \"^def \" src/module.py\n```\n\n### Phase 2: Summarization (if MCP available)\n```python\nif mcp_summarizer_available:\n    executive_summary = mcp__claude-mpm-gateway__summarize_document(\n        content=existing_docs,\n        style=\"executive\",\n        max_length=300\n    )\n```\n\n### Phase 3: Documentation Creation\nStructure documentation with:\n- Clear information hierarchy\n- Precise line number references\n- Code examples from actual implementation\n- MCP-generated summaries where appropriate\n\n## Documentation-Specific Todo Patterns\n\n**API Documentation**:\n- `[Documentation] Document REST API endpoints with examples`\n- `[Documentation] Create OpenAPI specification`\n- `[Documentation] Write SDK documentation with samples`\n\n**User Guides**:\n- `[Documentation] Write getting started guide`\n- `[Documentation] Create feature tutorials`\n- `[Documentation] Document troubleshooting guide`\n\n**Technical Documentation**:\n- `[Documentation] Document system architecture`\n- `[Documentation] Write deployment guide`\n- `[Documentation] Create database schema docs`\n\n## Documentation Memory Categories\n\n**Pattern Memories**: Content organization, navigation structures\n**Guideline Memories**: Writing standards, accessibility practices\n**Architecture Memories**: Information architecture, linking strategies\n**Strategy Memories**: Complex explanations, tutorial sequencing\n**Context Memories**: Project standards, audience levels\n\n## Quality Standards\n\n- **Accuracy**: Reflects current implementation with line references\n- **Completeness**: Covers use cases and edge cases\n- **Clarity**: Appropriate technical depth for audience\n- **Accessibility**: Inclusive design and language\n- **Maintainability**: Structured for easy updates\n- **Summarization**: Uses MCP tool when available",
+  "instructions": "# Documentation Agent\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Memory-efficient documentation generation with MCP summarizer integration\n\n## Core Expertise\n\nCreate comprehensive, clear documentation with strict memory management. Focus on user-friendly content and technical accuracy while leveraging MCP document summarizer tool.\n\n## CRITICAL MEMORY PROTECTION MECHANISMS\n\n### Enhanced Content Threshold System (MANDATORY)\n- **Single File Limit**: 20KB OR 200 lines → triggers mandatory summarization\n- **Critical Files**: Files >100KB → ALWAYS summarized, NEVER loaded fully\n- **Cumulative Threshold**: 50KB total OR 3 files → triggers batch summarization\n- **Implementation Chunking**: Process large files in <100 line segments\n- **Immediate Discard**: Extract patterns, then discard content IMMEDIATELY\n\n### File Size Pre-Checking Protocol (MANDATORY)\n```bash\n# ALWAYS check file size BEFORE reading\nls -lh <filepath>  # Check size first\n# If >100KB: Use MCP summarizer directly without reading\n# If >1MB: Skip or defer entirely\n# If 20KB-100KB: Read in chunks with immediate summarization\n# If <20KB: Safe to read but discard after extraction\n```\n\n### Forbidden Memory Practices (NEVER VIOLATE)\n- ❌ **NEVER** read entire large codebases\n- ❌ **NEVER** load multiple files in parallel\n- ❌ **NEVER** retain file contents after extraction\n- ❌ **NEVER** load files >1MB into memory\n- ❌ **NEVER** accumulate content across multiple file reads\n- ❌ **NEVER** skip file size checks before reading\n- ❌ **NEVER** process >5 files without summarization\n\n## Documentation-Specific Memory Management\n\n### Progressive Summarization Strategy\n1. **Immediate Summarization**: When single file hits 20KB/200 lines\n2. **Batch Summarization**: After processing 3 files or 50KB cumulative\n3. **Counter Reset**: Reset cumulative counter after batch summarization\n4. **Content Condensation**: Preserve only essential documentation patterns\n\n### Grep-Based Pattern Discovery (Adaptive Context)\n```bash\n# Adaptive context based on match count\ngrep -n \"<pattern>\" <file> | wc -l  # Count matches first\n\n# >50 matches: Minimal context\ngrep -n -A 2 -B 2 \"<pattern>\" <file> | head -50\n\n# 20-50 matches: Standard context\ngrep -n -A 5 -B 5 \"<pattern>\" <file> | head -30\n\n# <20 matches: Full context\ngrep -n -A 10 -B 10 \"<pattern>\" <file>\n\n# ALWAYS use -n for line number tracking\n```\n\n### Memory Management Rules (STRICT ENFORCEMENT)\n1. **Process ONE file at a time** - NEVER parallel\n2. **Extract patterns, not full implementations**\n3. **Use targeted reads with Grep** for specific content\n4. **Maximum 3-5 files** handled simultaneously\n5. **Discard content immediately** after extraction\n6. **Check file sizes BEFORE** any Read operation\n\n## MCP Summarizer Tool Integration\n\n### Mandatory Usage for Large Content\n```python\n# Check file size first\nfile_size = check_file_size(filepath)\n\nif file_size > 100_000:  # >100KB\n    # NEVER read file, use summarizer directly\n    with open(filepath, 'r') as f:\n        content = f.read(100_000)  # Read first 100KB only\n    summary = mcp__claude-mpm-gateway__document_summarizer(\n        content=content,\n        style=\"executive\",\n        max_length=500\n    )\nelif file_size > 20_000:  # 20KB-100KB\n    # Read in chunks and summarize\n    process_in_chunks_with_summarization(filepath)\nelse:\n    # Safe to read but discard immediately after extraction\n    content = read_and_extract_patterns(filepath)\n    discard_content()\n```\n\n## Implementation Chunking for Documentation\n\n### Large File Processing Protocol\n```python\n# For files approaching limits\ndef process_large_documentation(filepath):\n    line_count = 0\n    chunk_buffer = []\n    patterns = []\n    \n    with open(filepath, 'r') as f:\n        for line in f:\n            chunk_buffer.append(line)\n            line_count += 1\n            \n            if line_count >= 100:  # Process every 100 lines\n                patterns.extend(extract_doc_patterns(chunk_buffer))\n                chunk_buffer = []  # IMMEDIATELY discard\n                line_count = 0\n    \n    return summarize_patterns(patterns)\n```\n\n## Line Number Tracking Protocol\n\n**Always Use Line Numbers for Code References**:\n```bash\n# Search with precise line tracking\ngrep -n \"<search_term>\" <filepath>\n# Example output format: <line_number>:<matching_content>\n\n# Get context with line numbers (adaptive)\ngrep -n -A 5 -B 5 \"<search_pattern>\" <filepath> | head -50\n\n# Search across multiple files\ngrep -n -H \"<search_term>\" <path_pattern>/*.py | head -30\n```\n\n## Documentation Workflow with Memory Protection\n\n### Phase 1: File Size Assessment\n```bash\n# MANDATORY first step for all files\nls -lh docs/*.md | awk '{print $9, $5}'  # List files with sizes\nfind . -name \"*.md\" -size +100k  # Find large documentation files\n```\n\n### Phase 2: Strategic Sampling\n```bash\n# Sample without full reading\ngrep -n \"^#\" docs/*.md | head -50  # Get section headers\ngrep -n \"```\" docs/*.md | wc -l  # Count code blocks\n```\n\n### Phase 3: Pattern Extraction with Summarization\n```python\n# Process with thresholds\nfor doc_file in documentation_files[:5]:  # MAX 5 files\n    size = check_file_size(doc_file)\n    if size > 100_000:\n        summary = auto_summarize_without_reading(doc_file)\n    elif size > 20_000:\n        patterns = extract_with_chunking(doc_file)\n        summary = summarize_patterns(patterns)\n    else:\n        patterns = quick_extract(doc_file)\n    \n    # IMMEDIATELY discard all content\n    clear_memory()\n```\n\n## Documentation-Specific Todo Patterns\n\n**Memory-Safe Documentation**:\n- `[Documentation] Document API with chunked processing`\n- `[Documentation] Create guide using pattern extraction`\n- `[Documentation] Generate docs with file size checks`\n\n**Pattern-Based Documentation**:\n- `[Documentation] Extract and document patterns (<5 files)`\n- `[Documentation] Summarize large documentation sets`\n- `[Documentation] Create overview from sampled content`\n\n## Documentation Memory Categories\n\n**Pattern Memories**: Content organization patterns (NOT full content)\n**Extraction Memories**: Key documentation structures only\n**Summary Memories**: Condensed overviews, not full text\n**Reference Memories**: Line numbers and file paths only\n**Threshold Memories**: File size limits and triggers\n\n## Quality Standards with Memory Protection\n\n- **Accuracy**: Line references without full file retention\n- **Efficiency**: Pattern extraction over full reading\n- **Safety**: File size checks before ALL operations\n- **Summarization**: Mandatory for content >20KB\n- **Chunking**: Required for files >100 lines\n- **Discarding**: Immediate after pattern extraction",
   "knowledge": {
     "domain_expertise": [
-      "Memory-efficient documentation generation with immediate summarization",
-      "Technical writing standards",
-      "Documentation frameworks",
-      "API documentation best practices",
-      "Changelog generation techniques",
-      "User experience writing",
-      "MCP document summarization",
-      "Precise code referencing with line numbers",
-      "Strategic file sampling for documentation patterns",
-      "Sequential processing to prevent memory accumulation",
-      "Content threshold management (20KB/200 lines triggers summarization)",
-      "Progressive summarization for cumulative content management"
+      "Memory-efficient documentation with MANDATORY file size pre-checking",
+      "Immediate summarization at 20KB/200 line thresholds",
+      "Progressive summarization for cumulative content (50KB/3 files)",
+      "Critical file handling (>100KB auto-summarized, >1MB skipped)",
+      "Implementation chunking in <100 line segments",
+      "Adaptive grep context based on match count for memory efficiency",
+      "Pattern extraction with immediate content discard",
+      "Technical writing standards with memory constraints",
+      "Documentation frameworks optimized for large codebases",
+      "API documentation through strategic sampling only",
+      "MCP document summarizer integration for threshold management",
+      "Precise code referencing with line numbers without full retention",
+      "Sequential processing to prevent parallel memory accumulation",
+      "Forbidden practice enforcement (no parallel loads, no retention)"
     ],
     "best_practices": [
-      "Extract key patterns from 3-5 representative files maximum for documentation",
+      "ALWAYS check file size with LS before any Read operation",
+      "Extract key patterns from 3-5 representative files maximum",
       "Use grep with line numbers (-n) and adaptive context based on match count",
-      "Leverage MCP summarizer tool for files exceeding thresholds",
-      "Trigger summarization at 20KB or 200 lines for single files",
+      "Leverage MCP summarizer tool for ALL files exceeding thresholds",
+      "Trigger MANDATORY summarization at 20KB or 200 lines for single files",
       "Apply batch summarization after 3 files or 50KB cumulative content",
-      "Process files sequentially to prevent memory accumulation",
-      "Check file sizes before reading - auto-summarize >100KB files",
+      "Process files sequentially - NEVER in parallel",
+      "Auto-summarize >100KB files WITHOUT reading them",
+      "Skip or defer files >1MB entirely",
       "Reset cumulative counters after batch summarization",
-      "Extract and summarize patterns immediately, discard full file contents",
+      "Extract patterns and IMMEDIATELY discard full file contents",
+      "Use adaptive grep context: >50 matches (-A 2 -B 2 | head -50), <20 matches (-A 10 -B 10)",
+      "Process large files in <100 line chunks with immediate discard",
       "Create clear technical documentation with precise line references",
-      "Generate comprehensive API documentation from sampled patterns",
-      "Write user-friendly guides and tutorials",
-      "Maintain documentation consistency",
-      "Structure complex information effectively",
+      "Generate comprehensive API documentation from sampled patterns only",
+      "NEVER accumulate content across multiple file reads",
       "Always use grep -n for line number tracking in code references",
-      "Generate executive summaries when appropriate"
+      "Use targeted grep searches instead of full file reads",
+      "Implement progressive summarization for cumulative content management"
     ],
     "constraints": [
+      "❌ NEVER read entire large codebases",
+      "❌ NEVER load multiple files in parallel",
+      "❌ NEVER retain file contents after extraction",
+      "❌ NEVER load files >1MB into memory",
+      "❌ NEVER accumulate content across multiple file reads",
+      "❌ NEVER skip file size checks before reading",
+      "❌ NEVER process >5 files without summarization",
       "Process files sequentially to prevent memory accumulation",
       "Maximum 3-5 files for documentation analysis without summarization",
-      "Critical files >100KB must be summarized, never fully read",
-      "Single file threshold: 20KB or 200 lines triggers summarization",
+      "Critical files >100KB MUST be summarized, NEVER fully read",
+      "Single file threshold: 20KB or 200 lines triggers MANDATORY summarization",
       "Cumulative threshold: 50KB total or 3 files triggers batch summarization",
-      "Adaptive grep context: >50 matches use -A 2 -B 2 | head -50",
-      "Content must be discarded after extraction",
-      "Never retain full file contents in memory",
+      "Adaptive grep context: >50 matches use -A 2 -B 2 | head -50, <20 matches use -A 10 -B 10",
+      "Content MUST be discarded IMMEDIATELY after extraction",
+      "File size checking is MANDATORY before ALL Read operations",
       "Check MCP summarizer tool availability before use",
-      "Provide graceful fallback when MCP tool is not available",
       "Always include line numbers in code references",
-      "Sequential processing is mandatory for documentation generation"
+      "Implementation chunking: Process large files in <100 line segments",
+      "Sequential processing is MANDATORY for documentation generation"
     ],
     "examples": []
   },

claude_mpm/agents/templates/research.json

@@ -37,17 +37,6 @@
   },
   "capabilities": {
     "model": "opus",
-    "tools": [
-      "Read",
-      "Grep",
-      "Glob",
-      "LS",
-      "WebSearch",
-      "WebFetch",
-      "Bash",
-      "TodoWrite",
-      "mcp__claude-mpm-gateway__document_summarizer"
-    ],
     "resource_tier": "high",
     "temperature": 0.2,
     "max_tokens": 16384,

claude_mpm/cli/__init__.py

@@ -83,15 +83,26 @@ def main(argv: Optional[list] = None):
     # Initialize or update project registry
     _initialize_project_registry()
 
-    # Verify MCP Gateway configuration on startup (non-blocking)
-    _verify_mcp_gateway_startup()
-
-    # Create parser with version
+    # Parse args early to check if we should skip auto-configuration
+    # (for commands like --version, --help, etc.)
     parser = create_parser(version=__version__)
-
-    # Preprocess and parse arguments
     processed_argv = preprocess_args(argv)
     args = parser.parse_args(processed_argv)
+    
+    # Skip auto-configuration for certain commands
+    skip_auto_config_commands = ["--version", "-v", "--help", "-h"]
+    # sys is already imported at module level (line 16), use it directly
+    should_skip_auto_config = (
+        any(cmd in (processed_argv or sys.argv[1:]) for cmd in skip_auto_config_commands)
+        or (hasattr(args, 'command') and args.command in ["info", "doctor", "config", "mcp"])  # Info, diagnostic, and MCP commands
+    )
+    
+    if not should_skip_auto_config:
+        # Check for MCP auto-configuration (pipx installations)
+        _check_mcp_auto_configuration()
+
+    # Verify MCP Gateway configuration on startup (non-blocking)
+    _verify_mcp_gateway_startup()
 
     # Set up logging
     # Special case: For MCP start command, we need minimal logging to avoid stdout interference
@@ -101,7 +112,7 @@ def main(argv: Optional[list] = None):
     ):
         # For MCP server, configure minimal stderr-only logging
         import logging
-        import sys
+        # sys is already imported at module level
 
         # Only log errors to stderr for MCP server
         if not getattr(args, "test", False) and not getattr(
@@ -176,55 +187,122 @@ def _initialize_project_registry():
         # Continue execution - registry failure shouldn't block startup
 
 
+def _check_mcp_auto_configuration():
+    """
+    Check and potentially auto-configure MCP for pipx installations.
+    
+    WHY: Users installing via pipx should have MCP work out-of-the-box with
+    minimal friction. This function offers one-time auto-configuration with
+    user consent.
+    
+    DESIGN DECISION: This is blocking but quick - it only runs once and has
+    a 10-second timeout. We want to catch users on first run for the best
+    experience.
+    """
+    try:
+        from ..services.mcp_gateway.auto_configure import check_and_configure_mcp
+        
+        # This function handles all the logic:
+        # - Checks if already configured
+        # - Checks if pipx installation
+        # - Checks if already asked before
+        # - Prompts user if needed
+        # - Configures if user agrees
+        check_and_configure_mcp()
+        
+    except Exception as e:
+        # Non-critical - log but don't fail
+        from ..core.logger import get_logger
+        logger = get_logger("cli")
+        logger.debug(f"MCP auto-configuration check failed: {e}")
+
+
 def _verify_mcp_gateway_startup():
     """
-    Verify MCP Gateway configuration on startup.
+    Verify MCP Gateway configuration on startup and pre-warm MCP services.
 
     WHY: The MCP gateway should be automatically configured and verified on startup
     to provide a seamless experience with diagnostic tools, file summarizer, and
-    ticket service.
+    ticket service. Pre-warming MCP services eliminates the 11.9s delay on first use.
 
     DESIGN DECISION: This is non-blocking - failures are logged but don't prevent
     startup to ensure claude-mpm remains functional even if MCP gateway has issues.
     """
     try:
         import asyncio
+        import time
         from ..services.mcp_gateway.core.startup_verification import (
             verify_mcp_gateway_on_startup,
             is_mcp_gateway_configured,
         )
+        from ..services.mcp_gateway.core.process_pool import pre_warm_mcp_servers
+        from ..core.logger import get_logger
+        
+        logger = get_logger("mcp_prewarm")
 
         # Quick check first - if already configured, skip detailed verification
-        if is_mcp_gateway_configured():
-            return
-
-        # Run detailed verification in background
-        # Note: We don't await this to avoid blocking startup
-        def run_verification():
+        gateway_configured = is_mcp_gateway_configured()
+        
+        # Pre-warm MCP servers regardless of gateway config
+        # This eliminates the 11.9s delay on first agent invocation
+        def run_pre_warming():
             try:
+                start_time = time.time()
                 loop = asyncio.new_event_loop()
                 asyncio.set_event_loop(loop)
-                results = loop.run_until_complete(verify_mcp_gateway_on_startup())
+                
+                # Pre-warm MCP servers (especially vector search)
+                logger.info("Pre-warming MCP servers to eliminate startup delay...")
+                loop.run_until_complete(pre_warm_mcp_servers())
+                
+                pre_warm_time = time.time() - start_time
+                if pre_warm_time > 1.0:
+                    logger.info(f"MCP servers pre-warmed in {pre_warm_time:.2f}s")
+                
+                # Also run gateway verification if needed
+                if not gateway_configured:
+                    results = loop.run_until_complete(verify_mcp_gateway_on_startup())
+                
                 loop.close()
-
-                # Log results but don't block
-                from ..core.logger import get_logger
-                logger = get_logger("cli")
-
-                if results.get("gateway_configured"):
-                    logger.debug("MCP Gateway verification completed successfully")
-                else:
-                    logger.debug("MCP Gateway verification completed with warnings")
-
             except Exception as e:
-                from ..core.logger import get_logger
-                logger = get_logger("cli")
-                logger.debug(f"MCP Gateway verification failed: {e}")
-
-        # Run in background thread to avoid blocking startup
+                # Non-blocking - log but don't fail
+                logger.debug(f"MCP pre-warming error (non-critical): {e}")
+        
+        # Run pre-warming in background thread
         import threading
-        verification_thread = threading.Thread(target=run_verification, daemon=True)
-        verification_thread.start()
+        pre_warm_thread = threading.Thread(target=run_pre_warming, daemon=True)
+        pre_warm_thread.start()
+        
+        return
+
+        # Run detailed verification in background if not configured
+        if not gateway_configured:
+            # Note: We don't await this to avoid blocking startup
+            def run_verification():
+                try:
+                    loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(loop)
+                    results = loop.run_until_complete(verify_mcp_gateway_on_startup())
+                    loop.close()
+
+                    # Log results but don't block
+                    from ..core.logger import get_logger
+                    logger = get_logger("cli")
+
+                    if results.get("gateway_configured"):
+                        logger.debug("MCP Gateway verification completed successfully")
+                    else:
+                        logger.debug("MCP Gateway verification completed with warnings")
+
+                except Exception as e:
+                    from ..core.logger import get_logger
+                    logger = get_logger("cli")
+                    logger.debug(f"MCP Gateway verification failed: {e}")
+
+            # Run in background thread to avoid blocking startup
+            import threading
+            verification_thread = threading.Thread(target=run_verification, daemon=True)
+            verification_thread.start()
 
     except Exception as e:
         # Import logger here to avoid circular imports

claude_mpm/cli/commands/agent_manager.py

@@ -181,14 +181,15 @@ class AgentManagerCommand(AgentCommand):
         """Deploy an agent to specified tier."""
         try:
             agent_id = args.agent_id
-            tier = getattr(args, 'tier', 'user')
+            tier = getattr(args, 'tier', 'project')  # Default to project (changed from 'user')
             
-            # Determine deployment path
-            if tier == 'project':
-                deploy_path = Path.cwd() / ".claude" / "agents"
-            elif tier == 'user':
-                deploy_path = Path.home() / ".claude" / "agents"
-            else:
+            # Always deploy to project directory
+            # Regardless of tier, all agents go to project .claude/agents
+            deploy_path = Path.cwd() / ".claude" / "agents"
+            
+            # Note: We're keeping the tier parameter for backward compatibility
+            # but it no longer affects the deployment location
+            if tier not in ['project', 'user']:
                 return CommandResult.error_result("Invalid tier. Use 'project' or 'user'")
                 
             # Create directory if needed
@@ -203,7 +204,8 @@ class AgentManagerCommand(AgentCommand):
                 return CommandResult.error_result(f"Agent '{agent_id}' not found")
                 
             # Deploy using deployment service
-            self.deployment.deploy_agent(agent_id, str(deploy_path))
+            # Pass Path object, not string
+            self.deployment.deploy_agent(agent_id, deploy_path)
             
             return CommandResult.success_result(
                 f"Agent '{agent_id}' deployed to {tier} level"

claude_mpm/cli/commands/agents.py

@@ -71,6 +71,7 @@ class AgentsCommand(AgentCommand):
                 "deps-install": self._install_agent_dependencies,
                 "deps-list": self._list_agent_dependencies,
                 "deps-fix": self._fix_agent_dependencies,
+                "cleanup-orphaned": self._cleanup_orphaned_agents,
             }
 
             if args.agents_command in command_map:
@@ -469,6 +470,87 @@ class AgentsCommand(AgentCommand):
         except Exception as e:
             self.logger.error(f"Error fixing dependencies: {e}", exc_info=True)
             return CommandResult.error_result(f"Error fixing dependencies: {e}")
+    
+    def _cleanup_orphaned_agents(self, args) -> CommandResult:
+        """Clean up orphaned agents that don't have templates."""
+        try:
+            from ...services.agents.deployment.multi_source_deployment_service import (
+                MultiSourceAgentDeploymentService
+            )
+            
+            # Determine agents directory
+            if hasattr(args, 'agents_dir') and args.agents_dir:
+                agents_dir = args.agents_dir
+            else:
+                # Check for project-level .claude/agents first
+                project_agents_dir = Path.cwd() / ".claude" / "agents"
+                if project_agents_dir.exists():
+                    agents_dir = project_agents_dir
+                else:
+                    # Fall back to user home directory
+                    agents_dir = Path.home() / ".claude" / "agents"
+            
+            if not agents_dir.exists():
+                return CommandResult.success_result(f"Agents directory not found: {agents_dir}")
+            
+            # Initialize service
+            service = MultiSourceAgentDeploymentService()
+            
+            # Determine if we're doing a dry run
+            dry_run = getattr(args, 'dry_run', True)
+            if hasattr(args, 'force') and args.force:
+                dry_run = False
+            
+            # Perform cleanup
+            results = service.cleanup_orphaned_agents(agents_dir, dry_run=dry_run)
+            
+            output_format = getattr(args, 'format', 'text')
+            quiet = getattr(args, 'quiet', False)
+            
+            if output_format in ['json', 'yaml']:
+                return CommandResult.success_result(
+                    f"Found {len(results.get('orphaned', []))} orphaned agents",
+                    data=results
+                )
+            else:
+                # Text output
+                if not results.get("orphaned"):
+                    print("✅ No orphaned agents found")
+                    return CommandResult.success_result("No orphaned agents found")
+                
+                if not quiet:
+                    print(f"\nFound {len(results['orphaned'])} orphaned agent(s):")
+                    for orphan in results["orphaned"]:
+                        print(f"  - {orphan['name']} v{orphan['version']}")
+                
+                if dry_run:
+                    print(
+                        f"\n📝 This was a dry run. Use --force to actually remove "
+                        f"{len(results['orphaned'])} orphaned agent(s)"
+                    )
+                else:
+                    if results.get("removed"):
+                        print(
+                            f"\n✅ Successfully removed {len(results['removed'])} orphaned agent(s)"
+                        )
+                    
+                    if results.get("errors"):
+                        print(f"\n❌ Encountered {len(results['errors'])} error(s):")
+                        for error in results["errors"]:
+                            print(f"  - {error}")
+                        return CommandResult.error_result(
+                            f"Cleanup completed with {len(results['errors'])} errors",
+                            data=results
+                        )
+                
+                return CommandResult.success_result(
+                    f"Cleanup {'preview' if dry_run else 'completed'}",
+                    data=results
+                )
+                
+        except Exception as e:
+            self.logger.error(f"Error during cleanup: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error during cleanup: {e}")
 
 
 def manage_agents(args):