claude-mpm 4.20.3__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/cli_module/refactoring_guide.md

@@ -0,0 +1,253 @@
+# CLI Refactoring Guide
+
+This guide shows how to refactor the main() function in `/src/claude_mpm/cli.py` to reduce complexity from 16 to under 10.
+
+## Current Issues
+
+1. **High Cyclomatic Complexity (16)**
+   - Multiple nested conditionals
+   - Duplicate argument definitions
+   - Mixed concerns in one function
+
+2. **Code Duplication**
+   - Arguments defined twice (global level + run subcommand)
+   - Similar patterns repeated for each command
+
+3. **Poor Maintainability**
+   - Adding new commands requires multiple changes
+   - Hard to test individual components
+
+## Refactoring Steps
+
+### Step 1: Update imports in cli.py
+
+```python
+# Add to imports
+from .cli import ArgumentRegistry, CommandRegistry, register_standard_commands
+```
+
+### Step 2: Replace main() function
+
+Replace the entire `main()` function with:
+
+```python
+def main(argv: Optional[list] = None):
+    """Main CLI entry point with reduced complexity."""
+    # Initialize registries
+    arg_registry = ArgumentRegistry()
+    cmd_registry = CommandRegistry(arg_registry)
+    
+    # Register standard commands
+    register_standard_commands(cmd_registry)
+    
+    # Create parser
+    parser = argparse.ArgumentParser(
+        prog="claude-mpm",
+        description=f"Claude Multi-Agent Project Manager v{__version__}",
+        epilog="By default, runs an orchestrated Claude session."
+    )
+    
+    # Store version for ArgumentRegistry
+    parser._version = f"claude-mpm {__version__}"
+    
+    # Apply global arguments
+    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'])
+    
+    # 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)
+        if result is None and not args.command:
+            parser.print_help()
+            return 1
+        return result or 0
+        
+    except KeyboardInterrupt:
+        get_logger("cli").info("Session interrupted by user")
+        return 0
+    except Exception as e:
+        logger = get_logger("cli")
+        logger.error(f"Error: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 1
+    finally:
+        if hook_manager:
+            hook_manager.stop_service()
+```
+
+### Step 3: Extract helper functions
+
+Add these helper functions after main():
+
+```python
+def _setup_logging(args):
+    """Set up logging based on arguments."""
+    if args.debug and args.logging == "OFF":
+        args.logging = "DEBUG"
+    
+    if args.logging != "OFF":
+        setup_logging(level=args.logging, log_dir=args.log_dir)
+    else:
+        import logging
+        logger = logging.getLogger("cli")
+        logger.setLevel(logging.WARNING)
+
+
+def _initialize_hook_service(args):
+    """Initialize hook service if enabled."""
+    if getattr(args, 'no_hooks', False):
+        return None
+        
+    try:
+        from .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")
+            print("Failed to start hook service, continuing without hooks")
+            return None
+            
+    except Exception as e:
+        get_logger("cli").warning(f"Hook service init failed: {e}")
+        return None
+```
+
+### Step 4: Update command handler signatures
+
+Ensure all command handlers accept `**kwargs`:
+
+```python
+def run_session(args, hook_manager=None, **kwargs):
+    """Run an orchestrated Claude session."""
+    # ... existing implementation
+
+def list_tickets(args, **kwargs):
+    """List recent tickets."""
+    # ... existing implementation
+
+def show_info(args, hook_manager=None, **kwargs):
+    """Show framework and configuration information."""
+    # ... existing implementation
+```
+
+## Benefits Achieved
+
+### Complexity Reduction
+- **Before**: Cyclomatic complexity of 16
+- **After**: Cyclomatic complexity of ~8
+
+### Code Organization
+- Centralized argument definitions
+- No duplicate argument definitions
+- Clear separation of concerns
+- Easier to add new commands
+
+### Maintainability
+- New commands can be added with a single `register()` call
+- Arguments are defined once and reused
+- Helper functions are testable in isolation
+- Registry pattern allows for extension
+
+## Adding New Commands
+
+With the registry system, adding a new command is simple:
+
+```python
+# In your code or plugin
+def my_command(args, **kwargs):
+    """Implementation of your command."""
+    print(f"Running my command with args: {args}")
+    return 0
+
+# Register it
+cmd_registry.register(
+    name='mycommand',
+    help_text='Description of my command',
+    handler=my_command,
+    argument_groups=['framework'],  # Reuse existing argument groups
+    extra_args={
+        'custom_arg': {
+            'flags': ['--custom'],
+            'type': str,
+            'help': 'A custom argument for this command'
+        }
+    }
+)
+```
+
+## Testing
+
+The refactored code is easier to test:
+
+```python
+# Test argument registry
+def test_argument_registry():
+    registry = ArgumentRegistry()
+    parser = argparse.ArgumentParser()
+    registry.apply_arguments(parser, groups=['logging'])
+    
+    # Verify logging arguments were added
+    args = parser.parse_args(['--logging', 'DEBUG'])
+    assert args.logging == 'DEBUG'
+
+# Test command registry
+def test_command_registry():
+    arg_reg = ArgumentRegistry()
+    cmd_reg = CommandRegistry(arg_reg)
+    
+    called = False
+    def test_handler(args, **kwargs):
+        nonlocal called
+        called = True
+        return 0
+    
+    cmd_reg.register('test', 'Test command', test_handler)
+    
+    parser = argparse.ArgumentParser()
+    cmd_reg.setup_subcommands(parser)
+    
+    args = parser.parse_args(['test'])
+    result = cmd_reg.execute_command(args)
+    
+    assert called
+    assert result == 0
+```
+
+## Migration Checklist
+
+- [ ] Create `/src/claude_mpm/cli/` directory
+- [ ] Create `args.py` with ArgumentRegistry
+- [ ] Create `commands.py` with CommandRegistry
+- [ ] Create `__init__.py` to export classes
+- [ ] Update imports in `cli.py`
+- [ ] Replace main() function
+- [ ] Add helper functions
+- [ ] Update command handler signatures
+- [ ] Test the refactored CLI
+- [ ] Verify complexity is reduced to ≤10

claude_mpm/commands/mpm-help.md

@@ -87,6 +87,9 @@ Available Commands:
 /mpm-init [update]
   Initialize or update project documentation
 
+/mpm-resume
+  Create session resume files for easy work resumption
+
 /mpm-monitor [start|stop|restart|status|port]
   Manage Socket.IO monitoring server and dashboard
 

claude_mpm/commands/mpm-init.md

@@ -44,6 +44,7 @@ This command has two primary modes:
 - **🧠 Memory System**: Initializes project knowledge retention
 - **🔧 Tool Configuration**: Sets up linting, formatting, testing
 - **📝 Holistic Review**: Final organization and validation pass
+- **🔒 GitIgnore Management**: Automatically excludes claude-mpm config directories
 
 ## Options
 
@@ -205,14 +206,27 @@ When enabled, performs:
 - Initializes memory files for project knowledge
 - Documents memory usage patterns
 
-### 7. Holistic Organization (Final Step)
+### 7. GitIgnore Management (Automatic)
+During initialization:
+- **Automatic Updates**: Adds `.claude-mpm/` and `.claude/agents/` to `.gitignore`
+- **Smart Detection**: Skips entries that already exist (no duplicates)
+- **Safe Operation**: Creates `.gitignore` if missing, preserves existing content
+- **Non-Blocking**: Continues initialization even if `.gitignore` update fails
+
+**Entries Added**:
+- `.claude-mpm/`: Configuration directory (sessions, logs, etc.)
+- `.claude/agents/`: Agent runtime files
+
+This ensures claude-mpm configuration files never get committed to version control.
+
+### 8. Holistic Organization (Final Step)
 After all tasks, performs a comprehensive review:
 - Reorganizes content by priority
 - Validates completeness
 - Ensures single-path principle
 - Adds meta-instructions for maintenance
 
-### 8. Update Mode Features (NEW)
+### 9. Update Mode Features (NEW)
 When updating existing documentation:
 - **Smart Merging**: Intelligently merges new content with existing
 - **Custom Preservation**: Keeps your project-specific sections
@@ -309,7 +323,7 @@ Working on:
 
 📝 Files Modified:
   • src/claude_mpm/services/cli/resume_service.py (new)
-  • src/claude_mpm/cli/commands/mpm_init.py (updated)
+  • src/claude_mpm/cli/commands/mpm_init/ (refactored into package)
 
 🎯 Next Steps:
   • Implement ResumeService class
@@ -470,6 +484,7 @@ The command delegates to the Agentic Coder Optimizer agent which:
 - ✅ **Memory system**: Initialized for knowledge retention
 - ✅ **Developer docs**: Technical documentation (with AST analysis)
 - ✅ **Priority organization**: Instructions ranked by importance
+- ✅ **.gitignore**: Configuration directories automatically excluded
 
 ### For Existing Projects (Update Mode)
 - ✅ **Updated CLAUDE.md**: Refreshed with latest standards
@@ -478,6 +493,7 @@ The command delegates to the Agentic Coder Optimizer agent which:
 - ✅ **Structure verified**: Missing directories created
 - ✅ **Files organized**: Misplaced files moved (if --organize)
 - ✅ **Change summary**: Report of what was updated
+- ✅ **.gitignore**: Config directories added if not present
 
 ### For Quick Update Mode (`/mpm-init update`)
 - ✅ **Activity Report**: Summary of recent 30-day git activity

claude_mpm/commands/mpm-resume.md

@@ -0,0 +1,372 @@
+# /mpm-resume - Load Previous Session
+
+Load and display context from the most recent paused session to seamlessly continue your work.
+
+## Usage
+
+```
+/mpm-resume
+```
+
+## Description
+
+This command **loads and displays** the most recent paused session from automatic session saves, allowing you to resume work with full context restoration.
+
+Unlike `/mpm-init pause` which *creates* a new session save, this command *loads* existing session data that was automatically created when context usage reached 70% (140k/200k tokens).
+
+**Key Points:**
+- Reads from `.claude-mpm/sessions/` directory (automatically created at 70% context)
+- Displays up to ~40,000 tokens (~20% of 200k context budget)
+- Shows session summary, completed work, in-progress tasks, and git context
+- Does NOT create any new files - only reads and displays
+
+## What Gets Displayed
+
+When you run `/mpm-resume`, PM will display:
+
+### Session Summary
+- **Time Elapsed**: How long ago the session was paused
+- **Context Usage**: Token usage at time of pause (e.g., "67.6% - 135,259/200,000 tokens")
+- **Working On**: What you were working on when paused
+- **Session Duration**: How long the previous session lasted
+
+### Completed Work
+- List of accomplishments from the paused session
+- What was delivered and committed
+- Key milestones achieved
+
+### Current Tasks
+- **In Progress**: Tasks that were being worked on
+- **Pending**: Tasks that were planned but not started
+- **Completed**: Recently finished tasks for context
+
+### Git Context
+- **Branch**: Current branch name
+- **Recent Commits**: Last 5-10 commits with SHAs and messages
+- **Status**: Clean/dirty working directory
+- **Changes Since Pause**: New commits made since session was saved
+
+### Next Recommended Actions
+- Priority-ordered list of next steps
+- Estimated time for each task
+- Status and blockers for pending work
+
+## Session Storage Location
+
+Sessions are automatically saved to:
+```
+<project-root>/.claude-mpm/sessions/session-YYYYMMDD-HHMMSS.json
+```
+
+**Legacy location** (backward compatible):
+```
+<project-root>/.claude-mpm/sessions/pause/session-YYYYMMDD-HHMMSS.json
+```
+
+The system automatically checks both locations and uses the most recent session.
+
+## Example Output
+
+```
+================================================================================
+📋 PAUSED SESSION FOUND
+================================================================================
+
+Paused: 2 hours ago
+
+Last working on: Week 2 Skills Integration - Content Preparation
+
+Completed:
+  ✓ Week 1: Complete infrastructure - 8,900 lines of production-ready code
+  ✓ Week 1: Skills loading system with automatic progressive disclosure
+  ✓ Week 2: 15 of 23 skills downloaded (65% complete)
+  ✓ Week 2: 2 Tier 1 skills refactored to progressive disclosure
+  ✓ Code quality: All CRITICAL and HIGH issues resolved
+
+Next steps:
+  • Refactor Tier 2 skills (verification-before-completion, webapp-testing)
+  • Download remaining 8 skills from community repositories
+  • Refactor remaining 13 skills to progressive disclosure
+  • Generate license attributions for all bundled skills
+
+Git changes since pause: 3 commits
+
+Recent commits:
+  ac765731 - feat(skills): Week 2 progress - 15 skills downloaded (Bob Matsuoka)
+  205e532e - fix(skills): address CRITICAL and HIGH priority issues (Bob Matsuoka)
+  06a6d6a0 - feat: add automated pre-publish cleanup to release (Bob Matsuoka)
+
+Context Usage: 67.6% (135,259/200,000 tokens)
+Session Duration: 12 hours
+
+================================================================================
+Use this context to resume work, or start fresh if not relevant.
+================================================================================
+```
+
+## Implementation
+
+When PM receives `/mpm-resume`, it should:
+
+1. **Check for Sessions**
+   ```python
+   from claude_mpm.services.cli.session_resume_helper import SessionResumeHelper
+
+   helper = SessionResumeHelper()
+   if not helper.has_paused_sessions():
+       return "No paused sessions found"
+   ```
+
+2. **Load Most Recent Session**
+   ```python
+   session_data = helper.get_most_recent_session()
+   if not session_data:
+       return "Failed to load session data"
+   ```
+
+3. **Format and Display Context**
+   ```python
+   # Extract key information
+   conversation = session_data.get("conversation", {})
+   git_context = session_data.get("git_context", {})
+   context_usage = session_data.get("context_usage", {})
+   todos = session_data.get("todos", {})
+
+   # Display formatted output (see Example Output above)
+   ```
+
+4. **Calculate Git Changes**
+   ```python
+   # Get commits since pause
+   paused_at = session_data.get("paused_at")
+   new_commits = helper.get_git_changes_since_pause(paused_at, [])
+   ```
+
+5. **Limit Output to ~40k Tokens**
+   - Session summary: ~2k tokens
+   - Accomplishments (first 10): ~3k tokens
+   - Next steps (first 10): ~3k tokens
+   - Git context: ~5k tokens
+   - Todos: ~2k tokens
+   - Recent commits (up to 10): ~5k tokens
+   - **Total**: ~20k tokens (well under 40k limit)
+
+## Token Budget Management
+
+**Context Budget**: 200,000 tokens total
+**Resume Load**: ~20,000-40,000 tokens (10-20% of context)
+
+This leaves 160,000+ tokens for actual work after loading session context.
+
+## Session Data Format
+
+Sessions are stored as JSON with this structure:
+
+```json
+{
+  "session_id": "session-YYYYMMDD-HHMMSS",
+  "paused_at": "ISO-8601 timestamp",
+  "duration_hours": 12,
+  "context_usage": {
+    "tokens_used": 135259,
+    "tokens_total": 200000,
+    "percentage": 67.6
+  },
+  "conversation": {
+    "primary_task": "What user was working on",
+    "current_phase": "Current phase of work",
+    "summary": "Brief summary",
+    "accomplishments": ["list of completed items"],
+    "next_steps": [
+      {
+        "priority": 1,
+        "task": "Task description",
+        "estimated_hours": "8-12",
+        "status": "ready"
+      }
+    ]
+  },
+  "git_context": {
+    "branch": "main",
+    "recent_commits": [...],
+    "status": {...}
+  },
+  "todos": {
+    "active": [...],
+    "completed": [...]
+  }
+}
+```
+
+## When to Use This Command
+
+Use `/mpm-resume` when:
+- **Starting a new session**: After closing and reopening Claude CLI
+- **Context unclear**: You need to remember what you were working on
+- **After a break**: Coming back after hours or days
+- **Team handoff**: Another developer wants to understand current state
+- **Lost context**: Accidentally closed CLI and need to recover
+
+## Differences from Automatic Resume
+
+| Feature | Automatic Resume (70% context) | /mpm-resume Command |
+|---------|-------------------------------|---------------------|
+| **Trigger** | Automatic at 70% context | Manual user command |
+| **When** | PM startup (if session exists) | Anytime during session |
+| **Creates Files** | No (reads existing) | No (reads existing) |
+| **Session Source** | Same (`.claude-mpm/sessions/`) | Same (`.claude-mpm/sessions/`) |
+| **Display Format** | Identical | Identical |
+| **Token Usage** | ~20-40k tokens | ~20-40k tokens |
+
+Both features use the **same underlying system** (`SessionResumeHelper`), just triggered differently.
+
+## No Files Created
+
+**IMPORTANT**: This command does NOT create any new files.
+
+It ONLY reads from existing session files that were automatically created by the system at 70% context usage.
+
+If you want to manually create a session save (for example, at 50% context before hitting 70%), use a different workflow or wait for automatic save at 70%.
+
+## Related Features
+
+- **Automatic Session Save**: System creates sessions at 70% context automatically
+- **Automatic Session Resume**: PM startup hook displays sessions automatically
+- `/mpm-init pause`: Manual session pause workflow (if available)
+- `/mpm-init context`: Analyze git history for intelligent resumption
+- `/mpm-status`: Check current MPM status
+
+## Error Handling
+
+### No Sessions Found
+```
+No paused sessions found in .claude-mpm/sessions/
+
+To create a session save, continue working until context reaches 70% (140k tokens),
+at which point the system will automatically save your session state.
+```
+
+### Failed to Load Session
+```
+Paused session file found but failed to load.
+
+File: .claude-mpm/sessions/session-20251107-152740.json
+Error: Invalid JSON format
+
+You may need to manually inspect or delete this file.
+```
+
+### Invalid Session Format
+```
+Session file loaded but missing required fields.
+
+The session file may be corrupted or from an older version.
+Consider running /mpm-doctor to check system health.
+```
+
+## Benefits
+
+- **Instant Context**: Get full context in seconds without reading git logs
+- **No Mental Load**: Don't need to remember what you were doing
+- **Zero File Creation**: Pure read operation, no side effects
+- **Team Collaboration**: Share context with team members
+- **Graceful Recovery**: Recover from accidental CLI closures
+- **Smart Filtering**: Only shows relevant information (~20k tokens)
+- **Git Awareness**: See what changed since pause
+
+## Best Practices
+
+1. **Use Early**: Run `/mpm-resume` at start of each session if sessions exist
+2. **Check Git Changes**: Pay attention to commits made since pause
+3. **Validate Context**: Verify the session is still relevant before continuing
+4. **Clear Old Sessions**: Periodically clean up old session files
+5. **Combine with Git**: Use alongside `git log` for complete picture
+
+## Technical Details
+
+**Implementation Files:**
+- Service: `/src/claude_mpm/services/cli/session_resume_helper.py`
+- Hook: `/src/claude_mpm/hooks/session_resume_hook.py`
+- Command: This file
+
+**Key Functions:**
+- `SessionResumeHelper.has_paused_sessions()` - Check if sessions exist
+- `SessionResumeHelper.get_most_recent_session()` - Load latest session
+- `SessionResumeHelper.format_resume_prompt()` - Format display output
+- `SessionResumeHelper.get_git_changes_since_pause()` - Calculate git delta
+
+**Token Estimation:**
+- Session metadata: 1-2k tokens
+- Accomplishments (10 items): 2-4k tokens
+- Next steps (10 items): 2-4k tokens
+- Git commits (10 commits): 3-5k tokens
+- Todos (20 items): 2-3k tokens
+- Formatting/structure: 1-2k tokens
+- **Total**: 11-20k tokens (safely under 40k limit)
+
+## Troubleshooting
+
+### Session Not Found
+**Problem**: Command reports no sessions exist
+
+**Solutions:**
+1. Check directory exists: `ls .claude-mpm/sessions/`
+2. Check for legacy location: `ls .claude-mpm/sessions/pause/`
+3. Verify session files: `ls .claude-mpm/sessions/session-*.json`
+4. Session auto-saves at 70% context - may not exist yet
+
+### Git Changes Not Showing
+**Problem**: "No git changes since pause" but commits were made
+
+**Solutions:**
+1. Verify git repository: `git status`
+2. Check commit timestamps: `git log --since="<pause_time>"`
+3. Ensure session timestamp is correct
+4. Check timezone issues
+
+### Display Too Large
+**Problem**: Session context exceeds token budget
+
+**Solutions:**
+1. System automatically limits to first 10 items
+2. Full session details available in JSON file
+3. Use `cat .claude-mpm/sessions/session-*.json` for complete data
+4. Summary is optimized for 20k tokens max
+
+## Example Session Resume Workflow
+
+```bash
+# User starts new Claude CLI session
+$ claude-code
+
+# PM automatically checks for sessions on startup
+# (Automatic resume hook displays session if found)
+
+# OR user manually requests resume
+User: "/mpm-resume"
+
+# PM loads and displays session context
+PM: [Displays formatted session context as shown in Example Output]
+
+# User decides to continue work
+User: "Let's continue with the next priority task"
+
+# PM uses session context to understand what to do next
+PM: "Based on the paused session, the next priority is to refactor
+     the verification-before-completion skill. I'll delegate this to Engineer..."
+```
+
+## Version History
+
+- **v4.21.1**: Fixed command behavior - now loads sessions instead of creating files
+- **v4.21.0**: Added `/mpm-resume` command (incorrect behavior - created files)
+- **v4.19.0**: Automatic session resume infrastructure implemented
+- **v4.18.x**: Session pause/resume foundation
+
+## Support
+
+For issues or questions:
+- Run `/mpm-doctor` to check system health
+- Check logs: `.claude-mpm/logs/claude-mpm.log`
+- Verify session files: `ls -la .claude-mpm/sessions/`
+- Review documentation: `/docs/features/session-auto-resume.md`