claude-mpm 4.24.0__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/agents/templates/ticket-completeness-examples.md

@@ -0,0 +1,139 @@
+# Ticket Completeness Protocol Examples
+
+## ✅ COMPLETE TICKET (Passes Zero PM Context Test)
+
+```
+Ticket: PROJ-123 "Implement OAuth2 authentication"
+
+Description:
+Add OAuth2 authentication flow to user login system.
+
+ACCEPTANCE CRITERIA:
+- Users can log in via OAuth2 with Google and GitHub providers
+- Existing username/password login continues to work
+- OAuth2 tokens stored securely in database
+- Token refresh implemented for expired tokens
+- All existing tests pass + new OAuth2 tests added
+- Performance: OAuth2 login completes in < 2 seconds
+
+TECHNICAL CONTEXT (Comment):
+Code Patterns:
+- Follow existing auth patterns in src/auth/strategies/
+- Use passport-oauth2 library (already in dependencies)
+- Token storage follows pattern in src/models/auth_token.py
+
+Files to Modify:
+- src/auth/strategies/oauth2.py (create new)
+- src/auth/router.py (add OAuth2 routes)
+- src/models/user.py (add oauth_provider field)
+- tests/test_auth_oauth2.py (create new)
+
+Dependencies:
+- passport-oauth2>=1.7.0 (already installed)
+- No new dependencies required
+
+RESEARCH FINDINGS (Comment):
+OAuth2 Flow Analysis:
+1. Authorization Code Flow recommended (most secure)
+2. Google OAuth2: Requires client_id/secret (get from admin)
+3. GitHub OAuth2: Requires app registration (get from admin)
+4. Token refresh: Implement background job (runs every 24h)
+
+Security Considerations:
+- Store tokens encrypted at rest (use existing encryption service)
+- Implement PKCE for mobile clients (future enhancement)
+- Rate limit OAuth2 endpoints (5 attempts per minute)
+
+Reference: https://oauth.net/2/ (see "Authorization Code Flow" section)
+
+SUCCESS CRITERIA (Comment):
+Verification Steps:
+1. User clicks "Login with Google" → redirected to Google consent
+2. User approves → redirected back with code → token exchange succeeds
+3. User profile populated from Google API
+4. Token stored in database (encrypted)
+5. User can access protected resources
+6. Token refresh runs automatically
+
+Performance:
+- OAuth2 login: < 2 seconds (measured with pytest-benchmark)
+- Token refresh: < 500ms per token
+
+DISCOVERED WORK SUMMARY (Comment):
+In-Scope (Created Subtasks):
+- PROJ-124: Add OAuth2 provider configuration UI
+- PROJ-125: Implement token refresh background job
+
+Out-of-Scope (Separate Tickets):
+- PROJ-126: Add OAuth2 support for Facebook (separate feature request)
+- PROJ-127: Migrate existing users to OAuth2 (data migration project)
+
+Deferred (Documented but not ticketed):
+- PKCE for mobile clients (not needed for web app yet)
+- Multi-factor auth (separate initiative)
+
+Scope Decision: We focused ONLY on Google/GitHub OAuth2 for web app.
+Mobile and Facebook support deferred to separate initiatives per user confirmation.
+```
+
+**Engineer Assessment**: ✅ COMPLETE
+- Can understand what to build? YES (acceptance criteria clear)
+- Has research findings? YES (OAuth2 flow, security considerations)
+- Has technical context? YES (code patterns, files to modify, dependencies)
+- Knows success criteria? YES (verification steps, performance targets)
+- Knows about discovered work? YES (subtasks created, scope documented)
+
+## ❌ INCOMPLETE TICKET (Fails Zero PM Context Test)
+
+```
+Ticket: PROJ-123 "Implement OAuth2 authentication"
+
+Description:
+Add OAuth2 authentication flow to user login system.
+
+(No comments, no attachments)
+```
+
+**Engineer Assessment**: ❌ INCOMPLETE
+- Can understand what to build? PARTIALLY (vague description)
+- Has research findings? NO (which providers? what flow?)
+- Has technical context? NO (which files? which libraries?)
+- Knows success criteria? NO (how to verify? performance targets?)
+- Knows about discovered work? NO (are there dependencies? follow-ups?)
+
+**Engineer Questions for PM**:
+1. Which OAuth2 providers should I support?
+2. Which OAuth2 flow should I use?
+3. How do I store tokens? What encryption?
+4. Which files do I need to modify?
+5. What libraries should I use?
+6. How do I test this?
+7. Are there any follow-up tickets I should know about?
+
+**PM Violation**: Ticket lacks ALL context. Engineer cannot proceed independently.
+
+## Attachment Decision Tree Examples
+
+### 📊 RESEARCH FINDINGS:
+- Summary (< 500 words) → Attach as ticket comment
+- Detailed analysis (> 500 words) → Save to docs/research/, link from ticket
+- Architecture diagrams → Attach as comment (markdown or image link)
+- Third-party docs → Reference URL in ticket comment with key excerpts
+
+### 💻 CODE ANALYSIS:
+- Code patterns → Attach key examples as comment (code blocks)
+- File locations → List in comment ("Files to modify: src/foo.py, tests/test_foo.py")
+- Dependencies → List in comment with versions ("Requires: requests>=2.28.0")
+- Integration points → Describe in comment with code examples
+
+### 🧪 QA/TEST RESULTS:
+- Test output → Attach as comment (use code blocks)
+- Bug reports → Create separate tickets, reference from original
+- Performance benchmarks → Attach as comment with numbers
+- Edge cases → List in comment with reproduction steps
+
+### ⚠️ DO NOT ATTACH (Reference Only):
+- CLAUDE.md patterns → Reference only ("Follow auth patterns in CLAUDE.md")
+- Project-wide conventions → Reference only ("See CONTRIBUTING.md")
+- Existing documentation → Link, don't duplicate
+- Common knowledge → Don't attach obvious information

claude_mpm/agents/templates/ticketing-examples.md

@@ -0,0 +1,277 @@
+# Ticketing Delegation Examples
+
+**Purpose**: Comprehensive examples of correct PM ticketing delegation patterns
+**Usage**: Reference for PM when delegating ticket operations to ticketing agent
+**Circuit Breaker**: #6 - PM MUST NEVER use mcp-ticketer tools directly
+
+---
+
+## Search Operations
+
+### Ticket Search Delegation
+
+**❌ WRONG - PM searches directly**:
+```
+User: "Find tickets related to authentication"
+PM: [Uses mcp__mcp-ticketer__ticket_search directly]  ← VIOLATION
+```
+
+**✅ CORRECT - PM delegates search**:
+```
+User: "Find tickets related to authentication"
+PM: "I'll have ticketing search for authentication tickets..."
+[Delegates to ticketing: "Search for tickets related to authentication"]
+PM: "Based on ticketing's search results, here are the relevant tickets..."
+```
+
+**Why This Matters**:
+- PM focuses on orchestration, not ticket system mechanics
+- Ticketing agent owns all mcp-ticketer tool expertise
+- Reduces PM token load by 31.5% (886 lines of ticketing protocols)
+- Maintains separation of concerns (PM = delegation, ticketing = execution)
+
+---
+
+## Listing Operations
+
+### Ticket List Delegation
+
+**❌ WRONG - PM lists tickets directly**:
+```
+User: "Show me open tickets"
+PM: [Uses mcp__mcp-ticketer__ticket_list directly]  ← VIOLATION
+```
+
+**✅ CORRECT - PM delegates listing**:
+```
+User: "Show me open tickets"
+PM: "I'll have ticketing list open tickets..."
+[Delegates to ticketing: "List all open tickets"]
+PM: "Ticketing found [X] open tickets: [summary]"
+```
+
+**Delegation Pattern**:
+1. PM receives user request for ticket data
+2. PM delegates to ticketing with specific query
+3. Ticketing uses mcp-ticketer tools to fetch data
+4. Ticketing returns summary to PM
+5. PM uses summary for decision-making (NOT full ticket data)
+
+---
+
+## CRUD Operations
+
+### Complete CRUD Patterns
+
+**Correct Pattern**:
+```
+PM: "I'll have ticketing [read/create/update/comment on] the ticket"
+→ Delegate to ticketing with specific instruction
+→ Ticketing uses mcp-ticketer tools
+→ Ticketing returns summary to PM
+→ PM uses summary for decision-making (not full ticket data)
+```
+
+**Violation Pattern**:
+```
+PM: "I'll check the ticket details"
+→ PM uses mcp__mcp-ticketer__ticket_read directly
+→ VIOLATION: Circuit Breaker #6 triggered
+```
+
+### Read Operations
+
+**❌ WRONG**:
+```
+PM: "Let me check ticket PROJ-123"
+[Uses mcp__mcp-ticketer__ticket_read("PROJ-123")]
+```
+
+**✅ CORRECT**:
+```
+PM: "I'll have ticketing read PROJ-123"
+[Delegates to ticketing: "Read ticket PROJ-123 and return status, priority, and blockers"]
+Ticketing: "PROJ-123 is in progress, high priority, blocked by PROJ-122"
+PM: "Based on ticketing's report, we need to resolve PROJ-122 first"
+```
+
+### Create Operations
+
+**❌ WRONG**:
+```
+PM: "Creating ticket now..."
+[Uses mcp__mcp-ticketer__ticket_create directly]
+```
+
+**✅ CORRECT**:
+```
+PM: "I'll have ticketing create a ticket for this work"
+[Delegates to ticketing: "Create ticket: Add authentication with JWT"]
+Ticketing: "Created PROJ-124: Add authentication with JWT"
+PM: "Ticketing created PROJ-124, now delegating implementation to engineer"
+```
+
+### Update Operations
+
+**❌ WRONG**:
+```
+PM: "Updating ticket status..."
+[Uses mcp__mcp-ticketer__ticket_update directly]
+```
+
+**✅ CORRECT**:
+```
+PM: "I'll have ticketing update PROJ-123 status to done"
+[Delegates to ticketing: "Update PROJ-123: set state=done, add completion comment"]
+Ticketing: "Updated PROJ-123 to done with completion notes"
+PM: "PROJ-123 marked complete, moving to next task"
+```
+
+### Comment Operations
+
+**❌ WRONG**:
+```
+PM: "Adding comment to ticket..."
+[Uses mcp__mcp-ticketer__ticket_comment directly]
+```
+
+**✅ CORRECT**:
+```
+PM: "I'll have ticketing add a progress update to PROJ-123"
+[Delegates to ticketing: "Add comment to PROJ-123: Implementation 60% complete, frontend done"]
+Ticketing: "Added progress comment to PROJ-123"
+PM: "Ticketing updated stakeholders on progress"
+```
+
+---
+
+## Ticket Context Propagation
+
+### Passing Ticket Context to Other Agents
+
+**Pattern**: PM receives ticket info from ticketing → propagates to engineer/research
+
+**Example Workflow**:
+```
+User: "Implement TICKET-123"
+
+Step 1: PM delegates to ticketing
+PM → Ticketing: "Read TICKET-123 and return full details"
+
+Step 2: Ticketing returns summary
+Ticketing → PM: {
+  "ticket_id": "TICKET-123",
+  "title": "Add OAuth2 authentication",
+  "description": "Implement OAuth2 flow...",
+  "priority": "high",
+  "acceptance_criteria": ["Users can login with Google", "Token refresh works"]
+}
+
+Step 3: PM propagates to engineer
+PM → Engineer: "Implement OAuth2 authentication based on TICKET-123
+🎫 TICKET CONTEXT:
+- Ticket ID: TICKET-123
+- Title: Add OAuth2 authentication
+- Priority: high
+- Acceptance Criteria: [...]
+- Description: [...]"
+
+Step 4: Engineer completes work
+Engineer → PM: "OAuth2 implemented, tests passing"
+
+Step 5: PM delegates ticket update
+PM → Ticketing: "Update TICKET-123: set state=done, add completion comment"
+```
+
+**Key Principle**: PM acts as information router, NOT information consumer. PM receives ticket summaries from ticketing and forwards context to implementation agents, but PM doesn't use ticket data for implementation decisions.
+
+---
+
+## Scope Protection Patterns
+
+### Project Scoping Requirements
+
+**Rule**: ALL ticket operations require project scoping (project_id or default_project configured)
+
+**❌ WRONG - No project context**:
+```
+PM → Ticketing: "List open tickets"
+Ticketing: ⚠️ Project filtering required! Use default_project or specify project_id
+```
+
+**✅ CORRECT - Project context included**:
+```
+PM → Ticketing: "List open tickets for project MYAPP"
+Ticketing: "Found 5 open tickets in MYAPP: [...]"
+```
+
+**Automatic Protection**:
+Ticketing agent automatically validates project scope before executing any ticket operation. If missing, ticketing prompts PM to clarify project context or configure default_project.
+
+---
+
+## Context Optimization
+
+### Compact Mode vs Full Mode
+
+**Compact Mode** (default):
+- Returns ~15 tokens per ticket (id, title, state, priority, assignee)
+- Use for: listings, searches, bulk operations
+- 90% token savings vs full mode
+
+**Full Mode**:
+- Returns ~185 tokens per ticket (all fields, descriptions, comments)
+- Use for: detailed analysis, single ticket reads
+- Only when full context is needed
+
+**Example - Listing 20 Tickets**:
+```
+Compact mode: 20 tickets × 15 tokens = 300 tokens
+Full mode: 20 tickets × 185 tokens = 3,700 tokens
+Savings: 3,400 tokens (91% reduction)
+```
+
+**PM Delegation Strategy**:
+```
+# For bulk operations - use compact mode
+PM → Ticketing: "List open tickets (compact mode)"
+Ticketing: Returns 20 tickets in 300 tokens
+
+# For detailed analysis - use full mode on specific tickets
+PM → Ticketing: "Read ticket PROJ-123 (full details)"
+Ticketing: Returns 1 ticket in 185 tokens
+```
+
+---
+
+## Success Criteria
+
+**PM is delegating correctly if**:
+- ✅ PM NEVER uses mcp__mcp-ticketer__* tools directly
+- ✅ ALL ticket operations go through ticketing agent
+- ✅ PM receives summaries, not full ticket data
+- ✅ PM propagates ticket context to other agents
+- ✅ Project scoping is always specified or configured
+
+**Red Flags** (Circuit Breaker #6 violations):
+- ❌ PM uses mcp__mcp-ticketer__ticket_search directly
+- ❌ PM uses mcp__mcp-ticketer__ticket_list directly
+- ❌ PM uses mcp__mcp-ticketer__ticket_read directly
+- ❌ PM uses mcp__mcp-ticketer__ticket_create directly
+- ❌ PM uses mcp__mcp-ticketer__ticket_update directly
+- ❌ PM uses any mcp-ticketer tool without delegating first
+
+**Rule of Thumb**: If PM is about to use any tool starting with `mcp__mcp-ticketer__*`, STOP and delegate to ticketing instead.
+
+---
+
+## Related References
+
+- **Circuit Breakers**: See [circuit-breakers.md](circuit-breakers.md#circuit-breaker-6)
+- **Ticket Completeness**: See [ticket-completeness-examples.md](ticket-completeness-examples.md)
+- **Ticketing Agent Instructions**: See [ticketing.md](ticketing.md)
+
+---
+
+**Last Updated**: 2025-12-01
+**Phase**: Phase 3 Optimization - Example Extraction

claude_mpm/cli/__init__.py

@@ -17,6 +17,7 @@ from typing import Optional
 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,
@@ -31,6 +32,7 @@ from .startup import (
     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
 
 # Version resolution
@@ -65,10 +67,43 @@ def main(argv: Optional[list] = None):
 
     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):
-        run_background_services()
-    logger = setup_mcp_server_logging(args)
+        # 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:
+            run_background_services()
+            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}")

claude_mpm/cli/__main__.py

@@ -1,3 +1,7 @@
+# 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.
 

claude_mpm/cli/chrome_devtools_installer.py

@@ -0,0 +1,175 @@
+"""
+Chrome DevTools MCP Auto-Installer
+===================================
+
+Automatically installs and configures chrome-devtools-mcp on startup
+to enable browser automation and web interaction capabilities in Claude Code.
+
+WHY: Users should have browser automation capabilities out-of-the-box without
+manual MCP server configuration.
+
+DESIGN DECISION: Non-blocking installation that doesn't prevent startup if it fails.
+Uses the `claude mcp add` command for native Claude Code integration.
+"""
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional, Tuple
+
+from ..core.logger import get_logger
+
+
+class ChromeDevToolsInstaller:
+    """Manages automatic installation of chrome-devtools-mcp."""
+
+    MCP_SERVER_NAME = "chrome-devtools"
+    INSTALL_COMMAND = ["npx", "chrome-devtools-mcp@latest"]
+
+    def __init__(self):
+        """Initialize the chrome-devtools installer."""
+        self.logger = get_logger(__name__)
+        self.claude_config_path = Path.home() / ".claude.json"
+
+    def is_already_configured(self) -> bool:
+        """
+        Check if chrome-devtools-mcp is already configured in Claude.
+
+        Returns:
+            True if already configured, False otherwise
+        """
+        try:
+            if not self.claude_config_path.exists():
+                self.logger.debug("Claude config file not found")
+                return False
+
+            with open(self.claude_config_path) as f:
+                config = json.load(f)
+
+            # Check if chrome-devtools is in mcpServers
+            mcp_servers = config.get("mcpServers", {})
+            is_configured = self.MCP_SERVER_NAME in mcp_servers
+
+            if is_configured:
+                self.logger.debug(
+                    f"{self.MCP_SERVER_NAME} already configured in Claude"
+                )
+            else:
+                self.logger.debug(f"{self.MCP_SERVER_NAME} not found in Claude config")
+
+            return is_configured
+
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Failed to parse Claude config: {e}")
+            return False
+        except Exception as e:
+            self.logger.debug(f"Error checking Chrome DevTools configuration: {e}")
+            return False
+
+    def install_mcp_server(self) -> Tuple[bool, Optional[str]]:
+        """
+        Install chrome-devtools-mcp using the claude CLI.
+
+        Returns:
+            Tuple of (success: bool, error_message: Optional[str])
+        """
+        try:
+            # Build the command: claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
+            command = [
+                "claude",
+                "mcp",
+                "add",
+                self.MCP_SERVER_NAME,
+                "--",
+            ] + self.INSTALL_COMMAND
+
+            self.logger.debug(f"Running: {' '.join(command)}")
+
+            # Run the command with timeout
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=30,  # 30 second timeout
+                check=False,
+            )
+
+            if result.returncode == 0:
+                self.logger.info(
+                    f"Successfully installed {self.MCP_SERVER_NAME} MCP server"
+                )
+                return True, None
+
+            # Command failed
+            error_msg = (
+                f"Failed to install {self.MCP_SERVER_NAME}: {result.stderr.strip()}"
+            )
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+        except subprocess.TimeoutExpired:
+            error_msg = (
+                f"Installation of {self.MCP_SERVER_NAME} timed out after 30 seconds"
+            )
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+        except FileNotFoundError:
+            error_msg = "Claude CLI not found. Is Claude Code installed?"
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+        except Exception as e:
+            error_msg = f"Unexpected error installing {self.MCP_SERVER_NAME}: {e}"
+            self.logger.warning(error_msg)
+            return False, error_msg
+
+    def auto_install(self, quiet: bool = False) -> bool:
+        """
+        Automatically install chrome-devtools-mcp if not already configured.
+
+        Args:
+            quiet: If True, suppress console output
+
+        Returns:
+            True if installation succeeded or already configured, False otherwise
+        """
+        # Check if already configured
+        if self.is_already_configured():
+            if not quiet:
+                print("✓ Chrome DevTools MCP ready", flush=True)
+            return True
+
+        # Show progress feedback
+        if not quiet:
+            print("Installing Chrome DevTools MCP...", end=" ", flush=True)
+
+        # Install the MCP server
+        success, error = self.install_mcp_server()
+
+        if success:
+            if not quiet:
+                print("✓", flush=True)
+            return True
+
+        # Installation failed
+        if not quiet:
+            print("(skipped)", flush=True)
+
+        # Log the error but don't fail startup
+        self.logger.debug(f"Chrome DevTools installation skipped: {error}")
+        return False
+
+
+def auto_install_chrome_devtools(quiet: bool = False) -> bool:
+    """
+    Convenience function to auto-install chrome-devtools-mcp.
+
+    Args:
+        quiet: If True, suppress console output
+
+    Returns:
+        True if installation succeeded or already configured, False otherwise
+    """
+    installer = ChromeDevToolsInstaller()
+    return installer.auto_install(quiet=quiet)

claude_mpm/cli/commands/__init__.py

@@ -19,6 +19,7 @@ from .info import show_info
 from .mcp import manage_mcp
 from .memory import manage_memory
 from .monitor import manage_monitor
+from .postmortem import run_postmortem
 from .run import run_session
 from .skills import manage_skills
 from .tickets import list_tickets, manage_tickets
@@ -41,6 +42,7 @@ __all__ = [
     # 'run_guarded_session',  # Excluded from default exports (experimental)
     "manage_tickets",
     "run_doctor",
+    "run_postmortem",
     "run_session",
     "show_info",
 ]