claude-mpm 4.21.0__py3-none-any.whl → 5.0.2__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,44 @@ 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:
+            launch_progress.update(10)  # Start progress
+            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}")