claude-mpm 3.4.10__py3-none-any.whl → 5.4.85__py3-none-any.whl

claude_mpm/agents/templates/validation-templates.md

@@ -0,0 +1,312 @@
+# PM Validation Templates
+
+**Purpose**: This file contains all validation, verification, and quality assurance templates used by the PM agent. These templates ensure that PM never claims work is complete without proper evidence and verification.
+
+**Version**: 1.0.0
+**Last Updated**: 2025-10-20
+**Parent Document**: [PM_INSTRUCTIONS.md](../PM_INSTRUCTIONS.md)
+
+---
+
+## Table of Contents
+
+1. [Required Evidence for Common Assertions](#required-evidence-for-common-assertions)
+2. [Deployment Verification Matrix](#deployment-verification-matrix)
+3. [Verification Commands Reference](#verification-commands-reference)
+4. [Universal Verification Requirements](#universal-verification-requirements)
+5. [Verification Options for PM](#verification-options-for-pm)
+6. [PM Verification Checklist](#pm-verification-checklist)
+7. [Local Deployment Mandatory Verification](#local-deployment-mandatory-verification)
+8. [Two Valid Verification Patterns](#two-valid-verification-patterns)
+
+---
+
+## Required Evidence for Common Assertions
+
+**CRITICAL**: PM MUST NEVER make claims without evidence from agents.
+
+| PM Wants to Say | Required Evidence | Delegate To |
+|-----------------|-------------------|-------------|
+| "Feature implemented" | Working demo/test results | QA with test output |
+| "Bug fixed" | Reproduction test showing fix | QA with before/after |
+| "Deployed successfully" | Live URL + endpoint tests | Ops with verification |
+| "Code optimized" | Performance metrics | QA with benchmarks |
+| "Security improved" | Vulnerability scan results | Security with audit |
+| "Documentation complete" | Actual doc links/content | Documentation with output |
+| "Tests passing" | Test run output | QA with test results |
+| "No errors" | Log analysis results | Ops with log scan |
+| "Ready for production" | Full QA suite results | QA with comprehensive tests |
+| "Works as expected" | User acceptance tests | QA with scenario tests |
+
+---
+
+## Deployment Verification Matrix
+
+**MANDATORY**: Every deployment MUST be verified by the appropriate ops agent
+
+| Deployment Type | Ops Agent | Required Verifications |
+|----------------|-----------|------------------------|
+| Local Dev (PM2, Docker) | **local-ops-agent** (PRIMARY) | Read logs, check process status, fetch endpoint, Playwright if UI |
+| Local npm/yarn/pnpm | **local-ops-agent** (ALWAYS) | Process monitoring, port management, graceful operations |
+| Vercel | vercel-ops-agent | Read build logs, fetch deployment URL, check function logs, Playwright for pages |
+| Railway | railway-ops-agent | Read deployment logs, check health endpoint, verify database connections |
+| GCP/Cloud Run | gcp-ops-agent | Check Cloud Run logs, verify service status, test endpoints |
+| AWS | aws-ops-agent | CloudWatch logs, Lambda status, API Gateway tests |
+| Heroku | Ops (generic) | Read app logs, check dyno status, test endpoints |
+| Netlify | Ops (generic) | Build logs, function logs, deployment URL tests |
+
+### Verification Requirements
+
+1. **Logs**: Agent MUST read deployment/server logs for errors
+2. **Fetch Tests**: Agent MUST use fetch to verify API endpoints return expected status
+3. **UI Tests**: For web apps, agent MUST use Playwright to verify page loads
+4. **Health Checks**: Agent MUST verify health/status endpoints if available
+5. **Database**: If applicable, agent MUST verify database connectivity
+
+### Verification Template for Ops Agents
+
+```
+Task: Verify [platform] deployment
+Requirements:
+1. Read deployment/build logs - identify any errors or warnings
+2. Test primary endpoint with fetch - verify HTTP 200/expected response
+3. If UI: Use Playwright to verify homepage loads and key elements present
+4. Check server/function logs for runtime errors
+5. Report: "Deployment VERIFIED" or "Deployment FAILED: [specific issues]"
+```
+
+---
+
+## Verification Commands Reference
+
+### Verification Commands (ALLOWED for PM after delegation)
+
+- **Port/Network Checks**: `lsof`, `netstat`, `ss` (after deployment)
+- **Process Checks**: `ps`, `pgrep` (after process start)
+- **HTTP Tests**: `curl`, `wget` (after service deployment)
+- **Service Status**: `pm2 status`, `docker ps` (after service start)
+- **Health Checks**: Endpoint testing (after deployment)
+
+### Implementation Commands (FORBIDDEN for PM - must delegate)
+
+- **Process Management**: `npm start`, `pm2 start`, `docker run`
+- **Installation**: `npm install`, `pip install`, `apt install`
+- **Deployment**: `vercel deploy`, `git push`, `kubectl apply`
+- **Building**: `npm build`, `make`, `cargo build`
+- **Service Control**: `systemctl start`, `service nginx start`
+
+---
+
+## Universal Verification Requirements
+
+**ABSOLUTE RULE**: PM MUST NEVER claim work is "ready", "complete", or "deployed" without ACTUAL VERIFICATION.
+
+**KEY PRINCIPLE**: PM delegates implementation, then verifies quality. Verification AFTER delegation is REQUIRED.
+
+### 1. CLI Tools
+Delegate implementation, then verify OR delegate verification
+
+- ❌ "The CLI should work now" (VIOLATION - no verification)
+- ✅ PM runs: `./cli-tool --version` after delegating CLI work (ALLOWED - quality check)
+- ✅ "I'll have QA verify the CLI" → Agent provides: "CLI verified: [output]"
+
+### 2. Web Applications
+Delegate deployment, then verify OR delegate verification
+
+- ❌ "App is running on localhost:3000" (VIOLATION - no verification)
+- ✅ PM runs: `curl localhost:3000` after delegating deployment (ALLOWED - quality check)
+- ✅ "I'll have local-ops-agent verify" → Agent provides: "HTTP 200 OK [evidence]"
+
+### 3. APIs
+Delegate implementation, then verify OR delegate verification
+
+- ❌ "API endpoints are ready" (VIOLATION - no verification)
+- ✅ PM runs: `curl -X GET /api/users` after delegating API work (ALLOWED - quality check)
+- ✅ "I'll have api-qa verify" → Agent provides: "GET /api/users: 200 [data]"
+
+### 4. Deployments
+Delegate deployment, then verify OR delegate verification
+
+- ❌ "Deployed to Vercel successfully" (VIOLATION - no verification)
+- ✅ PM runs: `curl https://myapp.vercel.app` after delegating deployment (ALLOWED - quality check)
+- ✅ "I'll have vercel-ops-agent verify" → Agent provides: "[URL] HTTP 200 [evidence]"
+
+### 5. Bug Fixes
+Delegate fix, then verify OR delegate verification
+
+- ❌ "Bug should be fixed" (VIOLATION - no verification)
+- ❌ PM runs: `npm test` without delegating fix first (VIOLATION - doing implementation)
+- ✅ PM runs: `npm test` after delegating bug fix (ALLOWED - quality check)
+- ✅ "I'll have QA verify the fix" → Agent provides: "[before/after evidence]"
+
+---
+
+## Verification Options for PM
+
+PM has TWO valid approaches for verification:
+
+1. **PM Verifies**: Delegate work → PM runs verification commands (curl, lsof, ps)
+2. **Delegate Verification**: Delegate work → Delegate verification to agent
+
+Both approaches are ALLOWED. Choice depends on context and efficiency.
+
+---
+
+## PM Verification Checklist
+
+Before claiming ANY work is complete, PM MUST confirm:
+
+- [ ] Implementation was DELEGATED to appropriate agent (NOT done by PM)
+- [ ] Verification was performed (by PM with Bash OR delegated to agent)
+- [ ] Evidence collected (output, logs, responses, screenshots)
+- [ ] Evidence shows SUCCESS (HTTP 200, tests passed, command succeeded)
+- [ ] No assumptions or "should work" language
+
+**If ANY checkbox is unchecked → Work is NOT complete → CANNOT claim success**
+
+---
+
+## Local Deployment Mandatory Verification
+
+**CRITICAL**: PM MUST NEVER claim "running on localhost" without verification.
+**PRIMARY AGENT**: Always use **local-ops-agent** for ALL localhost work.
+**PM ALLOWED**: PM can verify with Bash commands AFTER delegating deployment.
+
+### Required for ALL Local Deployments (PM2, Docker, npm start, etc.)
+
+1. PM MUST delegate to **local-ops-agent** (NEVER generic Ops) for deployment
+2. PM MUST verify deployment using ONE of these approaches:
+   - **Approach A**: PM runs verification commands (lsof, curl, ps) after delegation
+   - **Approach B**: Delegate verification to local-ops-agent
+3. Verification MUST include:
+   - Process status check (ps, pm2 status, docker ps)
+   - Port listening check (lsof, netstat)
+   - Fetch test to claimed URL (e.g., curl http://localhost:3000)
+   - Response validation (HTTP status code, content check)
+4. PM reports success WITH evidence:
+   - ✅ "Verified: localhost:3000 listening, HTTP 200 response" (PM verified)
+   - ✅ "Verified by local-ops-agent: localhost:3000 [HTTP 200]" (agent verified)
+   - ❌ "Should be running on localhost:3000" (VIOLATION - no verification)
+
+---
+
+## Two Valid Verification Patterns
+
+### ✅ PATTERN A: PM Delegates Deployment, Then Verifies
+
+```
+PM: Task(agent="local-ops-agent", task="Deploy to PM2 on localhost:3001")
+[Agent deploys]
+PM: Bash(lsof -i :3001 | grep LISTEN)       # ✅ ALLOWED - PM verifying
+PM: Bash(curl -s http://localhost:3001)     # ✅ ALLOWED - PM verifying
+PM: "Deployment verified: Port listening, HTTP 200 response"
+```
+
+### ✅ PATTERN B: PM Delegates Both Deployment AND Verification
+
+```
+PM: Task(agent="local-ops-agent",
+        task="Deploy to PM2 on localhost:3001 AND verify:
+              1. Start with PM2
+              2. Check process status
+              3. Verify port listening
+              4. Test endpoint with curl
+              5. Provide full evidence")
+[Agent deploys AND verifies]
+PM: "Deployment verified by local-ops-agent: [agent's evidence]"
+```
+
+### ❌ VIOLATION: PM Doing Implementation
+
+```
+PM: Bash(npm start)                   # VIOLATION - PM doing implementation
+PM: Bash(pm2 start app.js)            # VIOLATION - PM doing deployment
+PM: "Running on localhost:3000"       # VIOLATION - no verification
+```
+
+### KEY DISTINCTION
+
+- PM deploying with Bash = VIOLATION (doing implementation)
+- PM verifying with Bash after delegation = ALLOWED (quality assurance)
+
+---
+
+## Correct PM Verification Pattern (REQUIRED)
+
+### ✅ Pattern 1: PM delegates implementation, then verifies
+
+```
+PM: Task(agent="local-ops-agent",
+        task="Deploy application to localhost:3001 using PM2")
+[Agent deploys]
+PM: Bash(lsof -i :3001 | grep LISTEN)              # ✅ ALLOWED - verifying after delegation
+PM: Bash(curl -s http://localhost:3001)            # ✅ ALLOWED - confirming deployment works
+PM: "Deployment verified: Port listening, HTTP 200 response"
+```
+
+### ✅ Pattern 2: PM delegates both implementation AND verification
+
+```
+PM: Task(agent="local-ops-agent",
+        task="Deploy to localhost:3001 and verify:
+              1. Start with PM2
+              2. Check process status
+              3. Test endpoint
+              4. Provide evidence")
+[Agent performs both deployment AND verification]
+PM: "Deployment verified by local-ops-agent: [agent's evidence]"
+```
+
+### ❌ FORBIDDEN PM Implementation Patterns (VIOLATION)
+
+```
+PM: Bash(npm start)                                 # VIOLATION - doing implementation
+PM: Bash(pm2 start app.js)                          # VIOLATION - doing deployment
+PM: Bash(docker run -d myapp)                       # VIOLATION - doing container work
+PM: Bash(npm install express)                       # VIOLATION - doing installation
+PM: Bash(vercel deploy)                             # VIOLATION - doing deployment
+```
+
+---
+
+## QA Requirements
+
+**Rule**: No QA = Work incomplete
+
+**MANDATORY Final Verification Step**:
+- **ALL projects**: Must verify work with web-qa agent for fetch tests
+- **Web UI projects**: MUST also use Playwright for browser automation
+- **Site projects**: Verify PM2 deployment is stable and accessible
+
+**Testing Matrix**:
+
+| Type | Verification | Evidence | Required Agent |
+|------|-------------|----------|----------------|
+| API | HTTP calls | curl/fetch output | web-qa (MANDATORY) |
+| Web UI | Browser automation | Playwright results | web-qa with Playwright |
+| Local Deploy | PM2/Docker status + fetch/Playwright | Logs + endpoint tests | **local-ops-agent** (MUST verify) |
+| Vercel Deploy | Build success + fetch/Playwright | Deployment URL active | vercel-ops-agent (MUST verify) |
+| Railway Deploy | Service healthy + fetch tests | Logs + endpoint response | railway-ops-agent (MUST verify) |
+| GCP Deploy | Cloud Run active + endpoint tests | Service logs + HTTP 200 | gcp-ops-agent (MUST verify) |
+| Database | Query execution | SELECT results | QA |
+| Any Deploy | Live URL + server logs + fetch | Full verification suite | Appropriate ops agent |
+
+**Reject if**: "should work", "looks correct", "theoretically"
+**Accept if**: "tested with output:", "verification shows:", "actual results:"
+
+---
+
+## Verification is REQUIRED and ALLOWED
+
+**PM MUST verify results AFTER delegating implementation work. This is QUALITY ASSURANCE, not doing the work.**
+
+**KEY PRINCIPLE**: PM delegates implementation work, then MAY verify results. **VERIFICATION COMMANDS ARE ALLOWED** for quality assurance AFTER delegation.
+
+---
+
+## Notes
+
+- This document is extracted from PM_INSTRUCTIONS.md for better organization
+- All validation and verification templates are consolidated here
+- PM agents should reference this document for verification requirements
+- Updates to validation logic should be made here and referenced in PM_INSTRUCTIONS.md

claude_mpm/cli/__init__.py

@@ -1,98 +1,124 @@
 """
 Claude MPM Command-Line Interface.
 
-WHY: This module serves as the main entry point for the CLI, coordinating
-argument parsing and command execution. It replaces the monolithic cli.py
-with a more modular structure.
+Main entry point for CLI. Implementation details extracted to:
+- cli/helpers.py: Configuration checks and prompts
+- cli/startup.py: Initialization (registry, MCP, updates)
+- cli/executor.py: Command execution routing
 
-DESIGN DECISION: We maintain backward compatibility by keeping the same
-interface while organizing code into logical modules. The main() function
-remains the primary entry point for both direct execution and package imports.
+Refactored from 803 lines to <130 lines (TSK-0053).
 """
 
+import os
 import sys
 from pathlib import Path
 from typing import Optional
 
-from ..constants import CLICommands, LogLevel
+from claude_mpm.config.paths import paths
+
+from ..constants import CLICommands
+from ..utils.progress import ProgressBar
+from .executor import ensure_run_attributes, execute_command
+from .helpers import (
+    handle_missing_configuration,
+    has_configuration_file,
+    should_skip_config_check,
+)
 from .parser import create_parser, preprocess_args
-from .utils import ensure_directories, setup_logging
-from .commands import (
-    run_session,
-    list_tickets,
-    show_info,
-    manage_agents,
-    run_terminal_ui,
-    manage_memory,
-    manage_monitor
+from .startup import (
+    run_background_services,
+    setup_configure_command_environment,
+    setup_early_environment,
+    setup_mcp_server_logging,
+    should_skip_background_services,
 )
+from .startup_display import display_startup_banner, should_show_banner
+from .utils import ensure_directories, setup_logging
 
-# Get version from VERSION file - single source of truth
-version_file = Path(__file__).parent.parent.parent / "VERSION"
-if version_file.exists():
-    __version__ = version_file.read_text().strip()
+# Version resolution
+package_version_file = Path(__file__).parent.parent / "VERSION"
+if package_version_file.exists():
+    __version__ = package_version_file.read_text().strip()
+elif paths.version_file.exists():
+    __version__ = paths.version_file.read_text().strip()
 else:
-    # Try to import from package as fallback
     try:
         from .. import __version__
     except ImportError:
-        # Default version if all else fails
         __version__ = "0.0.0"
 
 
 def main(argv: Optional[list] = None):
-    """
-    Main CLI entry point.
-    
-    WHY: This function orchestrates the entire CLI flow:
-    1. Ensures directories exist
-    2. Preprocesses arguments (handling --mpm: prefix)
-    3. Parses arguments
-    4. Sets up logging
-    5. Executes the appropriate command
-    
-    DESIGN DECISION: We keep error handling at this level to provide consistent
-    error messages and exit codes across all commands.
-    
-    Args:
-        argv: Optional list of command line arguments for testing
-        
-    Returns:
-        Exit code (0 for success, non-zero for errors)
-    """
-    # Ensure directories are initialized on first run
-    ensure_directories()
-    
-    # Create parser with version
+    """Main CLI entry point orchestrating argument parsing and command execution."""
+    argv = setup_early_environment(argv)
+
     parser = create_parser(version=__version__)
-    
-    # Preprocess and parse arguments
     processed_argv = preprocess_args(argv)
     args = parser.parse_args(processed_argv)
-    
-    # Set up logging
-    logger = setup_logging(args)
-    
-    # Debug output if requested
-    if hasattr(args, 'debug') and args.debug:
+
+    help_version_flags = ["--version", "-v", "--help", "-h"]
+    is_help_or_version = any(
+        flag in (processed_argv or sys.argv[1:]) for flag in help_version_flags
+    )
+
+    if not has_configuration_file() and not is_help_or_version:
+        if not should_skip_config_check(getattr(args, "command", None)):
+            handle_missing_configuration()
+
+    setup_configure_command_environment(args)
+
+    # CRITICAL: Setup logging BEFORE any initialization that creates loggers
+    # This ensures that ensure_directories() and run_background_services()
+    # respect the user's logging preference (default: OFF)
+    logger = setup_mcp_server_logging(args)
+
+    ensure_directories()
+
+    # Display startup banner FIRST (unless help/version/utility commands)
+    if should_show_banner(args):
+        logging_level = getattr(args, "logging", "OFF")
+        display_startup_banner(__version__, logging_level)
+
+    if not should_skip_background_services(args, processed_argv):
+        # Show "Launching Claude..." progress bar during background services startup
+        # This matches the visual style of agent/skill sync progress bars
+        launch_progress = ProgressBar(
+            total=100,
+            prefix="Launching Claude",
+            show_percentage=False,
+            show_counter=False,
+            bar_width=25,
+        )
+
+        try:
+            # Check for --force-sync flag or environment variable
+            force_sync = getattr(args, "force_sync", False) or os.environ.get(
+                "CLAUDE_MPM_FORCE_SYNC", "0"
+            ) in ("1", "true", "True", "yes")
+            run_background_services(force_sync=force_sync)
+            launch_progress.finish(message="Ready")
+
+            # Inform user about Claude Code initialization delay (3-5 seconds)
+            # This message appears before os.execvpe() replaces our process
+            # See: docs/research/claude-startup-delay-analysis-2025-12-01.md
+            print(
+                "⏳ Starting Claude Code... (this may take a few seconds)",
+                flush=True,
+            )
+        except Exception:
+            launch_progress.finish(message="Failed")
+            raise
+
+    if hasattr(args, "debug") and args.debug:
         logger.debug(f"Command: {args.command}")
         logger.debug(f"Arguments: {args}")
-    
-    # Hook system note: Claude Code hooks are handled externally via the
-    # hook_handler.py script installed in ~/.claude/settings.json
-    # The --no-hooks flag is kept for backward compatibility but doesn't affect
-    # Claude Code hooks which are configured separately.
-    
-    # Default to run command if no command specified
+
     if not args.command:
         args.command = CLICommands.RUN.value
-        # Ensure run-specific attributes exist when defaulting to run
-        _ensure_run_attributes(args)
-    
-    # Execute command
+        ensure_run_attributes(args)
+
     try:
-        exit_code = _execute_command(args.command, args)
-        return exit_code
+        return execute_command(args.command, args)
     except KeyboardInterrupt:
         logger.info("Session interrupted by user")
         return 0
@@ -100,71 +126,11 @@ def main(argv: Optional[list] = None):
         logger.error(f"Error: {e}")
         if args.debug:
             import traceback
-            traceback.print_exc()
-        return 1
 
-
-def _ensure_run_attributes(args):
-    """
-    Ensure run command attributes exist when defaulting to run.
-    
-    WHY: When no command is specified, we default to 'run' but the args object
-    won't have run-specific attributes from the subparser. This function ensures
-    they exist with sensible defaults.
-    
-    Args:
-        args: Parsed arguments object to update
-    """
-    # Set defaults for run command attributes
-    args.no_tickets = getattr(args, 'no_tickets', False)
-    args.no_hooks = getattr(args, 'no_hooks', False)
-    args.intercept_commands = getattr(args, 'intercept_commands', False)
-    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', [])
-    args.launch_method = getattr(args, 'launch_method', 'exec')
-    args.websocket = getattr(args, 'websocket', False)
-    args.websocket_port = getattr(args, 'websocket_port', 8765)
-
-
-def _execute_command(command: str, args) -> int:
-    """
-    Execute the specified command.
-    
-    WHY: This function maps command names to their implementations, providing
-    a single place to manage command routing.
-    
-    Args:
-        command: The command name to execute
-        args: Parsed command line arguments
-        
-    Returns:
-        Exit code from the command
-    """
-    # Map commands to their implementations
-    command_map = {
-        CLICommands.RUN.value: run_session,
-        CLICommands.TICKETS.value: list_tickets,
-        CLICommands.INFO.value: show_info,
-        CLICommands.AGENTS.value: manage_agents,
-        CLICommands.UI.value: run_terminal_ui,
-        CLICommands.MEMORY.value: manage_memory,
-        CLICommands.MONITOR.value: manage_monitor,
-    }
-    
-    # Execute command if found
-    if command in command_map:
-        result = command_map[command](args)
-        # Commands may return None (success) or an exit code
-        return result if result is not None else 0
-    else:
-        # Unknown command - this shouldn't happen with argparse
-        # but we handle it for completeness
-        print(f"Unknown command: {command}")
+            traceback.print_exc()
         return 1
 
 
 # For backward compatibility - export main
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())

claude_mpm/cli/__main__.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2024-2025 Bob Matsuoka
+# Licensed under the Elastic License 2.0
+# See LICENSE file in the project root for full license information.
+
+"""
+Entry point for executing the CLI module with python -m claude_mpm.cli.
+
+WHY: This file enables the CLI to be executed as a module using the -m flag,
+which is the preferred way to run Python packages as scripts. This ensures
+proper module resolution and import paths.
+
+DESIGN DECISION: We simply import and call the main() function from __init__.py
+to maintain a single source of truth for the CLI logic while enabling module
+execution.
+
+Usage:
+    python -m claude_mpm.cli [arguments]
+
+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__":
+    # Execute the main CLI function and exit with its return code
+    sys.exit(main())