claude-mpm 5.1.9__py3-none-any.whl → 5.4.48__py3-none-any.whl

claude_mpm/commands/mpm-monitor.md

@@ -4,415 +4,28 @@ command: monitor
 aliases: [mpm-monitor]
 migration_target: /mpm/system:monitor
 category: system
-deprecated_aliases: []
-description: Control Claude MPM monitoring server for real-time dashboard interface
+description: Control monitoring server and dashboard
 ---
-# Manage Socket.IO monitoring server
+# /mpm-monitor
 
-Control the Claude MPM monitoring server that powers the real-time dashboard interface for event tracking and project visualization.
+Manage Socket.IO monitoring server for real-time dashboard.
 
 ## Usage
-
-```
-/mpm-monitor [subcommand] [options]
-```
-
-## Description
-
-This slash command manages the Socket.IO monitoring server that provides real-time event tracking and visualization through a web-based dashboard. The monitoring server listens for events from the Claude MPM framework and displays them in an interactive interface accessible via web browser.
-
-The monitoring server typically runs on port 8765 (or auto-selects an available port in the range 8765-8785) and provides a real-time dashboard at `http://localhost:8765`.
-
-## Available Subcommands
-
-### Start Monitoring Server
-Start the Socket.IO monitoring server to enable real-time event tracking.
-
-```
-/mpm-monitor start [--port PORT] [--host HOST] [--dashboard] [--dashboard-port PORT] [--foreground] [--background] [--force] [--no-reclaim]
-```
-
-**Options:**
-- `--port PORT`: Specific port to start server on (auto-selects if not specified, range: 8765-8785)
-- `--host HOST`: Host to bind to (default: localhost)
-- `--dashboard`: Enable web dashboard interface (enabled by default)
-- `--dashboard-port PORT`: Dashboard port number (default: 8766)
-- `--foreground`: Run server in foreground mode (blocks terminal)
-- `--background`: Run server in background/daemon mode (default behavior)
-- `--force`: Force kill daemon processes to reclaim ports (use with caution)
-- `--no-reclaim`: Don't automatically reclaim ports from debug scripts
-
-**Examples:**
-```
-/mpm-monitor start
-/mpm-monitor start --port 8765
-/mpm-monitor start --port 8770 --dashboard --dashboard-port 8771
-/mpm-monitor start --foreground
-/mpm-monitor start --force --port 8765
-```
-
-**Default Behavior:**
-- Runs in background/daemon mode
-- Auto-selects first available port in range 8765-8785
-- Enables web dashboard on port 8766
-- Gracefully reclaims ports from debug scripts (not daemons)
-
-### Stop Monitoring Server
-Stop a running monitoring server instance.
-
-```
-/mpm-monitor stop [--port PORT] [--force]
-```
-
-**Options:**
-- `--port PORT`: Port of server to stop (stops all instances if not specified)
-- `--force`: Force stop even if clients are connected
-
-**Examples:**
-```
-/mpm-monitor stop
-/mpm-monitor stop --port 8765
-/mpm-monitor stop --force
-```
-
-**Behavior:**
-- Without `--port`: Stops all running monitoring server instances
-- With `--port`: Stops only the server on specified port
-- Without `--force`: Gracefully disconnects clients before stopping
-- With `--force`: Immediately stops server regardless of client connections
-
-### Restart Monitoring Server
-Restart the monitoring server (stop and start in one operation).
-
-```
-/mpm-monitor restart [--port PORT] [--host HOST]
-```
-
-**Options:**
-- `--port PORT`: Port to restart on (uses previous port if not specified)
-- `--host HOST`: Host to bind to (default: localhost)
-
-**Examples:**
-```
-/mpm-monitor restart
-/mpm-monitor restart --port 8770
-/mpm-monitor restart --port 8765 --host 0.0.0.0
-```
-
-**Behavior:**
-- Stops existing server instance
-- Starts new instance with same or updated configuration
-- Preserves client connections where possible
-
-### Check Server Status
-Display status information about running monitoring servers.
-
-```
-/mpm-monitor status [--verbose] [--show-ports]
-```
-
-**Options:**
-- `--verbose`: Show detailed status information (process IDs, uptime, connections)
-- `--show-ports`: Show status of all ports in the range (8765-8785)
-
-**Examples:**
-```
-/mpm-monitor status
-/mpm-monitor status --verbose
-/mpm-monitor status --show-ports
-```
-
-**Status Information:**
-- Running server instances and their ports
-- Process IDs and uptime
-- Number of connected clients
-- Dashboard URLs
-- Port availability status (with --show-ports)
-
-### Start on Specific Port
-Start or restart monitoring server on a specific port (convenience command).
-
-```
-/mpm-monitor port <PORT> [--host HOST] [--force] [--no-reclaim]
-```
-
-**Arguments:**
-- `PORT`: Port number to use (required)
-
-**Options:**
-- `--host HOST`: Host to bind to (default: localhost)
-- `--force`: Force kill daemon processes to reclaim port (use with caution)
-- `--no-reclaim`: Don't automatically reclaim port from debug scripts
-
-**Examples:**
-```
-/mpm-monitor port 8765
-/mpm-monitor port 8770 --host 0.0.0.0
-/mpm-monitor port 8765 --force
-```
-
-**Behavior:**
-- If server already running on port: restarts it
-- If port is in use by another process: fails (unless --force)
-- Auto-reclaims ports from debug scripts (unless --no-reclaim)
-
-## Implementation
-
-This command executes:
-```bash
-claude-mpm monitor [subcommand] [options]
-```
-
-The slash command passes through to the actual CLI monitoring system, which manages Socket.IO server processes.
-
-## Monitoring Features
-
-### Real-Time Event Tracking
-The monitoring server captures and displays:
-- **Agent Events**: Task delegation, completion, errors
-- **Tool Usage**: File operations, bash commands, API calls
-- **System Events**: Server startup/shutdown, configuration changes
-- **Project Events**: File changes, git operations, test results
-- **Memory Operations**: Knowledge persistence, context updates
-- **WebSocket Events**: Client connections, disconnections, errors
-
-### Web Dashboard
-The dashboard interface provides:
-- **Live Event Stream**: Real-time event feed with filtering
-- **Project Overview**: Active agents, current tasks, system status
-- **Performance Metrics**: Event rates, processing times, error counts
-- **Event History**: Searchable log of past events
-- **Connection Status**: Client connections, server health
-- **Visualization**: Event timelines, agent activity graphs
-
-### Port Management
-The monitoring server implements smart port selection:
-- **Auto-Selection**: Finds first available port in range 8765-8785
-- **Port Reclamation**: Gracefully reclaims ports from debug scripts
-- **Conflict Resolution**: Detects and handles port conflicts
-- **Multi-Instance**: Supports multiple servers on different ports
-
-## Expected Output
-
-### Start Command Output
-```
-Starting Socket.IO monitoring server...
-
-✓ Server started successfully
-  - Server URL: http://localhost:8765
-  - Dashboard URL: http://localhost:8766
-  - Process ID: 12345
-  - Mode: background
-
-Monitoring server is ready for connections.
-Open http://localhost:8766 in your browser to view the dashboard.
-```
-
-### Stop Command Output
-```
-Stopping monitoring server...
-
-✓ Server on port 8765 stopped successfully
-  - Disconnected 3 clients gracefully
-  - Process 12345 terminated
-
-Monitoring server stopped.
-```
-
-### Status Command Output
-```
-Monitoring Server Status
-========================
-
-Active Servers: 1
-
-Server 1:
-  - Port: 8765
-  - Dashboard: http://localhost:8766
-  - Process ID: 12345
-  - Uptime: 2h 15m 30s
-  - Connected Clients: 3
-  - Status: Running
-
-Dashboard accessible at: http://localhost:8766
-```
-
-### Status with --verbose Output
-```
-Monitoring Server Status (Detailed)
-====================================
-
-Active Servers: 1
-
-Server 1:
-  - Port: 8765
-  - Host: localhost
-  - Dashboard: http://localhost:8766
-  - Dashboard Port: 8766
-  - Process ID: 12345
-  - Started: 2025-01-08 14:30:15
-  - Uptime: 2h 15m 30s
-  - Connected Clients: 3
-  - Events Processed: 1,247
-  - Average Event Rate: 0.17/sec
-  - Status: Running (Healthy)
-
-Client Connections:
-  1. Browser (127.0.0.1:54321) - Connected 2h 10m ago
-  2. CLI Monitor (127.0.0.1:54322) - Connected 1h 45m ago
-  3. External Tool (127.0.0.1:54323) - Connected 30m ago
-
-Dashboard accessible at: http://localhost:8766
-```
-
-### Status with --show-ports Output
-```
-Monitoring Server Status
-========================
-
-Active Servers: 1
-Available Ports: 19
-
-Port Status (8765-8785):
-  8765: ✓ RUNNING (PID 12345, 3 clients)
-  8766: • IN USE (Dashboard for 8765)
-  8767: ○ AVAILABLE
-  8768: ○ AVAILABLE
-  8769: ○ AVAILABLE
-  8770: ○ AVAILABLE
-  ... (additional ports)
-  8785: ○ AVAILABLE
-
-Legend:
-  ✓ RUNNING - Monitor server active
-  • IN USE - Used by another process
-  ○ AVAILABLE - Ready for use
-
-Dashboard accessible at: http://localhost:8766
-```
-
-### Error Output Examples
-```
-Error: Port 8765 is already in use by another process
-Suggestion: Use --port to specify a different port or --force to reclaim
-
-Error: Failed to start monitoring server
-Reason: Permission denied on port 8765
-Suggestion: Try a port > 1024 or run with appropriate permissions
-
-Error: Server on port 8765 is not running
-Suggestion: Use '/mpm-monitor start' to start the server
-```
-
-## Use Cases
-
-### Development Workflow
-1. **Start monitoring** before beginning development session
-2. **View dashboard** to track agent activity and events in real-time
-3. **Monitor errors** to catch issues as they occur
-4. **Stop monitoring** when done or to free resources
-
-### Debugging
-1. **Start with --verbose** to see detailed process information
-2. **Check status** to verify server is running and clients are connected
-3. **Review dashboard** to examine event history and error patterns
-4. **Restart** if server becomes unresponsive
-
-### Multiple Projects
-1. **Use --port** to run separate monitors for different projects
-2. **Check --show-ports** to see which ports are available
-3. **Manage multiple instances** independently
-
-### Production Monitoring
-1. **Start with --background** to run as daemon (default)
-2. **Configure --host 0.0.0.0** to allow remote access
-3. **Check status regularly** to ensure server health
-4. **Use --force carefully** only when necessary to reclaim ports
-
-## Troubleshooting
-
-### Port Already in Use
-```bash
-# Check what's using the port
-/mpm-monitor status --show-ports
-
-# Start on a different port
-/mpm-monitor start --port 8770
-
-# Or force reclaim (use cautiously)
-/mpm-monitor start --port 8765 --force
-```
-
-### Server Won't Start
-```bash
-# Check detailed status
-/mpm-monitor status --verbose
-
-# Try manual restart
-/mpm-monitor stop --force
-/mpm-monitor start
 ```
-
-### Dashboard Not Accessible
-```bash
-# Verify server is running
-/mpm-monitor status
-
-# Check dashboard port
-/mpm-monitor status --verbose
-
-# Restart with specific dashboard port
-/mpm-monitor restart --dashboard-port 8766
+/mpm-monitor [start|stop|restart|status|port] [options]
 ```
 
-### Multiple Servers Running
-```bash
-# Check all running servers
-/mpm-monitor status --show-ports
-
-# Stop all servers
-/mpm-monitor stop
-
-# Start single server
-/mpm-monitor start
-```
-
-## Related Commands
-
-- `/mpm-status`: Show overall system status including monitoring server
-- `/mpm-doctor`: Diagnose monitoring and server issues
-- `/mpm-config`: Configure monitoring server settings
-- `/mpm-init`: Initialize project with monitoring configuration
-
-## Notes
-
-- **Default Mode**: Server runs in background/daemon mode by default
-- **Port Range**: Auto-selects from 8765-8785 if not specified
-- **Dashboard**: Web interface is enabled by default on port 8766
-- **Graceful Shutdown**: Server attempts to disconnect clients gracefully on stop
-- **Force Reclaim**: The `--force` option should be used with caution as it kills processes
-- **Debug Scripts**: Ports are automatically reclaimed from debug scripts (not daemons) unless `--no-reclaim` is specified
-- **Multiple Instances**: You can run multiple monitoring servers on different ports for different projects
-- **Security**: By default, server only binds to localhost. Use `--host 0.0.0.0` for remote access (consider security implications)
-
-## Technical Details
+**Subcommands:**
+- `start`: Start server (auto-selects port 8765-8785)
+- `stop`: Stop running server
+- `status`: Show server status
+- `port <PORT>`: Start on specific port
 
-### Socket.IO Server
-- **Protocol**: Socket.IO 4.x with WebSocket transport
-- **Port Range**: 8765-8785 (auto-selection)
-- **Dashboard**: Static web application served on separate port
-- **Events**: Real-time bidirectional event streaming
-- **Clients**: Supports multiple simultaneous client connections
+**Key Options:**
+- `--port PORT`: Specific port
+- `--force`: Force kill to reclaim port
+- `--foreground`: Run in foreground (default: background)
 
-### Process Management
-- **Daemon Mode**: Background process with PID tracking
-- **Foreground Mode**: Blocking process (useful for debugging)
-- **Health Checks**: Automatic health monitoring
-- **Graceful Shutdown**: Clean client disconnection on stop
+Dashboard: http://localhost:8766
 
-### Port Allocation Strategy
-1. Check if requested port is available
-2. If not specified, scan range 8765-8785
-3. Detect port conflicts with existing processes
-4. Optionally reclaim ports from debug scripts (not daemons)
-5. Fail gracefully if no ports available
+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

@@ -4,120 +4,18 @@ command: postmortem
 aliases: [mpm-postmortem]
 migration_target: /mpm/analysis:postmortem
 category: analysis
-deprecated_aliases: []
 description: Analyze session errors and suggest improvements
 ---
-# Analyze session errors and suggest improvements
+# /mpm-postmortem
 
-Perform a comprehensive analysis of errors encountered during the current or previous session and generate actionable improvement suggestions.
+Analyze session errors and generate improvement suggestions.
 
 ## Usage
-
-```
-/mpm-postmortem [options]
 ```
-
-## Description
-
-The postmortem command analyzes errors from:
-- Script execution failures
-- Skill execution issues
-- Agent instruction problems
-- User code errors (analysis only)
-
-It categorizes errors, identifies root causes, and generates actionable improvements:
-- **Scripts**: Tests and fixes in place
-- **Skills**: Updates skill files with improvements
-- **MPM Agents**: Prepares PRs with rationale for remote agent repository
-- **User Code**: Provides suggestions without modification
-
-## Options
-
-- `--dry-run`: Preview analysis without making changes (default for destructive operations)
-- `--auto-fix`: Automatically apply fixes to scripts and skills
-- `--create-prs`: Create pull requests for agent improvements
-- `--session-id <id>`: Analyze specific session (default: current session)
-- `--format <format>`: Output format: terminal, json, markdown (default: terminal)
-- `--output <file>`: Save report to file
-- `--verbose`: Include detailed error traces and analysis
-
-## Examples
-
-```bash
-# Analyze current session
-/mpm-postmortem
-
-# Preview changes without applying
-/mpm-postmortem --dry-run
-
-# Auto-fix scripts and skills
-/mpm-postmortem --auto-fix
-
-# Create PRs for agent improvements
-/mpm-postmortem --create-prs
-
-# Analyze specific session
-/mpm-postmortem --session-id 2025-12-03-143000
-
-# Save detailed report
-/mpm-postmortem --verbose --output postmortem-report.md
+/mpm-postmortem [--auto-fix] [--create-prs] [--dry-run]
 ```
 
-## Expected Output
-
-```
-📊 Session Postmortem Analysis
-═══════════════════════════════
-
-Session: 2025-12-03-143000
-Duration: 45 minutes
-Errors Found: 3
-
-🔧 Script Errors (1)
-─────────────────────
-• manage_version.py line 42: KeyError 'version'
-  Root Cause: Missing default value handling for optional configuration
-  Fix: Add fallback to default value when key not present
-  Status: Fixed ✓
-
-📚 Skill Errors (0)
-──────────────────
-No skill errors detected
-
-🤖 Agent Improvements (2)
-──────────────────────────
-• ticketing agent: Timeout on large ticket lists
-  Issue: Default timeout too short for projects with 500+ tickets
-  Improvement: Add pagination support and increase timeout threshold
-  PR: Created #123 (awaiting review)
-
-• engineer agent: Type validation missing for tool parameters
-  Issue: Invalid parameters passed to Edit tool causing failures
-  Improvement: Add parameter validation before tool invocation
-  Status: Ready to create PR (use --create-prs)
-
-💡 User Code Suggestions (0)
-────────────────────────────
-No user code issues detected
-
-📈 Summary
-──────────
-Total Errors: 3
-Fixed: 1
-PRs Created: 1
-Suggestions: 1
-```
-
-## Safety Features
-
-- **Dry-run by default**: Preview changes before applying
-- **Confirmation prompts**: Verify before creating PRs
-- **Backup before modifications**: Automatic backup of modified files
-- **Rollback capability**: Restore previous versions if needed
-- **Git integration**: Check for uncommitted changes before modifications
-
-## Related Commands
+Analyzes errors from: scripts, skills, agents, user code.
+Generates: fixes, updates, PR recommendations, suggestions.
 
-- `/mpm-doctor`: Diagnose installation and configuration issues
-- `/mpm-session-resume`: Resume previous session with context
-- `/mpm-status`: View current system status
+See docs/commands/postmortem.md for details.