claude-mpm 4.1.7__tar.gz → 4.1.8__tar.gz

claude_mpm-4.1.8/BUILD_NUMBER

@@ -0,0 +1 @@
+305

{claude_mpm-4.1.7 → claude_mpm-4.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.1.7
+Version: 4.1.8
 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

claude_mpm-4.1.8/VERSION

@@ -0,0 +1 @@
+4.1.8

{claude_mpm-4.1.7 → claude_mpm-4.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.1.7"
+version = "4.1.8"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -244,7 +244,7 @@ ignore-imports = false
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.1.7"
+version = "4.1.8"
 version_files = [
     "VERSION",
     "src/claude_mpm/VERSION",

claude_mpm-4.1.8/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.1.8

claude_mpm-4.1.8/src/claude_mpm/agents/OUTPUT_STYLE.md

@@ -0,0 +1,73 @@
+---
+name: Claude MPM
+description: Multi-Agent Project Manager orchestration mode for delegation and coordination
+---
+
+You are Claude Multi-Agent PM, a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized agents.
+
+## Core Operating Rules
+
+**DEFAULT BEHAVIOR - ALWAYS DELEGATE**:
+- 🔴 You MUST delegate 100% of ALL work to specialized agents by default
+- 🔴 Direct action is STRICTLY FORBIDDEN without explicit user override
+- 🔴 Even the simplest tasks MUST be delegated - NO EXCEPTIONS
+- 🔴 When in doubt, ALWAYS DELEGATE - never act directly
+
+**Allowed Tools**:
+- **Task** for delegation (YOUR PRIMARY FUNCTION)
+- **TodoWrite** for tracking delegation progress ONLY
+- **WebSearch/WebFetch** for gathering context BEFORE delegation
+- **Direct answers** ONLY for questions about PM capabilities
+
+## Communication Standards
+
+- **Tone**: Professional, neutral by default
+- **Use**: "Understood", "Confirmed", "Noted"
+- **No simplification** without explicit user request
+- **No mocks** outside test environments
+- **Complete implementations** only - no placeholders
+- **FORBIDDEN**: Overeager enthusiasm ("Excellent!", "Perfect!", "Amazing!")
+
+## Error Handling Protocol
+
+**3-Attempt Process**:
+1. **First Failure**: Re-delegate with enhanced context
+2. **Second Failure**: Mark "ERROR - Attempt 2/3", escalate if needed
+3. **Third Failure**: TodoWrite escalation with user decision required
+
+## Standard Operating Procedure
+
+1. **Analysis**: Parse request, assess context (NO TOOLS)
+2. **Planning**: Agent selection, task breakdown, priority assignment
+3. **Delegation**: Task Tool with enhanced format
+4. **Monitoring**: Track progress via TodoWrite
+5. **Integration**: Synthesize results, validate, report
+
+## TodoWrite Requirements
+
+### Mandatory [Agent] Prefix Rules
+
+**ALWAYS use [Agent] prefix for delegated tasks**:
+- ✅ `[Research] Analyze authentication patterns`
+- ✅ `[Engineer] Implement user registration`
+- ✅ `[QA] Test payment flow`
+- ✅ `[Documentation] Update API docs`
+
+**NEVER use [PM] prefix for implementation tasks**
+
+### Task Status Management
+
+- `pending` - Task not yet started
+- `in_progress` - Currently being worked on (ONE at a time)
+- `completed` - Task finished successfully
+
+## Response Format
+
+When completing delegations, provide structured summaries including:
+- Request summary
+- Agents used and task counts
+- Tasks completed with [Agent] prefixes
+- Files affected across all agents
+- Blockers encountered and resolutions
+- Next steps for user
+- Key information to remember

{claude_mpm-4.1.7 → claude_mpm-4.1.8}/src/claude_mpm/agents/templates/agent-manager.json

@@ -6,7 +6,7 @@
   "tool_choice": "auto",
   "metadata": {
     "description": "Manages agent creation, customization, deployment, and PM instruction configuration",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "capabilities": [
       "agent-creation",
       "variant-management",

{claude_mpm-4.1.7 → claude_mpm-4.1.8}/src/claude_mpm/agents/templates/agent-manager.md

@@ -56,24 +56,99 @@ You manage a comprehensive PM (Project Manager) customization system:
 
 ### Configuration System
 
-Additionally manage configuration files:
+#### Configuration Files (YAML Format)
 
-1. **Project Config** (`./.claude-mpm/configuration.yaml`)
-2. **User Config** (`~/.claude-mpm/configuration.yaml`)
-3. **System Config** (`/etc/claude-mpm/configuration.yaml`)
+The Claude MPM configuration system uses **YAML files**, not JSON:
 
-Features configured:
-- Response logging settings
-- Agent exclusion lists
-- Memory system parameters
-- SocketIO server configuration
-- Performance tuning
+1. **Project Config** (`./.claude-mpm/configuration.yaml`) - Project-specific settings
+2. **User Config** (`~/.claude-mpm/configuration.yaml`) - User's personal settings
+3. **System Config** (`/etc/claude-mpm/configuration.yaml`) - System defaults
+
+#### Agent Deployment Configuration
+
+Control agent deployment through the `agent_deployment` section:
+
+```yaml
+# .claude-mpm/configuration.yaml
+agent_deployment:
+  excluded_agents: ["research", "qa", "documentation"]  # List agents to exclude
+  case_sensitive: false      # Case-insensitive agent name matching (default: false)
+  exclude_dependencies: false # Whether to exclude agent dependencies (default: false)
+```
+
+#### Complete Configuration Example
+
+```yaml
+# .claude-mpm/configuration.yaml
+# Agent deployment settings
+agent_deployment:
+  excluded_agents: ["research", "qa", "documentation"]
+  case_sensitive: false
+  exclude_dependencies: false
+
+# Memory system settings
+memory:
+  enabled: true
+  auto_learning: true
+  limits:
+    default_size_kb: 80
+    max_sections: 10
+    max_items_per_section: 15
+
+# Response tracking
+response_tracking:
+  enabled: true
+  track_all_interactions: false
+  max_response_age_hours: 24
+  max_responses_per_agent: 100
+
+# Response logging
+response_logging:
+  enabled: true
+  track_all_interactions: false
+  format: json
+
+# SocketIO server
+socketio:
+  enabled: true
+  port_range: [8080, 8099]
+  default_port: 8080
+```
+
+#### Important Configuration Notes
+
+- **Configuration is YAML**: All configuration files use YAML format, not JSON
+- **No `use_custom_only` setting**: Use `excluded_agents` list to control deployment
+- **Agent exclusion**: List agent IDs in `excluded_agents` to prevent deployment
+- **Case sensitivity**: Control with `case_sensitive` field (default: false)
 
 **IMPORTANT NOTES**:
 - CLAUDE.md files are NOT loaded by MPM (handled by Claude Code directly)
 - SystemInstructionsDeployer auto-deploys PM instructions on first run
 - FrameworkLoader orchestrates all customization loading
 - Template variable {{CAPABILITIES}} is dynamically replaced with agent list
+- Configuration uses YAML format (`.claude-mpm/configuration.yaml`), not JSON
+- Agents excluded via `agent_deployment.excluded_agents` list in configuration
+
+## Agent Storage and Deployment
+
+### Directory Structure
+
+**Development/Source Templates** (JSON format):
+- `.claude-mpm/agents/*.json` - Project-level agent source templates
+- `~/.claude-mpm/agents/*.json` - User-level agent source templates
+- These JSON files are compiled to Markdown during deployment
+
+**Runtime/Deployed Agents** (Markdown format):
+- `.claude/agents/*.md` - Project-level deployed agents (what Claude Code reads)
+- `~/.claude/agents/*.md` - User-level deployed agents
+- `/src/claude_mpm/agents/templates/*.md` - System-level agent templates
+
+**Key Points**:
+- JSON files in `.claude-mpm/agents/` are source templates for development
+- MD files in `.claude/agents/` are deployed agents that Claude Code reads
+- Agent deployment compiles JSON templates to Markdown format
+- Version-based precedence determines which agent is used (highest version wins)
 
 ## Core Responsibilities
 
@@ -209,12 +284,127 @@ When creating agents, use this structure:
 }
 ```
 
+## Complete Agent JSON Schema
+
+### Required Fields for Deployment
+
+When deploying agents, ensure ALL fields use the correct data types:
+
+```json
+{
+  "agent_id": "custom-agent",                  // Required: unique identifier
+  "version": "1.0.0",                          // Required: semantic version
+  "metadata": {                                // Required: agent metadata
+    "name": "Custom Agent",
+    "description": "Agent description",
+    "tags": ["tag1", "tag2"],                 // MUST be a list, NOT a string!
+    "capabilities": ["capability1", "capability2"]  // MUST be a list!
+  },
+  "capabilities": {                            // Optional but recommended
+    "model": "sonnet",                         // Default: "sonnet"
+    "tools": ["Read", "Write", "Edit"],       // MUST be a list, NOT a JSON string!
+    "resource_tier": "standard"                // Default: "standard"
+  },
+  "specializations": ["spec1", "spec2"],      // Optional: MUST be a list if provided!
+  "when_to_use": ["scenario1", "scenario2"],   // Optional: MUST be a list if provided!
+  "network_access": true,                      // Optional: boolean
+  "temperature": 0.3                           // Optional: float between 0 and 1
+}
+```
+
+### Common Data Type Errors
+
+**❌ WRONG - These will cause deployment errors:**
+```json
+{
+  "tools": '["Read", "Write", "Edit"]',       // String containing JSON - WRONG!
+  "tags": '["tag1", "tag2"]',                  // String containing JSON - WRONG!
+  "specializations": '["spec1", "spec2"]'      // String containing JSON - WRONG!
+}
+```
+
+**✅ CORRECT - Use actual lists/arrays:**
+```json
+{
+  "tools": ["Read", "Write", "Edit"],          // Actual list - CORRECT!
+  "tags": ["tag1", "tag2"],                     // Actual list - CORRECT!
+  "specializations": ["spec1", "spec2"]         // Actual list - CORRECT!
+}
+```
+
+### Available Tools
+
+When specifying tools, use these exact names (case-sensitive):
+
+- **File Operations**: `Read`, `Write`, `Edit`, `MultiEdit`
+- **Search & Navigation**: `Grep`, `Glob`, `LS`
+- **System Operations**: `Bash`, `BashOutput`, `KillBash`
+- **Web Operations**: `WebSearch`, `WebFetch`
+- **Project Management**: `TodoWrite`
+- **Notebook Operations**: `NotebookEdit`
+- **MCP Tools**: Any tools starting with `mcp__` (if available)
+
 ### Version Guidelines
 - Production versions: Use standard semantic versioning (1.0.0, 1.1.0, 2.0.0)
 - Development versions: Use 999.x.x to override all other versions
 - Version determines precedence across ALL sources (project/user/system)
 - Higher version always wins regardless of deployment location
 
+## Common Deployment Errors and Solutions
+
+### 1. TypeError: can only concatenate list (not 'str') to list
+
+**Cause**: The `tools`, `tags`, `capabilities`, or `specializations` field is a JSON string instead of a list.
+
+**Solution**: Ensure all list fields are actual Python lists, not JSON strings:
+```python
+# WRONG
+"tools": '["Read", "Write"]'  # This is a string!
+
+# CORRECT
+"tools": ["Read", "Write"]     # This is a list!
+```
+
+### 2. Version Conflict Errors
+
+**Cause**: An agent with the same ID but higher version exists elsewhere.
+
+**Solution**: 
+- Use version 999.x.x for development to override all versions
+- Check existing versions with `mpm list`
+- Increment version appropriately for production releases
+
+### 3. Missing Required Fields
+
+**Cause**: Agent JSON is missing required fields like `agent_id`, `version`, or `metadata`.
+
+**Solution**: Use the complete schema above and ensure all required fields are present:
+```json
+{
+  "agent_id": "my-agent",     // Required
+  "version": "1.0.0",          // Required
+  "metadata": {               // Required
+    "name": "My Agent",
+    "description": "Description"
+  }
+}
+```
+
+### 4. Invalid Tool Names
+
+**Cause**: Specifying tools that don't exist in the environment.
+
+**Solution**: Use only valid tool names from the Available Tools list above. Check case-sensitivity!
+
+### 5. File Not Found Errors
+
+**Cause**: Agent prompt file doesn't exist at the specified location.
+
+**Solution**: 
+- Place agent files in `.claude/agents/` directory
+- Ensure both JSON and markdown files exist
+- Use matching filenames (e.g., `my-agent.json` and `my-agent.md`)
+
 ## Validation Rules
 
 ### Agent ID Validation
@@ -235,6 +425,32 @@ When creating agents, use this structure:
 - Ensure backup of overridden agents
 - Validate against schema if available
 
+### Pre-Deployment Validation Commands
+
+**Test agent configuration before deployment:**
+```bash
+# Validate JSON structure
+mpm validate-agent ./my-agent.json
+
+# Test deployment without applying
+mpm deploy --dry-run ./my-agent.json
+
+# Check for conflicts
+mpm list --show-conflicts my-agent
+```
+
+**Verify agent files:**
+```bash
+# Check both files exist
+ls -la .claude/agents/my-agent.*
+
+# Validate JSON syntax
+python -m json.tool .claude/agents/my-agent.json
+
+# Test agent loading
+mpm test-agent my-agent
+```
+
 ## Error Handling
 
 ### Common Errors and Solutions
@@ -366,6 +582,28 @@ Brief description of action taken
 - Development Mode: Yes/No (if version 999.x.x)
 ```
 
+## Common Misconceptions
+
+### Configuration Format
+❌ **INCORRECT**: "Configuration is in `.claude-mpm/config/agents.json`"
+✅ **CORRECT**: Configuration is in `.claude-mpm/configuration.yaml` (YAML format)
+
+### Agent Exclusion
+❌ **INCORRECT**: "Use `use_custom_only: true` to control agents"
+✅ **CORRECT**: Use `agent_deployment.excluded_agents` list in configuration.yaml
+
+### Agent Storage
+❌ **INCORRECT**: "Agents are stored as JSON at runtime"
+✅ **CORRECT**: 
+- Source templates: `.claude-mpm/agents/*.json` (development)
+- Deployed agents: `.claude/agents/*.md` (runtime, what Claude Code reads)
+
+### Configuration Files
+❌ **INCORRECT**: "Individual agent configs in `.claude-mpm/agents/[agent-name].json`"
+✅ **CORRECT**: 
+- Main config: `.claude-mpm/configuration.yaml` (YAML)
+- Agent templates: `.claude-mpm/agents/*.json` (compiled to MD on deployment)
+
 ## Security Considerations
 
 - Validate all user inputs

{claude_mpm-4.1.7 → claude_mpm-4.1.8}/src/claude_mpm/cli/commands/configure.py

@@ -222,6 +222,16 @@ class ConfigureCommand(BaseCommand):
         if getattr(args, "version_info", False):
             return self._show_version_info()
 
+        # Handle hook installation
+        if getattr(args, "install_hooks", False):
+            return self._install_hooks(force=getattr(args, "force", False))
+
+        if getattr(args, "verify_hooks", False):
+            return self._verify_hooks()
+
+        if getattr(args, "uninstall_hooks", False):
+            return self._uninstall_hooks()
+
         # Handle direct navigation options
         if getattr(args, "agents", False):
             return self._run_agent_management()
@@ -1018,7 +1028,11 @@ class ConfigureCommand(BaseCommand):
             import subprocess
 
             result = subprocess.run(
-                ["claude", "--version"], capture_output=True, text=True, timeout=5, check=False
+                ["claude", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
             )
             if result.returncode == 0:
                 claude_version = result.stdout.strip()
@@ -1157,7 +1171,11 @@ Directory: {self.project_dir}
             import subprocess
 
             result = subprocess.run(
-                ["claude", "--version"], capture_output=True, text=True, timeout=5, check=False
+                ["claude", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
             )
             if result.returncode == 0:
                 data["claude_version"] = result.stdout.strip()
@@ -1175,6 +1193,137 @@ Directory: {self.project_dir}
 
         return CommandResult.success_result("Version information displayed", data=data)
 
+    def _install_hooks(self, force: bool = False) -> CommandResult:
+        """Install Claude MPM hooks for Claude Code integration."""
+        try:
+            from ...hooks.claude_hooks.installer import HookInstaller
+
+            installer = HookInstaller()
+
+            # Check current status first
+            status = installer.get_status()
+            if status["installed"] and not force:
+                self.console.print("[yellow]Hooks are already installed.[/yellow]")
+                self.console.print("Use --force to reinstall.")
+
+                if not status["valid"]:
+                    self.console.print("\n[red]However, there are issues:[/red]")
+                    for issue in status["issues"]:
+                        self.console.print(f"  - {issue}")
+
+                return CommandResult.success_result(
+                    "Hooks already installed", data=status
+                )
+
+            # Install hooks
+            self.console.print("[cyan]Installing Claude MPM hooks...[/cyan]")
+            success = installer.install_hooks(force=force)
+
+            if success:
+                self.console.print("[green]✓ Hooks installed successfully![/green]")
+                self.console.print("\nYou can now use /mpm commands in Claude Code:")
+                self.console.print("  /mpm         - Show help")
+                self.console.print("  /mpm status  - Show claude-mpm status")
+
+                # Verify installation
+                is_valid, issues = installer.verify_hooks()
+                if not is_valid:
+                    self.console.print(
+                        "\n[yellow]Warning: Installation completed but verification found issues:[/yellow]"
+                    )
+                    for issue in issues:
+                        self.console.print(f"  - {issue}")
+
+                return CommandResult.success_result("Hooks installed successfully")
+            self.console.print("[red]✗ Hook installation failed[/red]")
+            return CommandResult.error_result("Hook installation failed")
+
+        except ImportError:
+            self.console.print("[red]Error: HookInstaller module not found[/red]")
+            self.console.print("Please ensure claude-mpm is properly installed.")
+            return CommandResult.error_result("HookInstaller module not found")
+        except Exception as e:
+            self.logger.error(f"Hook installation error: {e}", exc_info=True)
+            return CommandResult.error_result(f"Hook installation failed: {e}")
+
+    def _verify_hooks(self) -> CommandResult:
+        """Verify that Claude MPM hooks are properly installed."""
+        try:
+            from ...hooks.claude_hooks.installer import HookInstaller
+
+            installer = HookInstaller()
+            status = installer.get_status()
+
+            self.console.print("[bold]Hook Installation Status[/bold]\n")
+
+            if status["installed"]:
+                self.console.print(
+                    f"[green]✓[/green] Hooks installed at: {status['hook_script']}"
+                )
+            else:
+                self.console.print("[red]✗[/red] Hooks not installed")
+
+            if status["settings_file"]:
+                self.console.print(
+                    f"[green]✓[/green] Settings file: {status['settings_file']}"
+                )
+            else:
+                self.console.print("[red]✗[/red] Settings file not found")
+
+            if status.get("configured_events"):
+                self.console.print(
+                    f"[green]✓[/green] Configured events: {', '.join(status['configured_events'])}"
+                )
+            else:
+                self.console.print("[red]✗[/red] No events configured")
+
+            if status["valid"]:
+                self.console.print("\n[green]All checks passed![/green]")
+            else:
+                self.console.print("\n[red]Issues found:[/red]")
+                for issue in status["issues"]:
+                    self.console.print(f"  - {issue}")
+
+            return CommandResult.success_result(
+                "Hook verification complete", data=status
+            )
+
+        except ImportError:
+            self.console.print("[red]Error: HookInstaller module not found[/red]")
+            return CommandResult.error_result("HookInstaller module not found")
+        except Exception as e:
+            self.logger.error(f"Hook verification error: {e}", exc_info=True)
+            return CommandResult.error_result(f"Hook verification failed: {e}")
+
+    def _uninstall_hooks(self) -> CommandResult:
+        """Uninstall Claude MPM hooks."""
+        try:
+            from ...hooks.claude_hooks.installer import HookInstaller
+
+            installer = HookInstaller()
+
+            # Confirm uninstallation
+            if not Confirm.ask(
+                "[yellow]Are you sure you want to uninstall Claude MPM hooks?[/yellow]"
+            ):
+                return CommandResult.success_result("Uninstallation cancelled")
+
+            self.console.print("[cyan]Uninstalling Claude MPM hooks...[/cyan]")
+            success = installer.uninstall_hooks()
+
+            if success:
+                self.console.print("[green]✓ Hooks uninstalled successfully![/green]")
+                return CommandResult.success_result("Hooks uninstalled successfully")
+            self.console.print("[red]✗ Hook uninstallation failed[/red]")
+            return CommandResult.error_result("Hook uninstallation failed")
+
+        except ImportError:
+            self.console.print("[red]Error: HookInstaller module not found[/red]")
+            return CommandResult.error_result("HookInstaller module not found")
+        except Exception as e:
+            self.logger.error(f"Hook uninstallation error: {e}", exc_info=True)
+            return CommandResult.error_result(f"Hook uninstallation failed: {e}")
+
     def _run_agent_management(self) -> CommandResult:
         """Jump directly to agent management."""
         try:

{claude_mpm-4.1.7 → claude_mpm-4.1.8}/src/claude_mpm/cli/commands/configure_tui.py

@@ -1200,7 +1200,11 @@ class SettingsScreen(Container):
             import subprocess
 
             result = subprocess.run(
-                ["claude", "--version"], capture_output=True, text=True, timeout=5, check=False
+                ["claude", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
             )
             if result.returncode == 0:
                 claude_version = result.stdout.strip()

{claude_mpm-4.1.7 → claude_mpm-4.1.8}/src/claude_mpm/cli/parsers/configure_parser.py

@@ -96,6 +96,29 @@ def add_configure_subparser(subparsers) -> argparse.ArgumentParser:
         help="Import configuration from a file",
     )
 
+    # Hook management options
+    hooks_group = configure_parser.add_argument_group("hook management")
+    hooks_group.add_argument(
+        "--install-hooks",
+        action="store_true",
+        help="Install Claude MPM hooks for Claude Code integration",
+    )
+    hooks_group.add_argument(
+        "--verify-hooks",
+        action="store_true",
+        help="Verify that Claude MPM hooks are properly installed",
+    )
+    hooks_group.add_argument(
+        "--uninstall-hooks",
+        action="store_true",
+        help="Uninstall Claude MPM hooks",
+    )
+    hooks_group.add_argument(
+        "--force",
+        action="store_true",
+        help="Force reinstallation of hooks even if they already exist",
+    )
+
     # Display options
     display_group = configure_parser.add_argument_group("display options")
     display_group.add_argument(