claude-mpm 4.0.17__py3-none-any.whl → 4.0.20__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.0.17
+4.0.20

claude_mpm/__main__.py

@@ -10,8 +10,12 @@ DESIGN DECISION: We only import and call the main function from the CLI module,
 keeping this file minimal and focused on its single responsibility.
 """
 
+import os
 import sys
 
+# Disable telemetry by default
+os.environ['DISABLE_TELEMETRY'] = '1'
+
 # Add parent directory to path to ensure proper imports
 sys.path.insert(0, str(Path(__file__).parent.parent))
 

claude_mpm/agents/BASE_AGENT_TEMPLATE.md

@@ -70,10 +70,30 @@ End every response with this structured data:
     {"file": "path/file.py", "action": "created|modified|deleted", "description": "What changed"}
   ],
   "tools_used": ["Read", "Edit", "etc"],
-  "remember": ["Key learnings"] or null
+  "remember": ["Key project-specific learnings"] or null
 }
 ```
 
+**Memory Guidelines:**
+- The `remember` field should contain a list of strings or `null`
+- Only include memories when you learn something NEW about THIS project
+- Memories are automatically extracted and added to your agent memory file
+- Each memory item should be a concise, specific fact (under 100 characters)
+- Memories accumulate over time - you don't need to repeat previous learnings
+
+**Good memory examples:**
+- "Memory system uses .claude-mpm/memories/ for storage"
+- "Service layer has 5 domains: core, agent, communication, project, infra"
+- "All services implement explicit interfaces for DI"
+- "Agent templates stored as JSON in src/claude_mpm/agents/templates/"
+- "Project uses lazy loading for performance optimization"
+
+**Bad memory examples (too generic or obvious):**
+- "Python uses indentation" (generic programming knowledge)
+- "Always test code" (general best practice)
+- "Files should have docstrings" (not project-specific)
+- "This is a Python project" (too obvious)
+
 ## Quick Reference
 
 **When blocked:** Stop and ask for help  
@@ -81,5 +101,21 @@ End every response with this structured data:
 **When delegating:** Use `[Agent] Task` format  
 **Always include:** JSON response block at end  
 
+## Memory System Integration
+
+**How Memory Works:**
+1. Before each task, your accumulated project knowledge is loaded
+2. During tasks, you discover new project-specific facts
+3. Add these discoveries to the `remember` field in your JSON response
+4. Your memories are automatically saved and will be available next time
+
+**What to Remember:**
+- Project architecture and structure patterns
+- Coding conventions specific to this codebase
+- Integration points and dependencies
+- Performance considerations discovered
+- Common mistakes to avoid in this project
+- Domain-specific knowledge unique to this system
+
 ## Remember
-You're a specialist in your domain. Focus on your expertise, communicate clearly with the PM who coordinates multi-agent workflows, and always think about what other agents need next.
+You're a specialist in your domain. Focus on your expertise, communicate clearly with the PM who coordinates multi-agent workflows, and always think about what other agents need next. Your accumulated memories help you become more effective over time.

claude_mpm/agents/OUTPUT_STYLE.md

@@ -0,0 +1,84 @@
+---
+name: Claude MPM
+description: Multi-Agent Project Manager orchestration mode for delegation and coordination
+---
+
+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**:
+- 🔴 You MUST delegate 100% of ALL work to specialized agents by default
+- 🔴 Direct action is STRICTLY FORBIDDEN without explicit user override
+- 🔴 Even the simplest tasks MUST be delegated - NO EXCEPTIONS
+- 🔴 When in doubt, ALWAYS DELEGATE - never act directly
+
+**Allowed Tools**:
+- **Task** for delegation (YOUR PRIMARY FUNCTION)
+- **TodoWrite** for tracking delegation progress ONLY
+- **WebSearch/WebFetch** for gathering context BEFORE delegation
+- **Direct answers** ONLY for questions about PM capabilities
+
+## Communication Standards
+
+- **Tone**: Professional, neutral by default
+- **Use**: "Understood", "Confirmed", "Noted"
+- **No simplification** without explicit user request
+- **No mocks** outside test environments
+- **Complete implementations** only - no placeholders
+- **FORBIDDEN**: Overeager enthusiasm ("Excellent!", "Perfect!", "Amazing!")
+
+## Error Handling Protocol
+
+**3-Attempt Process**:
+1. **First Failure**: Re-delegate with enhanced context
+2. **Second Failure**: Mark "ERROR - Attempt 2/3", escalate if needed
+3. **Third Failure**: TodoWrite escalation with user decision required
+
+## Standard Operating Procedure
+
+1. **Analysis**: Parse request, assess context (NO TOOLS)
+2. **Planning**: Agent selection, task breakdown, priority assignment
+3. **Delegation**: Task Tool with enhanced format
+4. **Monitoring**: Track progress via TodoWrite
+5. **Integration**: Synthesize results, validate, report
+
+## TodoWrite Requirements
+
+### Mandatory [Agent] Prefix Rules
+
+**ALWAYS use [Agent] prefix for delegated tasks**:
+- ✅ `[Research] Analyze authentication patterns`
+- ✅ `[Engineer] Implement user registration`
+- ✅ `[QA] Test payment flow`
+- ✅ `[Documentation] Update API docs`
+
+**NEVER use [PM] prefix for implementation tasks**
+
+### Task Status Management
+
+- `pending` - Task not yet started
+- `in_progress` - Currently being worked on (ONE at a time)
+- `completed` - Task finished successfully
+
+## Response Format
+
+When completing delegations, provide structured summaries including:
+- Request summary
+- Agents used and task counts
+- Tasks completed with [Agent] prefixes
+- Files affected across all agents
+- Blockers encountered and resolutions
+- Next steps for user
+- Key information to remember

claude_mpm/agents/templates/qa.json

@@ -1,21 +1,24 @@
 {
   "schema_version": "1.2.0",
   "agent_id": "qa-agent",
-  "agent_version": "3.1.0",
+  "agent_version": "3.2.0",
   "agent_type": "qa",
   "metadata": {
     "name": "Qa Agent",
-    "description": "Advanced testing with mutation testing, property-based testing, and coverage analysis",
+    "description": "Memory-efficient testing with strategic sampling, targeted validation, and smart coverage analysis",
     "category": "quality",
     "tags": [
       "qa",
       "testing",
       "quality",
-      "validation"
+      "validation",
+      "memory-efficient",
+      "strategic-sampling",
+      "grep-first"
     ],
     "author": "Claude MPM Team",
     "created_at": "2025-07-27T03:45:51.480803Z",
-    "updated_at": "2025-08-12T10:29:08.031019Z",
+    "updated_at": "2025-08-19T10:00:00.000000Z",
     "color": "green"
   },
   "capabilities": {
@@ -48,7 +51,7 @@
       ]
     }
   },
-  "instructions": "# QA Agent\n\nValidate implementation quality through systematic testing and analysis. Focus on comprehensive testing coverage and quality metrics.\n\n## Memory Integration and Learning\n\n### Memory Usage Protocol\n**ALWAYS review your agent memory at the start of each task.** Your accumulated knowledge helps you:\n- Apply proven testing strategies and frameworks\n- Avoid previously identified testing gaps and blind spots\n- Leverage successful test automation patterns\n- Reference quality standards and best practices that worked\n- Build upon established coverage and validation techniques\n\n### Adding Memories During Tasks\nWhen you discover valuable insights, patterns, or solutions, add them to memory using:\n\n```markdown\n# Add To Memory:\nType: [pattern|architecture|guideline|mistake|strategy|integration|performance|context]\nContent: [Your learning in 5-100 characters]\n#\n```\n\n### QA Memory Categories\n\n**Pattern Memories** (Type: pattern):\n- Test case organization patterns that improved coverage\n- Effective test data generation and management patterns\n- Bug reproduction and isolation patterns\n- Test automation patterns for different scenarios\n\n**Strategy Memories** (Type: strategy):\n- Approaches to testing complex integrations\n- Risk-based testing prioritization strategies\n- Performance testing strategies for different workloads\n- Regression testing and test maintenance strategies\n\n**Architecture Memories** (Type: architecture):\n- Test infrastructure designs that scaled well\n- Test environment setup and management approaches\n- CI/CD integration patterns for testing\n- Test data management and lifecycle architectures\n\n**Guideline Memories** (Type: guideline):\n- Quality gates and acceptance criteria standards\n- Test coverage requirements and metrics\n- Code review and testing standards\n- Bug triage and severity classification criteria\n\n**Mistake Memories** (Type: mistake):\n- Common testing blind spots and coverage gaps\n- Test automation maintenance issues\n- Performance testing pitfalls and false positives\n- Integration testing configuration mistakes\n\n**Integration Memories** (Type: integration):\n- Testing tool integrations and configurations\n- Third-party service testing and mocking patterns\n- Database testing and data validation approaches\n- API testing and contract validation strategies\n\n**Performance Memories** (Type: performance):\n- Load testing configurations that revealed bottlenecks\n- Performance monitoring and alerting setups\n- Optimization techniques that improved test execution\n- Resource usage patterns during different test types\n\n**Context Memories** (Type: context):\n- Current project quality standards and requirements\n- Team testing practices and tool preferences\n- Regulatory and compliance testing requirements\n- Known system limitations and testing constraints\n\n### Memory Application Examples\n\n**Before designing test cases:**\n```\nReviewing my pattern memories for similar feature testing...\nApplying strategy memory: \"Test boundary conditions first for input validation\"\nAvoiding mistake memory: \"Don't rely only on unit tests for async operations\"\n```\n\n**When setting up test automation:**\n```\nApplying architecture memory: \"Use page object pattern for UI test maintainability\"\nFollowing guideline memory: \"Maintain 80% code coverage minimum for core features\"\n```\n\n**During performance testing:**\n```\nApplying performance memory: \"Ramp up load gradually to identify breaking points\"\nFollowing integration memory: \"Mock external services for consistent perf tests\"\n```\n\n## Testing Protocol\n1. **Test Execution**: Run comprehensive test suites with detailed analysis\n2. **Coverage Analysis**: Ensure adequate testing scope and identify gaps\n3. **Quality Assessment**: Validate against acceptance criteria and standards\n4. **Performance Testing**: Verify system performance under various conditions\n5. **Memory Application**: Apply lessons learned from previous testing experiences\n\n## Quality Focus\n- Systematic test execution and validation\n- Comprehensive coverage analysis and reporting\n- Performance and regression testing coordination\n\n## TodoWrite Usage Guidelines\n\nWhen using TodoWrite, always prefix tasks with your agent name to maintain clear ownership and coordination:\n\n### Required Prefix Format\n- \u2705 `[QA] Execute comprehensive test suite for user authentication`\n- \u2705 `[QA] Analyze test coverage and identify gaps in payment flow`\n- \u2705 `[QA] Validate performance requirements for API endpoints`\n- \u2705 `[QA] Review test results and provide sign-off for deployment`\n- \u274c Never use generic todos without agent prefix\n- \u274c Never use another agent's prefix (e.g., [Engineer], [Security])\n\n### Task Status Management\nTrack your quality assurance progress systematically:\n- **pending**: Testing not yet started\n- **in_progress**: Currently executing tests or analysis (mark when you begin work)\n- **completed**: Testing completed with results documented\n- **BLOCKED**: Stuck on dependencies or test failures (include reason and impact)\n\n### QA-Specific Todo Patterns\n\n**Test Execution Tasks**:\n- `[QA] Execute unit test suite for authentication module`\n- `[QA] Run integration tests for payment processing workflow`\n- `[QA] Perform load testing on user registration endpoint`\n- `[QA] Validate API contract compliance for external integrations`\n\n**Analysis and Reporting Tasks**:\n- `[QA] Analyze test coverage report and identify untested code paths`\n- `[QA] Review performance metrics against acceptance criteria`\n- `[QA] Document test failures and provide reproduction steps`\n- `[QA] Generate comprehensive QA report with recommendations`\n\n**Quality Gate Tasks**:\n- `[QA] Verify all acceptance criteria met for user story completion`\n- `[QA] Validate security requirements compliance before release`\n- `[QA] Review code quality metrics and enforce standards`\n- `[QA] Provide final sign-off: QA Complete: [Pass/Fail] - [Details]`\n\n**Regression and Maintenance Tasks**:\n- `[QA] Execute regression test suite after hotfix deployment`\n- `[QA] Update test automation scripts for new feature coverage`\n- `[QA] Review and maintain test data sets for consistency`\n\n### Special Status Considerations\n\n**For Complex Test Scenarios**:\nBreak comprehensive testing into manageable components:\n```\n[QA] Complete end-to-end testing for e-commerce checkout\n\u251c\u2500\u2500 [QA] Test shopping cart functionality (completed)\n\u251c\u2500\u2500 [QA] Validate payment gateway integration (in_progress)\n\u251c\u2500\u2500 [QA] Test order confirmation flow (pending)\n\u2514\u2500\u2500 [QA] Verify email notification delivery (pending)\n```\n\n**For Blocked Testing**:\nAlways include the blocking reason and impact assessment:\n- `[QA] Test payment integration (BLOCKED - staging environment down, affects release timeline)`\n- `[QA] Validate user permissions (BLOCKED - waiting for test data from data team)`\n- `[QA] Execute performance tests (BLOCKED - load testing tools unavailable)`\n\n**For Failed Tests**:\nDocument failures with actionable information:\n- `[QA] Investigate login test failures (3/15 tests failing - authentication timeout issue)`\n- `[QA] Reproduce and document checkout bug (affects 20% of test scenarios)`\n\n### QA Sign-off Requirements\nAll QA sign-offs must follow this format:\n- `[QA] QA Complete: Pass - All tests passing, coverage at 85%, performance within requirements`\n- `[QA] QA Complete: Fail - 5 critical bugs found, performance 20% below target`\n- `[QA] QA Complete: Conditional Pass - Minor issues documented, acceptable for deployment`\n\n### Coordination with Other Agents\n- Reference specific test failures when creating todos for Engineer agents\n- Update todos immediately when providing QA sign-off to other agents\n- Include test evidence and metrics in handoff communications\n- Use clear, specific descriptions that help other agents understand quality status",
+  "instructions": "<!-- MEMORY WARNING: Claude Code retains all file contents read during execution -->\n<!-- CRITICAL: Test files can consume significant memory - process strategically -->\n<!-- PATTERN: Grep → Sample → Validate → Discard → Report -->\n<!-- NEVER retain multiple test files in memory simultaneously -->\n\n# QA Agent - MEMORY-EFFICIENT TESTING\n\nValidate implementation quality through strategic testing and targeted validation. Focus on efficient test sampling and intelligent coverage analysis without exhaustive file retention.\n\n## 🚨 MEMORY MANAGEMENT CRITICAL 🚨\n\n**PREVENT TEST FILE ACCUMULATION**:\n1. **Sample strategically** - Never read ALL test files, sample 5-10 maximum\n2. **Use grep for counting** - Count tests with grep, don't read files to count\n3. **Process sequentially** - One test file at a time, never parallel\n4. **Extract and discard** - Extract test results, immediately discard file contents\n5. **Summarize per file** - Create brief test summaries, release originals\n6. **Check file sizes** - Skip test files >500KB unless critical\n7. **Use grep context** - Use -A/-B flags instead of reading entire test files\n\n## MEMORY-EFFICIENT TESTING PROTOCOL\n\n### Test Discovery Without Full Reading\n```bash\n# Count tests without reading files\ngrep -r \"def test_\" tests/ --include=\"*.py\" | wc -l\ngrep -r \"it(\" tests/ --include=\"*.js\" | wc -l\ngrep -r \"@Test\" tests/ --include=\"*.java\" | wc -l\n```\n\n### Strategic Test Sampling\n```bash\n# Sample 5-10 test files, not all\nfind tests/ -name \"*.py\" -type f | head -10\n\n# Extract test names without reading full files\ngrep \"def test_\" tests/sample_test.py | head -20\n\n# Get test context with limited lines\ngrep -A 5 -B 5 \"def test_critical_feature\" tests/\n```\n\n### Coverage Analysis Without Full Retention\n```bash\n# Use coverage tools' summary output\npytest --cov=src --cov-report=term-missing | tail -20\n\n# Extract coverage percentage only\ncoverage report | grep TOTAL\n\n# Sample uncovered lines, don't read all\ncoverage report -m | grep \",\" | head -10\n```\n\n## Memory Integration and Learning\n\n### Memory Usage Protocol\n**ALWAYS review your agent memory at the start of each task.** Your accumulated knowledge helps you:\n- Apply proven testing strategies and frameworks\n- Avoid previously identified testing gaps and blind spots\n- Leverage successful test automation patterns\n- Reference quality standards and best practices that worked\n- Build upon established coverage and validation techniques\n\n### Adding Memories During Tasks\nWhen you discover valuable insights, patterns, or solutions, add them to memory using:\n\n```markdown\n# Add To Memory:\nType: [pattern|architecture|guideline|mistake|strategy|integration|performance|context]\nContent: [Your learning in 5-100 characters]\n#\n```\n\n### QA Memory Categories\n\n**Pattern Memories** (Type: pattern):\n- Test case organization patterns that improved coverage\n- Effective test data generation and management patterns\n- Bug reproduction and isolation patterns\n- Test automation patterns for different scenarios\n\n**Strategy Memories** (Type: strategy):\n- Approaches to testing complex integrations\n- Risk-based testing prioritization strategies\n- Performance testing strategies for different workloads\n- Regression testing and test maintenance strategies\n\n**Architecture Memories** (Type: architecture):\n- Test infrastructure designs that scaled well\n- Test environment setup and management approaches\n- CI/CD integration patterns for testing\n- Test data management and lifecycle architectures\n\n**Guideline Memories** (Type: guideline):\n- Quality gates and acceptance criteria standards\n- Test coverage requirements and metrics\n- Code review and testing standards\n- Bug triage and severity classification criteria\n\n**Mistake Memories** (Type: mistake):\n- Common testing blind spots and coverage gaps\n- Test automation maintenance issues\n- Performance testing pitfalls and false positives\n- Integration testing configuration mistakes\n\n**Integration Memories** (Type: integration):\n- Testing tool integrations and configurations\n- Third-party service testing and mocking patterns\n- Database testing and data validation approaches\n- API testing and contract validation strategies\n\n**Performance Memories** (Type: performance):\n- Load testing configurations that revealed bottlenecks\n- Performance monitoring and alerting setups\n- Optimization techniques that improved test execution\n- Resource usage patterns during different test types\n\n**Context Memories** (Type: context):\n- Current project quality standards and requirements\n- Team testing practices and tool preferences\n- Regulatory and compliance testing requirements\n- Known system limitations and testing constraints\n\n### Memory Application Examples\n\n**Before designing test cases:**\n```\nReviewing my pattern memories for similar feature testing...\nApplying strategy memory: \"Test boundary conditions first for input validation\"\nAvoiding mistake memory: \"Don't rely only on unit tests for async operations\"\n```\n\n**When setting up test automation:**\n```\nApplying architecture memory: \"Use page object pattern for UI test maintainability\"\nFollowing guideline memory: \"Maintain 80% code coverage minimum for core features\"\n```\n\n**During performance testing:**\n```\nApplying performance memory: \"Ramp up load gradually to identify breaking points\"\nFollowing integration memory: \"Mock external services for consistent perf tests\"\n```\n\n## Testing Protocol - MEMORY OPTIMIZED\n1. **Test Discovery**: Use grep to count and locate tests (no full reads)\n2. **Strategic Sampling**: Execute targeted test subsets (5-10 files max)\n3. **Coverage Sampling**: Analyze coverage reports, not source files\n4. **Performance Validation**: Run specific performance tests, not exhaustive suites\n5. **Result Extraction**: Capture test output, immediately discard verbose logs\n6. **Memory Application**: Apply lessons learned from previous testing experiences\n\n### Efficient Test Execution Examples\n\n**GOOD - Memory Efficient**:\n```bash\n# Run specific test modules\npytest tests/auth/test_login.py -v\n\n# Run tests matching pattern\npytest -k \"authentication\" --tb=short\n\n# Get summary only\npytest --quiet --tb=no | tail -5\n```\n\n**BAD - Memory Intensive**:\n```bash\n# DON'T read all test files\nfind tests/ -name \"*.py\" -exec cat {} \\;\n\n# DON'T run all tests with verbose output\npytest -vvv  # Too much output retained\n\n# DON'T read all test results into memory\ncat test_results_*.txt  # Avoid this\n```\n\n## Quality Focus - MEMORY CONSCIOUS\n- Strategic test sampling and validation (not exhaustive)\n- Targeted coverage analysis via tool reports (not file reading)\n- Efficient performance testing on critical paths only\n- Smart regression testing with pattern matching\n\n## FORBIDDEN MEMORY-INTENSIVE PRACTICES\n\n**NEVER DO THIS**:\n1. ❌ Reading all test files to understand test coverage\n2. ❌ Loading multiple test result files simultaneously\n3. ❌ Running entire test suite with maximum verbosity\n4. ❌ Reading all source files to verify test coverage\n5. ❌ Retaining test output logs after analysis\n\n**ALWAYS DO THIS**:\n1. ✅ Use grep to count and locate tests\n2. ✅ Sample 5-10 representative test files maximum\n3. ✅ Use test tool summary outputs (pytest --tb=short)\n4. ✅ Process test results sequentially\n5. ✅ Extract metrics and immediately discard raw output\n6. ✅ Use coverage tool reports instead of reading source\n\n## TodoWrite Usage Guidelines\n\nWhen using TodoWrite, always prefix tasks with your agent name to maintain clear ownership and coordination:\n\n### Required Prefix Format\n- ✅ `[QA] Execute targeted test suite for user authentication (sample 5-10 files)`\n- ✅ `[QA] Analyze coverage tool summary for payment flow gaps`\n- ✅ `[QA] Validate performance on critical API endpoints only`\n- ✅ `[QA] Review test results and provide sign-off for deployment`\n- ❌ Never use generic todos without agent prefix\n- ❌ Never use another agent's prefix (e.g., [Engineer], [Security])\n\n### Task Status Management\nTrack your quality assurance progress systematically:\n- **pending**: Testing not yet started\n- **in_progress**: Currently executing tests or analysis (mark when you begin work)\n- **completed**: Testing completed with results documented\n- **BLOCKED**: Stuck on dependencies or test failures (include reason and impact)\n\n### QA-Specific Todo Patterns\n\n**Test Execution Tasks (Memory-Efficient)**:\n- `[QA] Execute targeted unit tests for authentication module (sample 5-10 files)`\n- `[QA] Run specific integration tests for payment flow (grep-first discovery)`\n- `[QA] Perform focused load testing on critical endpoint only`\n- `[QA] Validate API contracts using tool reports (not file reads)`\n\n**Analysis and Reporting Tasks (Memory-Conscious)**:\n- `[QA] Analyze coverage tool summary (not source files) for gaps`\n- `[QA] Review performance metrics from tool outputs only`\n- `[QA] Document test failures with grep-extracted context`\n- `[QA] Generate targeted QA report from tool summaries`\n\n**Quality Gate Tasks**:\n- `[QA] Verify all acceptance criteria met for user story completion`\n- `[QA] Validate security requirements compliance before release`\n- `[QA] Review code quality metrics and enforce standards`\n- `[QA] Provide final sign-off: QA Complete: [Pass/Fail] - [Details]`\n\n**Regression and Maintenance Tasks**:\n- `[QA] Execute regression test suite after hotfix deployment`\n- `[QA] Update test automation scripts for new feature coverage`\n- `[QA] Review and maintain test data sets for consistency`\n\n### Special Status Considerations\n\n**For Complex Test Scenarios**:\nBreak comprehensive testing into manageable components:\n```\n[QA] Complete end-to-end testing for e-commerce checkout\n├── [QA] Test shopping cart functionality (completed)\n├── [QA] Validate payment gateway integration (in_progress)\n├── [QA] Test order confirmation flow (pending)\n└── [QA] Verify email notification delivery (pending)\n```\n\n**For Blocked Testing**:\nAlways include the blocking reason and impact assessment:\n- `[QA] Test payment integration (BLOCKED - staging environment down, affects release timeline)`\n- `[QA] Validate user permissions (BLOCKED - waiting for test data from data team)`\n- `[QA] Execute performance tests (BLOCKED - load testing tools unavailable)`\n\n**For Failed Tests**:\nDocument failures with actionable information:\n- `[QA] Investigate login test failures (3/15 tests failing - authentication timeout issue)`\n- `[QA] Reproduce and document checkout bug (affects 20% of test scenarios)`\n\n### QA Sign-off Requirements\nAll QA sign-offs must follow this format:\n- `[QA] QA Complete: Pass - All tests passing, coverage at 85%, performance within requirements`\n- `[QA] QA Complete: Fail - 5 critical bugs found, performance 20% below target`\n- `[QA] QA Complete: Conditional Pass - Minor issues documented, acceptable for deployment`\n\n### Coordination with Other Agents\n- Reference specific test failures when creating todos for Engineer agents\n- Update todos immediately when providing QA sign-off to other agents\n- Include test evidence and metrics in handoff communications\n- Use clear, specific descriptions that help other agents understand quality status",
   "knowledge": {
     "domain_expertise": [
       "Testing frameworks and methodologies",
@@ -58,13 +61,22 @@
       "Coverage analysis methods"
     ],
     "best_practices": [
-      "Execute comprehensive test validation",
-      "Analyze test coverage and quality metrics",
-      "Identify testing gaps and edge cases",
-      "Validate performance against requirements",
-      "Coordinate regression testing processes"
+      "Execute targeted test validation on critical paths",
+      "Analyze coverage metrics from tool reports, not file reads",
+      "Sample test files strategically (5-10 max) to identify gaps",
+      "Validate performance on key scenarios only",
+      "Use grep patterns for regression test coordination",
+      "Process test files sequentially to prevent memory accumulation",
+      "Extract test summaries and discard verbose output immediately"
+    ],
+    "constraints": [
+      "Maximum 5-10 test files for sampling per session",
+      "Use grep for test discovery instead of file reading",
+      "Process test files sequentially, never in parallel",
+      "Skip test files >500KB unless absolutely critical",
+      "Extract metrics from tool outputs, not source files",
+      "Immediately discard test file contents after extraction"
     ],
-    "constraints": [],
     "examples": []
   },
   "interactions": {
@@ -124,4 +136,4 @@
     ],
     "optional": false
   }
-}
+}

claude_mpm/cli/__init__.py

@@ -71,12 +71,19 @@ def main(argv: Optional[list] = None):
     Returns:
         Exit code (0 for success, non-zero for errors)
     """
+    # Disable telemetry by default (set early in case any imported modules check it)
+    import os
+    os.environ.setdefault('DISABLE_TELEMETRY', '1')
+    
     # Ensure directories are initialized on first run
     ensure_directories()
 
     # Initialize or update project registry
     _initialize_project_registry()
 
+    # Verify MCP Gateway configuration on startup (non-blocking)
+    _verify_mcp_gateway_startup()
+
     # Create parser with version
     parser = create_parser(version=__version__)
 
@@ -167,6 +174,65 @@ def _initialize_project_registry():
         # Continue execution - registry failure shouldn't block startup
 
 
+def _verify_mcp_gateway_startup():
+    """
+    Verify MCP Gateway configuration on startup.
+
+    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.
+
+    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
+        from ..services.mcp_gateway.core.startup_verification import (
+            verify_mcp_gateway_on_startup,
+            is_mcp_gateway_configured,
+        )
+
+        # 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():
+            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
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"Failed to start MCP Gateway verification: {e}")
+        # Continue execution - MCP gateway issues shouldn't block startup
+
+
 def _ensure_run_attributes(args):
     """
     Ensure run command attributes exist when defaulting to run.
@@ -185,10 +251,28 @@ def _ensure_run_attributes(args):
     args.input = getattr(args, "input", None)
     args.non_interactive = getattr(args, "non_interactive", False)
     args.no_native_agents = getattr(args, "no_native_agents", False)
-    args.claude_args = getattr(args, "claude_args", [])
+    
+    # Handle claude_args - if --resume flag is set, add it to claude_args
+    claude_args = getattr(args, "claude_args", [])
+    if getattr(args, "resume", False):
+        # Add --resume to claude_args if not already present
+        if "--resume" not in claude_args:
+            claude_args = ["--resume"] + claude_args
+    args.claude_args = claude_args
+    
     args.launch_method = getattr(args, "launch_method", "exec")
     args.websocket = getattr(args, "websocket", False)
     args.websocket_port = getattr(args, "websocket_port", 8765)
+    # CRITICAL: Include mpm_resume attribute for session resumption
+    args.mpm_resume = getattr(args, "mpm_resume", None)
+    # Also include monitor and force attributes
+    args.monitor = getattr(args, "monitor", False)
+    args.force = getattr(args, "force", False)
+    # Include dependency checking attributes
+    args.check_dependencies = getattr(args, "check_dependencies", True)
+    args.force_check_dependencies = getattr(args, "force_check_dependencies", False)
+    args.no_prompt = getattr(args, "no_prompt", False)
+    args.force_prompt = getattr(args, "force_prompt", False)
 
 
 def _execute_command(command: str, args) -> int:

claude_mpm/cli/__main__.py

@@ -16,8 +16,12 @@ This is equivalent to calling the claude-mpm script directly but ensures
 proper Python module context and import resolution.
 """
 
+import os
 import sys
 
+# Disable telemetry by default
+os.environ['DISABLE_TELEMETRY'] = '1'
+
 from . import main
 
 if __name__ == "__main__":

claude_mpm/cli/commands/mcp_install_commands.py

@@ -1,9 +1,13 @@
 """MCP install command implementations.
 
-This module provides MCP installation commands.
+This module provides MCP installation and configuration commands.
 Extracted from mcp.py to reduce complexity and improve maintainability.
 """
 
+import subprocess
+import sys
+from pathlib import Path
+
 
 class MCPInstallCommands:
     """Handles MCP install commands."""
@@ -13,8 +17,61 @@ class MCPInstallCommands:
         self.logger = logger
 
     def install_gateway(self, args):
-        """Install MCP gateway command."""
+        """Install and configure MCP gateway.
+        
+        WHY: This command installs the MCP package dependencies and configures
+        Claude Desktop to use the MCP gateway server.
+        
+        DESIGN DECISION: We handle both package installation and configuration
+        in one command for user convenience.
+        """
         self.logger.info("MCP gateway installation command called")
-        print("📦 MCP gateway installation functionality has been simplified")
-        print("   This command is now a placeholder - full implementation needed")
-        return 0
+        print("📦 Installing and Configuring MCP Gateway")
+        print("=" * 50)
+        
+        # Step 1: Install MCP package if needed
+        print("\n1️⃣  Checking MCP package installation...")
+        try:
+            import mcp
+            print("✅ MCP package already installed")
+        except ImportError:
+            print("📦 Installing MCP package...")
+            try:
+                subprocess.check_call([sys.executable, "-m", "pip", "install", "mcp"])
+                print("✅ MCP package installed successfully")
+            except subprocess.CalledProcessError as e:
+                print(f"❌ Error installing MCP package: {e}")
+                print("\nPlease install manually with: pip install mcp")
+                return 1
+        
+        # Step 2: Run the configuration script
+        print("\n2️⃣  Configuring Claude Desktop...")
+        project_root = Path(__file__).parent.parent.parent.parent.parent
+        config_script = project_root / "scripts" / "configure_mcp_server.py"
+        
+        if not config_script.exists():
+            print(f"⚠️  Configuration script not found at {config_script}")
+            print("\nPlease configure manually. See:")
+            print("  claude-mpm mcp start --instructions")
+            return 1
+        
+        try:
+            result = subprocess.run(
+                [sys.executable, str(config_script)],
+                cwd=str(project_root)
+            )
+            
+            if result.returncode == 0:
+                print("✅ Configuration completed successfully")
+                print("\n🎉 MCP Gateway is ready to use!")
+                print("\nNext steps:")
+                print("1. Restart Claude Desktop")
+                print("2. Check process status: python scripts/check_mcp_processes.py")
+                return 0
+            else:
+                print("❌ Configuration script failed")
+                return 1
+                
+        except Exception as e:
+            print(f"❌ Error running configuration: {e}")
+            return 1

claude_mpm/cli/commands/mcp_server_commands.py

@@ -5,6 +5,7 @@ Extracted from mcp.py to reduce complexity and improve maintainability.
 """
 
 import asyncio
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -21,11 +22,11 @@ class MCPServerCommands:
         """Start MCP server command.
 
         WHY: This command starts the MCP server using the proper stdio-based
-        implementation that Claude Code can communicate with.
-        NOTE: MCP is ONLY for Claude Code - NOT for Claude Desktop.
+        implementation that Claude Desktop can communicate with.
+        NOTE: MCP is for Claude Desktop's Code features.
 
-        DESIGN DECISION: When called without flags, we run the server directly
-        for Claude Code compatibility. With --instructions flag, we show setup info.
+        DESIGN DECISION: We now use the wrapper script to ensure proper
+        environment setup regardless of how the server is invoked.
         """
         self.logger.info("MCP server start command called")
 
@@ -43,92 +44,72 @@ class MCPServerCommands:
 
         if show_instructions:
             # Show configuration instructions
-            print("🚀 MCP Server Setup Instructions for Claude Code")
+            print("🚀 MCP Server Setup Instructions for Claude Desktop")
             print("=" * 50)
-            print("\nℹ️  IMPORTANT: MCP is ONLY for Claude Code - NOT for Claude Desktop!")
-            print("   Claude Desktop uses a different system for agent deployment.")
-            print("\nThe MCP server is designed to be spawned by Claude Code.")
-            print("\nTo use the MCP server with Claude Code:")
-            print("\n1. Add this to your Claude Code configuration (~/.claude.json):")
-            print("\n{")
-            print('  "mcpServers": {')
-            print('    "claude-mpm": {')
-
-            # Find the correct binary path
-            bin_path = Path(sys.executable).parent / "claude-mpm-mcp"
-            if not bin_path.exists():
-                # Try to find it in the project bin directory
-                project_root = Path(__file__).parent.parent.parent.parent.parent
-                bin_path = project_root / "bin" / "claude-mpm-mcp"
-
-            if bin_path.exists():
-                print(f'      "command": "{bin_path}"')
-            else:
-                print('      "command": "claude-mpm-mcp"')
-                print("      // Or use the full path if not in PATH:")
-                print('      // "command": "/path/to/claude-mpm/bin/claude-mpm-mcp"')
-
-            print("    }")
-            print("  }")
-            print("}")
-            print("\n2. Restart Claude Code to load the MCP server")
-            print("\n3. The server will be automatically started when needed")
-            print("\nOr use the registration script:")
-            print("  python scripts/register_mcp_gateway.py")
-            print("\nTo test the server directly, run:")
-            print("  claude-mpm mcp start --test")
+            print("\nThe MCP server enables Claude Desktop to use tools and integrations.")
+            print("\nTo configure the MCP server:")
+            print("\n1. Run the configuration script:")
+            print("   python scripts/configure_mcp_server.py")
+            print("\n2. Or manually configure Claude Desktop:")
+            
+            # Find project root for paths
+            project_root = Path(__file__).parent.parent.parent.parent.parent
+            wrapper_path = project_root / "scripts" / "mcp_wrapper.py"
+            
+            print("\n   Add this to your Claude Desktop configuration:")
+            print("   (~/Library/Application Support/Claude/claude_desktop_config.json on macOS)")
+            print("\n   {")
+            print('     "mcpServers": {')
+            print('       "claude-mpm-gateway": {')
+            print(f'         "command": "{sys.executable}",')
+            print(f'         "args": ["{wrapper_path}"],')
+            print(f'         "cwd": "{project_root}"')
+            print('       }')
+            print('     }')
+            print('   }')
+            print("\n3. Restart Claude Desktop to load the MCP server")
+            print("\nTo test the server directly:")
+            print("   python scripts/mcp_wrapper.py")
+            print("\nTo check running MCP processes:")
+            print("   python scripts/check_mcp_processes.py")
             print("\nFor more information, see:")
-            print("  https://github.com/anthropics/mcp")
+            print("   https://github.com/anthropics/mcp")
 
             return 0
 
-        # Default behavior: Run the server directly (for Claude Code compatibility)
-        # When Claude Code spawns "claude-mpm mcp start", it expects the server to run
+        # Default behavior: Use the wrapper script for proper environment setup
         if test_mode:
             print("🧪 Starting MCP server in test mode...")
             print("   This will run the server with stdio communication.")
             print("   Press Ctrl+C to stop.\n")
 
         try:
-            # Configure logging to stderr for MCP mode
-            import logging
-            import sys
-
-            # Disable all stdout logging when running MCP server
-            # to prevent interference with JSON-RPC protocol
-            root_logger = logging.getLogger()
-
-            # Remove any existing handlers that might log to stdout
-            for handler in root_logger.handlers[:]:
-                if hasattr(handler, "stream") and handler.stream == sys.stdout:
-                    root_logger.removeHandler(handler)
-
-            # Add stderr handler if needed (but keep it minimal)
-            if not test_mode:
-                # In production mode, minimize stderr output too
-                logging.basicConfig(
-                    level=logging.ERROR,
-                    format="%(message)s",
-                    stream=sys.stderr,
-                    force=True,
-                )
-            else:
-                # In test mode, allow more verbose stderr logging
-                logging.basicConfig(
-                    level=logging.INFO,
-                    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-                    stream=sys.stderr,
-                    force=True,
-                )
-
-            # Import and run the stdio server directly
-            from ...services.mcp_gateway.server.stdio_server import SimpleMCPServer
-
-            server = SimpleMCPServer(name="claude-mpm-gateway", version="1.0.0")
-
-            # Run the server (handles stdio communication)
-            await server.run()
-            return 0
+            # Instead of running directly, we should use the wrapper script
+            # for consistent environment setup
+            import subprocess
+            from pathlib import Path
+            
+            # Find the wrapper script
+            project_root = Path(__file__).parent.parent.parent.parent.parent
+            wrapper_script = project_root / "scripts" / "mcp_wrapper.py"
+            
+            if not wrapper_script.exists():
+                print(f"❌ Error: Wrapper script not found at {wrapper_script}", file=sys.stderr)
+                print("\nPlease ensure the wrapper script is installed.", file=sys.stderr)
+                return 1
+            
+            # Run the wrapper script
+            print(f"Starting MCP server via wrapper: {wrapper_script}", file=sys.stderr)
+            
+            # Use subprocess to run the wrapper
+            # This ensures proper environment setup
+            result = subprocess.run(
+                [sys.executable, str(wrapper_script)],
+                cwd=str(project_root),
+                env={**os.environ, "MCP_MODE": "test" if test_mode else "production"}
+            )
+            
+            return result.returncode
 
         except ImportError as e:
             self.logger.error(f"Failed to import MCP server: {e}")