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

claude_mpm/cli_module/migration_example.py

@@ -6,56 +6,55 @@ from 16 to under 10 by using ArgumentRegistry and CommandRegistry.
 
 import argparse
 import sys
-from pathlib import Path
 from typing import Optional
 
 from claude_mpm._version import __version__
+from claude_mpm.cli import ArgumentRegistry, CommandRegistry, register_standard_commands
 from claude_mpm.core.logger import get_logger, setup_logging
 from claude_mpm.services.hook_service_manager import HookServiceManager
-from claude_mpm.cli import ArgumentRegistry, CommandRegistry, register_standard_commands
 
 
 def main_refactored(argv: Optional[list] = None):
     """Refactored main CLI entry point with reduced complexity.
-    
+
     This version uses registries to manage arguments and commands,
     reducing cyclomatic complexity from 16 to approximately 8.
     """
     # Initialize registries
     arg_registry = ArgumentRegistry()
     cmd_registry = CommandRegistry(arg_registry)
-    
+
     # Register standard commands
     register_standard_commands(cmd_registry)
-    
+
     # Create parser with basic info
     parser = argparse.ArgumentParser(
         prog="claude-mpm",
         description=f"Claude Multi-Agent Project Manager v{__version__} - Orchestrate Claude with agent delegation and ticket tracking",
-        epilog="By default, runs an orchestrated Claude session. Use 'claude-mpm' for interactive mode or 'claude-mpm -i \"prompt\"' for non-interactive mode."
+        epilog="By default, runs an orchestrated Claude session. Use 'claude-mpm' for interactive mode or 'claude-mpm -i \"prompt\"' for non-interactive mode.",
     )
-    
+
     # Store version for ArgumentRegistry
     parser._version = f"claude-mpm {__version__}"
-    
+
     # Apply global arguments
-    arg_registry.apply_arguments(parser, groups=['global'])
-    
+    arg_registry.apply_arguments(parser, groups=["global"])
+
     # Apply run arguments at top level (for default behavior)
-    arg_registry.apply_arguments(parser, groups=['run'], exclude=['no_hooks'])
-    
+    arg_registry.apply_arguments(parser, groups=["run"], exclude=["no_hooks"])
+
     # Set up subcommands
     cmd_registry.setup_subcommands(parser)
-    
+
     # Parse arguments
     args = parser.parse_args(argv)
-    
+
     # Set up logging
     _setup_logging(args)
-    
+
     # Initialize hook service
     hook_manager = _initialize_hook_service(args)
-    
+
     try:
         # Execute command
         result = cmd_registry.execute_command(args, hook_manager=hook_manager)
@@ -63,7 +62,7 @@ def main_refactored(argv: Optional[list] = None):
             parser.print_help()
             return 1
         return result or 0
-        
+
     except KeyboardInterrupt:
         get_logger("cli").info("Session interrupted by user")
         return 0
@@ -72,6 +71,7 @@ def main_refactored(argv: Optional[list] = None):
         logger.error(f"Error: {e}")
         if args.debug:
             import traceback
+
             traceback.print_exc()
         return 1
     finally:
@@ -85,99 +85,77 @@ def _setup_logging(args):
     # Handle deprecated --debug flag
     if args.debug and args.logging == "OFF":
         args.logging = "DEBUG"
-    
+
     # Only setup logging if not OFF
     if args.logging != "OFF":
         setup_logging(level=args.logging, log_dir=args.log_dir)
     else:
         # Minimal logger for CLI feedback
         import logging
+
         logger = logging.getLogger("cli")
         logger.setLevel(logging.WARNING)
 
 
 def _initialize_hook_service(args):
     """Initialize hook service if enabled (extracted helper)."""
-    if getattr(args, 'no_hooks', False):
+    if getattr(args, "no_hooks", False):
         return None
-        
+
     try:
         # Check if hooks are enabled via config
         from claude_mpm.config.hook_config import HookConfig
-        
+
         if not HookConfig.is_hooks_enabled():
             get_logger("cli").info("Hooks disabled via configuration")
             return None
-            
+
         hook_manager = HookServiceManager(log_dir=args.log_dir)
         if hook_manager.start_service():
             logger = get_logger("cli")
             logger.info(f"Hook service started on port {hook_manager.port}")
             print(f"Hook service started on port {hook_manager.port}")
             return hook_manager
-        else:
-            logger = get_logger("cli")
-            logger.warning("Failed to start hook service, continuing without hooks")
-            print("Failed to start hook service, continuing without hooks")
-            return None
-            
+        logger = get_logger("cli")
+        logger.warning("Failed to start hook service, continuing without hooks")
+        print("Failed to start hook service, continuing without hooks")
+        return None
+
     except Exception as e:
-        get_logger("cli").warning(f"Hook service initialization failed: {e}, continuing without hooks")
+        get_logger("cli").warning(
+            f"Hook service initialization failed: {e}, continuing without hooks"
+        )
         return None
 
 
 # Example of how to add custom commands
 def extend_with_custom_commands(cmd_registry: CommandRegistry):
     """Example of adding custom commands to the registry."""
-    
+
     def validate_command(args, **kwargs):
         """Custom validation command."""
         print("Running validation...")
         # Implementation here
         return 0
-    
+
     # Register custom command
     cmd_registry.register(
-        name='validate',
-        help_text='Validate project configuration and agent setup',
+        name="validate",
+        help_text="Validate project configuration and agent setup",
         handler=validate_command,
-        argument_groups=['framework'],
+        argument_groups=["framework"],
         extra_args={
-            'strict': {
-                'flags': ['--strict'],
-                'action': 'store_true',
-                'help': 'Enable strict validation mode'
+            "strict": {
+                "flags": ["--strict"],
+                "action": "store_true",
+                "help": "Enable strict validation mode",
             }
-        }
+        },
     )
 
 
 # Comparison with original main() function
-def complexity_comparison():
-    """Show the complexity reduction achieved.
-    
-    Original main() function:
-    - Cyclomatic complexity: 16
-    - Lines of code: ~230
-    - Duplicate argument definitions: 6 (for 'run' command)
-    - Mixed concerns: argument parsing, logging, hook service, command dispatch
-    
-    Refactored main_refactored() function:
-    - Cyclomatic complexity: ~8
-    - Lines of code: ~50
-    - Duplicate argument definitions: 0
-    - Separated concerns: registries handle definitions, helpers handle setup
-    
-    Benefits:
-    1. Centralized argument definitions eliminate duplication
-    2. Command registry simplifies adding new commands
-    3. Extracted helpers reduce nesting and conditionals
-    4. Easier to test individual components
-    5. Clear separation of concerns
-    """
-    pass
-
 
 if __name__ == "__main__":
     # Example usage of refactored main
-    sys.exit(main_refactored())
+    sys.exit(main_refactored())

claude_mpm/commands/__init__.py

@@ -0,0 +1,14 @@
+"""
+Commands package for Claude MPM.
+
+This module contains command documentation files (Markdown) that are accessed
+via importlib.resources.path() for command help and reference material.
+
+This __init__.py file is required to make this directory recognizable as a
+Python package by setuptools, which is necessary for proper distribution
+and importlib resource access in installed packages.
+
+Without this file, importlib.resources.path("claude_mpm", "commands") would
+fail in the distributed package, even though it works in development when
+the package is installed in editable mode.
+"""

claude_mpm/commands/mpm-config.md

@@ -0,0 +1,28 @@
+---
+namespace: mpm/config
+command: config
+aliases: [mpm-config]
+migration_target: /mpm/config
+category: config
+description: Manage Claude MPM configuration
+---
+# /mpm-config
+
+Unified configuration management with auto-detection.
+
+## Usage
+```
+/mpm-config [auto|view|validate|status] [options]
+```
+
+**Modes:**
+- `auto` (default): Auto-detect toolchain and configure agents/skills
+- `view`: Display current configuration
+- `validate`: Check configuration validity
+- `status`: Show configuration health
+
+**Key Options:**
+- `--yes`: Auto-deploy without confirmation
+- `--preview`: Show recommendations only
+
+See docs/commands/config.md for full options.

claude_mpm/commands/mpm-doctor.md

@@ -0,0 +1,20 @@
+---
+namespace: mpm/system
+command: doctor
+aliases: [mpm-doctor]
+migration_target: /mpm/system:doctor
+category: system
+description: Run diagnostic checks on Claude MPM installation
+---
+# /mpm-doctor
+
+Run comprehensive diagnostics on Claude MPM installation.
+
+## Usage
+```
+/mpm-doctor [--verbose] [--fix]
+```
+
+Checks: installation, configuration, WebSocket, agents, memory, hooks.
+
+See docs/commands/doctor.md for details.

claude_mpm/commands/mpm-help.md

@@ -0,0 +1,20 @@
+---
+namespace: mpm/system
+command: help
+aliases: [mpm-help]
+migration_target: /mpm/system:help
+category: system
+description: Display help for Claude MPM commands
+---
+# /mpm-help
+
+Show help for MPM commands. Delegates to PM agent.
+
+## Usage
+```
+/mpm-help [command]
+```
+
+Shows all commands or detailed help for specific command.
+
+See docs/commands/help.md for full command reference.

claude_mpm/commands/mpm-init.md

@@ -0,0 +1,120 @@
+---
+namespace: mpm/system
+command: init
+aliases: [mpm-init]
+migration_target: /mpm/system:init
+category: system
+description: Initialize or update project for Claude Code and MPM
+---
+# /mpm-init
+
+Initialize or intelligently update project for Claude Code and Claude MPM.
+
+## Usage
+```
+/mpm-init [update|context|resume|catchup] [options]
+```
+
+## Core Modes
+
+### Project Setup
+```
+/mpm-init                      # Auto-detect: offer update or create
+/mpm-init update               # Quick update (30-day git activity)
+/mpm-init --update             # Full documentation refresh
+/mpm-init --force              # Force recreate from scratch
+```
+
+**Delegates to Agentic Coder Optimizer agent** for:
+- CLAUDE.md creation/update (with priority rankings 🔴🟡🟢⚪)
+- AST analysis and code structure docs
+- Single-path workflows (ONE way to do ANYTHING)
+- Tool configuration, memory system, gitignore management
+
+**Smart Update Mode:** Auto-detects existing CLAUDE.md and offers update vs recreate.
+
+### Context Analysis
+```
+/mpm-init context [--days N]   # Intelligent git history analysis (default: 7 days)
+/mpm-init catchup              # Quick commit history (last 25 commits, no analysis)
+```
+
+**context:** Delegates to Research agent for deep analysis of:
+- Active work streams (from commit patterns)
+- Intent and motivation (from messages)
+- Risks and blockers
+- Recommended next actions
+
+**catchup:** Direct CLI execution, instant output.
+
+### Resume from Logs
+```
+/mpm-init resume [--list] [--session-id ID]
+```
+
+Reads stop event logs from `.claude-mpm/resume-logs/` and `.claude-mpm/responses/` showing:
+- What was being worked on
+- Tasks completed, files modified
+- Next steps, stop reason, token usage
+- Git context (branch, status)
+
+## Key Options
+
+**Configuration:**
+- `--project-type TYPE`: web, api, cli, library
+- `--framework NAME`: react, django, fastapi, etc.
+- `--ast-analysis` / `--no-ast-analysis`: Enable/disable code analysis
+- `--comprehensive` / `--minimal`: Full setup vs CLAUDE.md only
+
+**Organization:**
+- `--organize`: Organize misplaced files
+- `--preserve-custom`: Keep custom sections (default)
+- `--review`: Review without changes
+
+## What Gets Created
+
+**New Projects:**
+- ✅ CLAUDE.md (priority-ranked instructions)
+- ✅ Single-path workflows (make build/test/deploy)
+- ✅ Tool configs (linting, formatting, testing)
+- ✅ Memory system (.claude-mpm/memories/)
+- ✅ DEVELOPER.md, CODE_STRUCTURE.md (with AST)
+- ✅ .gitignore updates (auto-adds .claude-mpm/)
+
+**Updates:**
+- ✅ Smart merging (preserves custom sections)
+- ✅ Automatic archival (docs/_archive/)
+- ✅ Change tracking
+
+## Examples
+
+```bash
+# Quick start
+/mpm-init                      # Auto-detect mode
+
+# Quick update (lightweight)
+/mpm-init update               # 30-day activity report
+
+# Resume work
+/mpm-init context --days 14    # Analyze last 2 weeks
+/mpm-init resume               # Show latest session from logs
+/mpm-init catchup              # Quick commit history
+
+# Full configuration
+/mpm-init --project-type web --framework react --comprehensive
+```
+
+## Implementation Notes
+
+**Delegation patterns:**
+- **Project init/update:** → Agentic Coder Optimizer agent
+- **context:** → PM → Research agent (structured analysis)
+- **catchup:** → Direct CLI (git log wrapper)
+- **resume:** → PM (reads logs, no delegation)
+
+**Token budgets:**
+- context analysis: 10-30s processing time
+- resume display: ~10-20k tokens
+- catchup: instant, minimal tokens
+
+See docs/commands/init.md for comprehensive documentation.

claude_mpm/commands/mpm-monitor.md

@@ -0,0 +1,31 @@
+---
+namespace: mpm/system
+command: monitor
+aliases: [mpm-monitor]
+migration_target: /mpm/system:monitor
+category: system
+description: Control monitoring server and dashboard
+---
+# /mpm-monitor
+
+Manage Socket.IO monitoring server for real-time dashboard.
+
+## Usage
+```
+/mpm-monitor [start|stop|restart|status|port] [options]
+```
+
+**Subcommands:**
+- `start`: Start server (auto-selects port 8765-8785)
+- `stop`: Stop running server
+- `status`: Show server status
+- `port <PORT>`: Start on specific port
+
+**Key Options:**
+- `--port PORT`: Specific port
+- `--force`: Force kill to reclaim port
+- `--foreground`: Run in foreground (default: background)
+
+Dashboard: http://localhost:8766
+
+See docs/commands/monitor.md for details.

claude_mpm/commands/mpm-organize.md

@@ -0,0 +1,120 @@
+---
+namespace: mpm/system
+command: organize
+aliases: [mpm-organize]
+migration_target: /mpm/system:organize
+category: system
+description: Organize project files with intelligent consolidation
+---
+# /mpm-organize
+
+Organize ALL project files with intelligent detection, consolidation, and pruning.
+
+## Usage
+```
+/mpm-organize [--dry-run] [--force] [options]
+```
+
+**Delegates to Project Organizer agent** for comprehensive file organization.
+
+## Scope
+
+**Default:** Organizes ALL project files
+- Documentation (.md, .rst, .txt)
+- Source code (proper module structure)
+- Tests (organized test suites)
+- Scripts (scripts/ directory)
+- Configuration (appropriate locations)
+
+**Protected files (never moved):** README.md, package.json, pyproject.toml, Makefile, .gitignore, etc.
+
+## Key Options
+
+**Safety:**
+- `--dry-run`: Preview without changes (recommended first run)
+- `--force`: Proceed with uncommitted changes
+- `--no-backup`: Skip backup (not recommended)
+
+**Scope:**
+- `--docs-only`: Only documentation (legacy behavior)
+- `--code-only` / `--tests-only` / `--scripts-only`: Specific file types
+
+**Operations:**
+- `--consolidate-only`: Merge duplicates only
+- `--prune-only`: Remove stale files only
+- `--no-prune`: Keep all files (no deletions)
+
+## What It Does
+
+1. **Pattern Detection:** Scans for existing organization (PROJECT_ORGANIZATION.md, framework conventions)
+2. **Consolidation:** Merges duplicates (READMEs, guides, utilities)
+3. **Pruning:** Archives/removes stale content (>6 months old, empty files)
+4. **Categorization:** Sorts docs into research/user/developer
+5. **Safe Movement:** Uses `git mv` to preserve history
+6. **Backup:** Creates backup_project_YYYYMMDD_HHMMSS.tar.gz
+
+## Standard Structure
+
+```
+docs/
+├── research/        # Spikes, analysis, notes
+├── user/            # Guides, tutorials, FAQs
+└── developer/       # API docs, architecture, contributing
+
+src/<package>/       # Proper module structure
+tests/               # Mirrored source structure
+scripts/             # Automation tools
+config/              # Configuration (if needed)
+```
+
+## Examples
+
+```bash
+# Preview changes (recommended first)
+/mpm-organize --dry-run
+
+# Organize everything with backup
+/mpm-organize
+
+# Documentation only
+/mpm-organize --docs-only --dry-run
+
+# Consolidate without pruning
+/mpm-organize --consolidate-only --no-prune
+
+# Save report
+/mpm-organize --report /tmp/organize-report.md
+```
+
+## Expected Output
+
+```
+🔍 Analyzing project structure...
+✓ Detected PROJECT_ORGANIZATION.md - using project standards
+✓ Found 23 documentation files, 15 test files, 8 scripts
+
+📁 Proposed Changes:
+
+  Consolidate:
+    → Merge README_OLD.md + README_BACKUP.md → docs/user/README.md
+
+  Organize:
+    docs/research/ ← spike-oauth.md (from root)
+    tests/unit/ ← test_auth.py (from root)
+    scripts/ ← deploy.sh (from root)
+
+  Prune:
+    ✂ Remove TODO_2023.md (stale 18 months)
+
+📊 Summary: 8 to move, 2 to merge, 3 to prune
+```
+
+## Safety Features
+
+- Full project backup before changes
+- Git integration (preserves history)
+- Import validation (ensures moves won't break code)
+- Protected files never touched
+- Conservative pruning (archive when unsure)
+
+See docs/commands/organize.md for full documentation.

claude_mpm/commands/mpm-postmortem.md

@@ -0,0 +1,21 @@
+---
+namespace: mpm/analysis
+command: postmortem
+aliases: [mpm-postmortem]
+migration_target: /mpm/analysis:postmortem
+category: analysis
+description: Analyze session errors and suggest improvements
+---
+# /mpm-postmortem
+
+Analyze session errors and generate improvement suggestions.
+
+## Usage
+```
+/mpm-postmortem [--auto-fix] [--create-prs] [--dry-run]
+```
+
+Analyzes errors from: scripts, skills, agents, user code.
+Generates: fixes, updates, PR recommendations, suggestions.
+
+See docs/commands/postmortem.md for details.

claude_mpm/commands/mpm-session-resume.md

@@ -0,0 +1,30 @@
+---
+namespace: mpm/session
+command: resume
+aliases: [mpm-session-resume]
+migration_target: /mpm/session:resume
+category: session
+description: Load context from paused session
+---
+# /mpm-session-resume
+
+Load and display context from most recent paused session.
+
+## Usage
+```
+/mpm-resume
+```
+
+**What it shows:**
+- Session summary and time elapsed
+- Completed work and current tasks
+- Git context and recent commits
+- Next recommended actions
+
+**Session location:** `.claude-mpm/sessions/session-*.json`
+
+**Token usage:** ~20-40k tokens (10-20% of context budget)
+
+**Note:** Reads existing sessions (created automatically at 70% context). Does NOT create new files.
+
+See docs/features/session-auto-resume.md for details.

claude_mpm/commands/mpm-status.md

@@ -0,0 +1,20 @@
+---
+namespace: mpm/system
+command: status
+aliases: [mpm-status]
+migration_target: /mpm/system:status
+category: system
+description: Display Claude MPM system status
+---
+# /mpm-status
+
+Show MPM system status. Delegates to PM agent.
+
+## Usage
+```
+/mpm-status
+```
+
+Displays: version, services, agents, memory, configuration, project info.
+
+See docs/commands/status.md for details.