claude-mpm 4.0.34__tar.gz → 4.1.0__tar.gz

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/CLAUDE.md

@@ -72,11 +72,12 @@ Following the TSK-0053 refactoring, Claude MPM features:
 # Full test suite
 ./scripts/run_all_tests.sh
 
-# Lint and type checks
+# Lint and type checks (catches duplicate imports!)
 ./scripts/run_lint.sh
 ```
 
 See [docs/QA.md](docs/QA.md) for detailed testing procedures.
+See [docs/LINTING.md](docs/LINTING.md) for linting configuration and duplicate import detection.
 
 ### Key System Components
 

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.0.34
+Version: 4.1.0
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -54,6 +54,11 @@ Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-import-order; extra == "dev"
+Requires-Dist: flake8-tidy-imports; extra == "dev"
+Requires-Dist: flake8-bugbear; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pylint>=3.0.0; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
@@ -133,6 +138,13 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 pip install claude-mpm
 ```
 
+Or with pipx (recommended for isolated installation):
+```bash
+pipx install claude-mpm
+# Configure MCP for pipx users:
+claude-mpm mcp-pipx-config
+```
+
 **That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
 
 ## Quick Usage
@@ -157,15 +169,17 @@ claude-mpm cleanup-memory
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
 
 
-## Architecture (v3.8.2+)
+## Architecture (v4.1.0+)
 
-Following the TSK-0053 refactoring, Claude MPM features:
+Following continuous improvements through v4.1.0, Claude MPM features:
 
-- **Service-Oriented Architecture**: Five specialized service domains
+- **Service-Oriented Architecture**: Five specialized service domains with Socket.IO stability improvements
 - **Interface-Based Contracts**: All services implement explicit interfaces
 - **Dependency Injection**: Service container with automatic resolution
 - **50-80% Performance Improvement**: Through lazy loading and intelligent caching
 - **Enhanced Security**: Comprehensive input validation and sanitization framework
+- **Improved Monitoring**: Enhanced dashboard with hierarchical agent display
+- **Socket.IO Stability**: Major reliability improvements for real-time communication
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.
 
@@ -254,11 +268,15 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 ### API Documentation
 Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
 
-## Recent Updates (v3.8.2)
+## Recent Updates (v4.1.0)
+
+**Socket.IO Stability Improvements**: Major reliability enhancements for real-time communication with improved error handling and connection management.
+
+**Project Organization**: Comprehensive cleanup and reorganization with structured script directories for better maintainability.
 
-**Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
+**Documentation Consolidation**: Streamlined documentation structure with consolidated guides and improved navigation.
 
-**Process Management Improvements**: Enhanced hook system reliability with automatic process cleanup, timeout protection, and orphan process monitoring to prevent resource leaks.
+**Agent Hierarchy Display**: Enhanced dashboard with hierarchical agent display showing PM at top level with visual distinction for implied vs explicit nodes.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/README.md

@@ -23,6 +23,13 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 pip install claude-mpm
 ```
 
+Or with pipx (recommended for isolated installation):
+```bash
+pipx install claude-mpm
+# Configure MCP for pipx users:
+claude-mpm mcp-pipx-config
+```
+
 **That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
 
 ## Quick Usage
@@ -47,15 +54,17 @@ claude-mpm cleanup-memory
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
 
 
-## Architecture (v3.8.2+)
+## Architecture (v4.1.0+)
 
-Following the TSK-0053 refactoring, Claude MPM features:
+Following continuous improvements through v4.1.0, Claude MPM features:
 
-- **Service-Oriented Architecture**: Five specialized service domains
+- **Service-Oriented Architecture**: Five specialized service domains with Socket.IO stability improvements
 - **Interface-Based Contracts**: All services implement explicit interfaces
 - **Dependency Injection**: Service container with automatic resolution
 - **50-80% Performance Improvement**: Through lazy loading and intelligent caching
 - **Enhanced Security**: Comprehensive input validation and sanitization framework
+- **Improved Monitoring**: Enhanced dashboard with hierarchical agent display
+- **Socket.IO Stability**: Major reliability improvements for real-time communication
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.
 
@@ -144,11 +153,15 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 ### API Documentation
 Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
 
-## Recent Updates (v3.8.2)
+## Recent Updates (v4.1.0)
+
+**Socket.IO Stability Improvements**: Major reliability enhancements for real-time communication with improved error handling and connection management.
+
+**Project Organization**: Comprehensive cleanup and reorganization with structured script directories for better maintainability.
 
-**Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
+**Documentation Consolidation**: Streamlined documentation structure with consolidated guides and improved navigation.
 
-**Process Management Improvements**: Enhanced hook system reliability with automatic process cleanup, timeout protection, and orphan process monitoring to prevent resource leaks.
+**Agent Hierarchy Display**: Enhanced dashboard with hierarchical agent display showing PM at top level with visual distinction for implied vs explicit nodes.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 

claude_mpm-4.1.0/VERSION

@@ -0,0 +1 @@
+4.1.0

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.0.34"
+version = "4.1.0"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -89,6 +89,11 @@ dev = [
     # Code formatting and linting
     "black",
     "flake8",
+    "flake8-import-order",
+    "flake8-tidy-imports",
+    "flake8-bugbear",
+    "ruff>=0.1.0",
+    "pylint>=3.0.0",
     "pre-commit",
 
     # Type checking
@@ -184,9 +189,58 @@ markers = [
 ]
 asyncio_mode = "auto"
 
+[tool.ruff]
+# Ruff configuration for duplicate import detection
+line-length = 88
+target-version = "py38"
+select = [
+    "F",     # Pyflakes
+    "E",     # pycodestyle errors  
+    "W",     # pycodestyle warnings
+    "I",     # isort
+    "F401",  # Unused imports
+    "F811",  # Redefinition (catches duplicate imports!)
+    "F821",  # Undefined name (catches scope issues!)
+    "F823",  # Local variable referenced before assignment
+]
+ignore = ["E203", "E501"]
+exclude = [
+    ".git", "__pycache__", ".venv", "venv", "build", "dist",
+    "*.egg-info", ".pytest_cache", ".mypy_cache", "node_modules"
+]
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401", "F403"]
+"tests/*" = ["F403", "F405"]
+
+[tool.pylint]
+# Pylint configuration for additional checks
+max-line-length = 88
+disable = [
+    "C0111",  # missing-docstring
+    "C0103",  # invalid-name
+    "R0903",  # too-few-public-methods
+    "R0913",  # too-many-arguments
+    "W0212",  # protected-access
+]
+# Enable duplicate code detection
+enable = [
+    "duplicate-code",
+    "reimported",
+    "import-self",
+    "cyclic-import",
+    "wrong-import-order",
+    "ungrouped-imports",
+    "wrong-import-position",
+]
+min-similarity-lines = 4
+ignore-comments = true
+ignore-docstrings = true
+ignore-imports = false
+
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.0.34"
+version = "4.1.0"
 version_files = [
     "VERSION",
     "src/claude_mpm/VERSION",

claude_mpm-4.1.0/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.1.0

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/src/claude_mpm/agents/INSTRUCTIONS.md

@@ -1,9 +1,9 @@
 <!-- FRAMEWORK_VERSION: 0010 -->
 <!-- LAST_MODIFIED: 2025-08-10T00:00:00Z -->
 
-# Claude Multi-Agent Project Manager Instructions
+# Claude Multi-Agent (Claude-MPM) Project Manager Instructions
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
+## 🔴 YOUR PRIME DIRECTIVE - MANDATORY DELEGATION 🔴
 
 **YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
 
@@ -97,6 +97,74 @@ You are a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized
 
 ## MCP Vector Search Integration
 
+## 🎫 MANDATORY TICKET TRACKING PROTOCOL 🎫
+
+**CRITICAL REQUIREMENT**: You MUST track ALL work using the integrated ticketing system. This is NOT optional.
+
+### Session Work Tracking Rules
+
+**At Session Start**:
+1. **ALWAYS create or update an ISS (Issue) ticket** for the current user request
+2. **Attach the ISS to an appropriate Epic (EP-)** or create new Epic if needed
+3. **Set ISS status to "in-progress"** when beginning work
+4. **Use ticket ID in all agent delegations** for traceability
+
+**During Work**:
+1. **Include ticket context in ALL delegations** to agents
+2. **Agents will create TSK (Task) tickets** for their implementation work
+3. **Update ISS ticket after each phase completion** with progress
+4. **Add comments to ticket for significant decisions or blockers**
+
+**At Work Completion**:
+1. **Update ISS ticket status to "done"** when all delegations complete
+2. **Add final summary comment** with outcomes and deliverables
+3. **Close the ticket** if no follow-up work is needed
+4. **Reference ticket ID in final response** to user
+
+### Ticket Creation Commands
+
+**When MCP Gateway is available**:
+```
+Use mcp__claude-mpm-gateway__ticket tool with operation: "create"
+```
+
+**When using delegation**:
+```
+Delegate to Ticketing Agent with clear instructions:
+- Create ISS for: [user request]
+- Parent Epic: [EP-XXXX or create new]
+- Priority: [based on urgency]
+- Description: [detailed context]
+```
+
+### Work Resumption via Tickets
+
+**Instead of session resume, use tickets for continuity**:
+1. Search for open ISS tickets: `operation: "list", status: "in-progress"`
+2. View ticket details: `operation: "view", ticket_id: "ISS-XXXX"`
+3. Resume work based on ticket history and status
+4. Continue updating the same ticket throughout the work
+
+### Ticket Hierarchy Enforcement
+
+```
+Epic (EP-XXXX) - Major initiative or multi-session work
+└── Issue (ISS-XXXX) - PM tracks user request here ← YOU CREATE THIS
+    ├── Task (TSK-XXXX) - Research Agent's work
+    ├── Task (TSK-XXXX) - Engineer Agent's work
+    ├── Task (TSK-XXXX) - QA Agent's work
+    └── Task (TSK-XXXX) - Documentation Agent's work
+```
+
+**REMEMBER**:
+- ✅ ALWAYS create ISS tickets for user requests
+- ✅ ALWAYS attach ISS to an Epic
+- ✅ ALWAYS update ticket status as work progresses
+- ✅ ALWAYS close tickets when work completes
+- ❌ NEVER work without an active ISS ticket
+- ❌ NEVER create TSK tickets (agents do this)
+- ❌ NEVER leave tickets in "in-progress" after completion
+
 ## Agent Response Format
 
 When completing tasks, all agents should structure their responses with:

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/src/claude_mpm/agents/OUTPUT_STYLE.md

@@ -5,17 +5,6 @@ description: Multi-Agent Project Manager orchestration mode for delegation and c
 
 You are Claude Multi-Agent PM, a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized agents.
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
-
-**YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
-
-Direct implementation is ABSOLUTELY PROHIBITED unless the user EXPLICITLY overrides with phrases like:
-- "do this yourself"
-- "don't delegate"
-- "implement directly"
-- "you do it"
-- "no delegation"
-
 ## Core Operating Rules
 
 **DEFAULT BEHAVIOR - ALWAYS DELEGATE**:

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/src/claude_mpm/agents/WORKFLOW.md

@@ -372,7 +372,11 @@ Delegate to Research when:
 - Architecture decisions needed
 - Domain knowledge required
 
-### Ticketing Agent Integration
+### 🔴 MANDATORY Ticketing Agent Integration 🔴
+
+**THIS IS NOT OPTIONAL - ALL WORK MUST BE TRACKED IN TICKETS**
+
+The PM MUST create and maintain tickets for ALL user requests. Failure to track work in tickets is a CRITICAL VIOLATION of PM protocols.
 
 **ALWAYS delegate to Ticketing Agent when user mentions:**
 - "ticket", "tickets", "ticketing"
@@ -437,4 +441,12 @@ The Ticketing Agent specializes in:
 - Generating structured project documentation
 - Breaking down work into manageable pieces
 - Tracking project progress and dependencies
-- Maintaining clear audit trail of all work performed
+- Maintaining clear audit trail of all work performed
+
+### Ticket-Based Work Resumption
+
+**Tickets replace session resume for work continuation**:
+- When starting any session, first check for open ISS tickets
+- Resume work on existing tickets rather than starting new ones
+- Use ticket history to understand context and progress
+- This ensures continuity across sessions and PMs

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/src/claude_mpm/cli/__init__.py

@@ -83,15 +83,26 @@ def main(argv: Optional[list] = None):
     # Initialize or update project registry
     _initialize_project_registry()
 
-    # Verify MCP Gateway configuration on startup (non-blocking)
-    _verify_mcp_gateway_startup()
-
-    # Create parser with version
+    # Parse args early to check if we should skip auto-configuration
+    # (for commands like --version, --help, etc.)
     parser = create_parser(version=__version__)
-
-    # Preprocess and parse arguments
     processed_argv = preprocess_args(argv)
     args = parser.parse_args(processed_argv)
+    
+    # Skip auto-configuration for certain commands
+    skip_auto_config_commands = ["--version", "-v", "--help", "-h"]
+    # sys is already imported at module level (line 16), use it directly
+    should_skip_auto_config = (
+        any(cmd in (processed_argv or sys.argv[1:]) for cmd in skip_auto_config_commands)
+        or (hasattr(args, 'command') and args.command in ["info", "doctor", "config", "mcp"])  # Info, diagnostic, and MCP commands
+    )
+    
+    if not should_skip_auto_config:
+        # Check for MCP auto-configuration (pipx installations)
+        _check_mcp_auto_configuration()
+
+    # Verify MCP Gateway configuration on startup (non-blocking)
+    _verify_mcp_gateway_startup()
 
     # Set up logging
     # Special case: For MCP start command, we need minimal logging to avoid stdout interference
@@ -101,7 +112,7 @@ def main(argv: Optional[list] = None):
     ):
         # For MCP server, configure minimal stderr-only logging
         import logging
-        import sys
+        # sys is already imported at module level
 
         # Only log errors to stderr for MCP server
         if not getattr(args, "test", False) and not getattr(
@@ -176,6 +187,36 @@ def _initialize_project_registry():
         # Continue execution - registry failure shouldn't block startup
 
 
+def _check_mcp_auto_configuration():
+    """
+    Check and potentially auto-configure MCP for pipx installations.
+    
+    WHY: Users installing via pipx should have MCP work out-of-the-box with
+    minimal friction. This function offers one-time auto-configuration with
+    user consent.
+    
+    DESIGN DECISION: This is blocking but quick - it only runs once and has
+    a 10-second timeout. We want to catch users on first run for the best
+    experience.
+    """
+    try:
+        from ..services.mcp_gateway.auto_configure import check_and_configure_mcp
+        
+        # This function handles all the logic:
+        # - Checks if already configured
+        # - Checks if pipx installation
+        # - Checks if already asked before
+        # - Prompts user if needed
+        # - Configures if user agrees
+        check_and_configure_mcp()
+        
+    except Exception as e:
+        # Non-critical - log but don't fail
+        from ..core.logger import get_logger
+        logger = get_logger("cli")
+        logger.debug(f"MCP auto-configuration check failed: {e}")
+
+
 def _verify_mcp_gateway_startup():
     """
     Verify MCP Gateway configuration on startup and pre-warm MCP services.

{claude_mpm-4.0.34 → claude_mpm-4.1.0}/src/claude_mpm/cli/commands/agents.py

@@ -71,6 +71,7 @@ class AgentsCommand(AgentCommand):
                 "deps-install": self._install_agent_dependencies,
                 "deps-list": self._list_agent_dependencies,
                 "deps-fix": self._fix_agent_dependencies,
+                "cleanup-orphaned": self._cleanup_orphaned_agents,
             }
 
             if args.agents_command in command_map:
@@ -469,6 +470,87 @@ class AgentsCommand(AgentCommand):
         except Exception as e:
             self.logger.error(f"Error fixing dependencies: {e}", exc_info=True)
             return CommandResult.error_result(f"Error fixing dependencies: {e}")
+    
+    def _cleanup_orphaned_agents(self, args) -> CommandResult:
+        """Clean up orphaned agents that don't have templates."""
+        try:
+            from ...services.agents.deployment.multi_source_deployment_service import (
+                MultiSourceAgentDeploymentService
+            )
+            
+            # Determine agents directory
+            if hasattr(args, 'agents_dir') and args.agents_dir:
+                agents_dir = args.agents_dir
+            else:
+                # Check for project-level .claude/agents first
+                project_agents_dir = Path.cwd() / ".claude" / "agents"
+                if project_agents_dir.exists():
+                    agents_dir = project_agents_dir
+                else:
+                    # Fall back to user home directory
+                    agents_dir = Path.home() / ".claude" / "agents"
+            
+            if not agents_dir.exists():
+                return CommandResult.success_result(f"Agents directory not found: {agents_dir}")
+            
+            # Initialize service
+            service = MultiSourceAgentDeploymentService()
+            
+            # Determine if we're doing a dry run
+            dry_run = getattr(args, 'dry_run', True)
+            if hasattr(args, 'force') and args.force:
+                dry_run = False
+            
+            # Perform cleanup
+            results = service.cleanup_orphaned_agents(agents_dir, dry_run=dry_run)
+            
+            output_format = getattr(args, 'format', 'text')
+            quiet = getattr(args, 'quiet', False)
+            
+            if output_format in ['json', 'yaml']:
+                return CommandResult.success_result(
+                    f"Found {len(results.get('orphaned', []))} orphaned agents",
+                    data=results
+                )
+            else:
+                # Text output
+                if not results.get("orphaned"):
+                    print("✅ No orphaned agents found")
+                    return CommandResult.success_result("No orphaned agents found")
+                
+                if not quiet:
+                    print(f"\nFound {len(results['orphaned'])} orphaned agent(s):")
+                    for orphan in results["orphaned"]:
+                        print(f"  - {orphan['name']} v{orphan['version']}")
+                
+                if dry_run:
+                    print(
+                        f"\n📝 This was a dry run. Use --force to actually remove "
+                        f"{len(results['orphaned'])} orphaned agent(s)"
+                    )
+                else:
+                    if results.get("removed"):
+                        print(
+                            f"\n✅ Successfully removed {len(results['removed'])} orphaned agent(s)"
+                        )
+                    
+                    if results.get("errors"):
+                        print(f"\n❌ Encountered {len(results['errors'])} error(s):")
+                        for error in results["errors"]:
+                            print(f"  - {error}")
+                        return CommandResult.error_result(
+                            f"Cleanup completed with {len(results['errors'])} errors",
+                            data=results
+                        )
+                
+                return CommandResult.success_result(
+                    f"Cleanup {'preview' if dry_run else 'completed'}",
+                    data=results
+                )
+                
+        except Exception as e:
+            self.logger.error(f"Error during cleanup: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error during cleanup: {e}")
 
 
 def manage_agents(args):