claude-mpm 4.7.3__py3-none-any.whl → 4.7.4__py3-none-any.whl

claude_mpm/commands/mpm-init.md

@@ -1,4 +1,4 @@
-# /mpm-init
+# /mpm-init [update]
 
 Initialize or intelligently update your project for optimal use with Claude Code and Claude MPM using the Agentic Coder Optimizer agent.
 
@@ -6,8 +6,9 @@ Initialize or intelligently update your project for optimal use with Claude Code
 
 ```
 /mpm-init                      # Auto-detects and offers update or create
+/mpm-init update               # Lightweight update based on recent git activity
 /mpm-init --review             # Review project state without changes
-/mpm-init --update             # Update existing CLAUDE.md
+/mpm-init --update             # Full update of existing CLAUDE.md
 /mpm-init --organize           # Organize project structure
 /mpm-init --force              # Force recreate from scratch
 /mpm-init --project-type web --framework react
@@ -18,6 +19,8 @@ Initialize or intelligently update your project for optimal use with Claude Code
 
 This command delegates to the Agentic Coder Optimizer agent to establish clear, single-path project standards for documentation, tooling, and workflows.
 
+**Quick Update Mode**: Running `/mpm-init update` performs a lightweight update focused on recent git activity. It analyzes recent commits, generates an activity report, and updates documentation with minimal changes. Perfect for quick refreshes after development sprints.
+
 **Smart Update Mode**: When CLAUDE.md exists, the command automatically offers to update rather than recreate, preserving your custom content while refreshing standard sections. Previous versions are archived in `docs/_archive/` for safety.
 
 ## Features
@@ -135,6 +138,14 @@ When updating existing documentation:
 ```
 Analyzes project and offers appropriate action (create/update/review).
 
+### Quick Update (Lightweight)
+```bash
+/mpm-init update
+```
+Fast update based on recent 30-day git activity. Generates activity report and updates docs with minimal changes.
+
+**Note**: Typing `/mpm-init update` executes `claude-mpm mpm-init --quick-update` automatically.
+
 ### Review Project State
 ```bash
 /mpm-init --review
@@ -173,10 +184,26 @@ Quick initialization without code analysis.
 
 ## Implementation
 
-This command executes:
+**IMPORTANT**: This slash command accepts an optional `update` argument for quick updates.
+
+**Argument Processing**:
+- When you type `/mpm-init update`, Claude executes `claude-mpm mpm-init --quick-update`
+- When you type `/mpm-init` (no argument), Claude executes standard mode
+- The slash command handler automatically maps the `update` argument to the `--quick-update` flag
+
+This command routes between different modes:
+
+**Quick Update Mode** (`/mpm-init update`):
+```bash
+claude-mpm mpm-init --quick-update
+```
+This triggers a lightweight update that analyzes recent git activity (30 days) and generates an activity report.
+
+**Standard Mode** (`/mpm-init`):
 ```bash
 claude-mpm mpm-init [options]
 ```
+This triggers the full initialization or smart update flow.
 
 The command delegates to the Agentic Coder Optimizer agent which:
 1. Analyzes your project structure
@@ -187,6 +214,12 @@ The command delegates to the Agentic Coder Optimizer agent which:
 6. Performs AST analysis (if enabled)
 7. Organizes everything with priority rankings
 
+**Quick Update Mode** performs:
+1. Git history analysis (last 30 days)
+2. Recent activity report generation
+3. Lightweight documentation updates
+4. Change summary for PM memory
+
 ## Expected Output
 
 ### For New Projects
@@ -206,12 +239,23 @@ The command delegates to the Agentic Coder Optimizer agent which:
 - ✅ **Files organized**: Misplaced files moved (if --organize)
 - ✅ **Change summary**: Report of what was updated
 
+### For Quick Update Mode (`/mpm-init update`)
+- ✅ **Activity Report**: Summary of recent 30-day git activity
+- ✅ **Recent Commits**: List of commits with authors and dates
+- ✅ **Changed Files**: Files with most modifications
+- ✅ **Active Branches**: Current and recent branch activity
+- ✅ **Lightweight Doc Updates**: Append activity notes to CLAUDE.md
+- ✅ **PM Memory Update**: Recommendations for project manager
+- ✅ **Quick Check**: Verify CLAUDE.md freshness without full regeneration
+
 ## Notes
 
+- **Quick Update vs Full Update**: Use `/mpm-init update` for fast activity-based updates (30 days), or `/mpm-init --update` for comprehensive doc refresh
 - **Smart Mode**: Automatically detects existing CLAUDE.md and offers update vs recreate
 - **Safe Updates**: Previous versions always archived before updating
 - **Custom Content**: Your project-specific sections are preserved by default
 - **Git Integration**: Analyzes recent commits to understand project evolution
+- **Argument Processing**: The slash command processes the `update` argument and routes to `--quick-update` flag
 - The command uses the Agentic Coder Optimizer agent for implementation
 - AST analysis is enabled by default for comprehensive documentation
 - Priority rankings help AI agents focus on critical instructions first

claude_mpm/commands/mpm-monitor.md

@@ -0,0 +1,409 @@
+# Manage Socket.IO monitoring server
+
+Control the Claude MPM monitoring server that powers the real-time dashboard interface for event tracking and project visualization.
+
+## 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
+```
+
+### 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
+
+### 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
+
+### 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
+
+### 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

claude_mpm/commands/mpm-organize.md

@@ -15,7 +15,9 @@ Organize your project files into proper directories using intelligent pattern de
 
 This slash command delegates to the **Project Organizer agent** to perform thorough project housekeeping. The agent analyzes your project structure, detects existing patterns and framework conventions, then organizes files into proper directories following best practices.
 
-**Smart Organization**: The agent first checks CLAUDE.md for project-specific organization guidelines. If not found, it applies framework-specific conventions and industry best practices.
+**Smart Organization**: The agent follows the official [Project Organization Standard](../../../docs/reference/PROJECT_ORGANIZATION.md), which defines comprehensive organization rules for Claude MPM projects. It also checks CLAUDE.md for project-specific guidelines and respects framework-specific conventions.
+
+**Standard Documentation**: After organizing, this command ensures the organization standard is documented and accessible at `docs/reference/PROJECT_ORGANIZATION.md` with proper linking from CLAUDE.md.
 
 ## Features
 
@@ -47,21 +49,26 @@ This slash command delegates to the **Project Organizer agent** to perform thoro
 
 ## What This Command Does
 
-### 1. CLAUDE.md Analysis
+### 1. Organization Standard Verification
+- Ensures `docs/reference/PROJECT_ORGANIZATION.md` exists and is current
+- Creates or updates the standard if needed
+- Links the standard from CLAUDE.md for easy reference
+
+### 2. CLAUDE.md Analysis
 - Checks for existing organization guidelines
 - Extracts project-specific rules and conventions
 - Identifies priority areas for organization
 
-### 2. Project Structure Detection
+### 3. Project Structure Detection
 - Scans directory hierarchy and patterns
 - Identifies naming conventions (camelCase, kebab-case, snake_case)
 - Maps current file type locations
 - Detects framework-specific conventions (Next.js, Django, Rails, etc.)
 - Determines organization type (feature/type/domain-based)
 
-### 3. File Organization Strategy
+### 4. File Organization Strategy
 
-The agent organizes files into standard directories:
+The agent organizes files into standard directories per [PROJECT_ORGANIZATION.md](../../../docs/reference/PROJECT_ORGANIZATION.md):
 
 ```
 docs/           # All documentation files (*.md, guides, architecture)
@@ -72,7 +79,7 @@ src/            # Source code following framework conventions
 .claude/        # Claude MPM configuration and agents
 ```
 
-### 4. Framework-Specific Handling
+### 5. Framework-Specific Handling
 
 **Next.js Projects**:
 - Respects `pages/`, `app/`, `public/`, API routes
@@ -93,7 +100,7 @@ src/            # Source code following framework conventions
 - Detects and respects framework conventions
 - Applies appropriate organizational patterns
 
-### 5. Safe File Movement
+### 6. Safe File Movement
 
 For each file to be moved:
 1. Analyzes file purpose and dependencies
@@ -102,14 +109,14 @@ For each file to be moved:
 4. Updates import paths in affected files
 5. Validates build still works
 
-### 6. Backup Creation
+### 7. Backup Creation
 
 Before major reorganization:
 ```bash
 backup_YYYYMMDD_HHMMSS.tar.gz  # Complete project backup
 ```
 
-### 7. Import Path Updates
+### 8. Import Path Updates
 
 Automatically updates:
 - Python imports (`from old.path import X` → `from new.path import X`)
@@ -117,7 +124,7 @@ Automatically updates:
 - Relative path references
 - Configuration file paths
 
-### 8. Organization Report
+### 9. Organization Report
 
 Generates detailed report including:
 - Files moved and their new locations
@@ -274,6 +281,12 @@ Use `/mpm-organize` when:
 - Follows guidelines in CLAUDE.md when available
 - Falls back to framework conventions and best practices
 
+## Related Documentation
+
+- **[Project Organization Standard](../../../docs/reference/PROJECT_ORGANIZATION.md)**: Comprehensive organization rules and guidelines
+- **[Project Structure](../../../docs/developer/STRUCTURE.md)**: Authoritative file organization reference
+- **[CLAUDE.md](../../../CLAUDE.md)**: Development guidelines with organization quick reference
+
 ## Related Commands
 
 - `/mpm-init`: Initialize or update project documentation and structure

claude_mpm/dashboard/static/built/shared/page-structure.js

@@ -7,7 +7,6 @@ export class PageStructure {
     constructor() {
         this.pages = [
             { id: 'main', label: '📈 Main Dashboard', href: '/static/' },
-            { id: 'monitors', label: '📋 All Monitors', href: '/static/monitors-index.html' },
             { id: 'events', label: '📊 Events', href: '/static/events.html' },
             { id: 'agents', label: '🤖 Agents', href: '/static/agents.html' },
             { id: 'tools', label: '🔧 Tools', href: '/static/tools.html' },
@@ -24,7 +23,6 @@ export class PageStructure {
         if (path.includes('tools.html')) return 'tools';
         if (path.includes('files.html')) return 'files';
         if (path.includes('activity.html')) return 'activity';
-        if (path.includes('monitors-index.html')) return 'monitors';
         if (path.includes('index.html') || path.endsWith('/static/') || path.endsWith('/')) return 'main';
 
         return 'main';