claude-mpm 1.0.0__tar.gz → 2.0.0__tar.gz

claude_mpm-2.0.0/.claude/commands/README.md

@@ -0,0 +1,36 @@
+# Claude MPM Slash Commands
+
+This directory contains slash command definitions for Claude MPM.
+
+## Overview
+
+Slash commands allow you to execute specific actions without going through the LLM. They are processed directly by the claude-mpm framework.
+
+## Available Commands
+
+### `/mpm:test`
+- **Description**: A simple test command that returns "Hello World"
+- **Usage**: `/mpm:test`
+- **Purpose**: Demonstrates the slash command system
+
+## Implementation
+
+Commands are handled in two ways:
+
+1. **Command Router** (`.claude/scripts/command_router.py`): A standalone Python script that can execute commands independently
+2. **Simple Runner Integration** (`src/claude_mpm/core/simple_runner.py`): Intercepts `/mpm:` commands before they reach Claude
+
+## Adding New Commands
+
+To add a new slash command:
+
+1. Add the command handler to the command router
+2. Create a markdown file in the appropriate subdirectory (e.g., `.claude/commands/mpm/mycommand.md`)
+3. Optionally update the `_handle_mpm_command` method in simple_runner.py for direct integration
+
+## Future Enhancements
+
+- Hook-based command processing for better modularity
+- Command discovery and auto-registration
+- Rich command output formatting
+- Command history and logging

claude_mpm-2.0.0/.claude/commands/mpm.md

@@ -0,0 +1,5 @@
+---
+description: Claude MPM management commands
+---
+
+/mpm

claude_mpm-2.0.0/.claude/hooks.json

@@ -0,0 +1,32 @@
+{
+  "hooks": {
+    "userPromptSubmit": [
+      {
+        "name": "mpm-command-interceptor",
+        "enabled": true,
+        "priority": 100,
+        "conditions": {
+          "promptPatterns": ["/mpm:", "Hello World"]
+        },
+        "handler": "/Users/masa/Projects/claude-mpm/.claude/hooks/mpm_intercept_hook.js"
+      },
+      {
+        "name": "helloworld-command",
+        "enabled": true,
+        "priority": 90,
+        "conditions": {
+          "promptPatterns": ["/helloworld"]
+        },
+        "handler": "/Users/masa/Projects/claude-mpm/.claude/hooks/helloworld_hook.js"
+      }
+    ]
+  },
+  "global": {
+    "timeoutMs": 5000,
+    "retryCount": 3,
+    "logging": {
+      "level": "info",
+      "destination": "/Users/masa/Projects/claude-mpm/.claude/logs/hooks.log"
+    }
+  }
+}

claude_mpm-2.0.0/.claude/scripts/command_router.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Simple command router for /mpm: commands."""
+
+import sys
+from typing import Dict, Callable, Optional
+
+
+class CommandRouter:
+    """Simple command dispatcher for /mpm: commands."""
+    
+    def __init__(self):
+        self.commands: Dict[str, Callable] = {}
+        self._register_builtin_commands()
+    
+    def _register_builtin_commands(self):
+        """Register built-in commands."""
+        self.register("test", self._test_command)
+    
+    def register(self, command: str, handler: Callable):
+        """Register a command handler."""
+        self.commands[command] = handler
+    
+    def _test_command(self, *args) -> str:
+        """Simple test command that returns Hello World."""
+        return "Hello World"
+    
+    def execute(self, command: str, *args) -> Optional[str]:
+        """Execute a command and return the result."""
+        if command in self.commands:
+            return self.commands[command](*args)
+        return None
+    
+    def list_commands(self) -> list:
+        """List all available commands."""
+        return list(self.commands.keys())
+
+
+def main():
+    """Main entry point for command router."""
+    router = CommandRouter()
+    
+    if len(sys.argv) < 2:
+        print("Usage: command_router.py <command> [args...]")
+        print(f"Available commands: {', '.join(router.list_commands())}")
+        sys.exit(1)
+    
+    command = sys.argv[1]
+    args = sys.argv[2:]
+    
+    result = router.execute(command, *args)
+    if result is not None:
+        print(result)
+    else:
+        print(f"Unknown command: {command}")
+        print(f"Available commands: {', '.join(router.list_commands())}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

claude_mpm-2.0.0/.claude/settings.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/masa/Projects/claude-mpm/src/claude_mpm/hooks/claude_hooks/hook_wrapper.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/masa/Projects/claude-mpm/src/claude_mpm/hooks/claude_hooks/hook_wrapper.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/masa/Projects/claude-mpm/src/claude_mpm/hooks/claude_hooks/hook_wrapper.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

{claude_mpm-1.0.0 → claude_mpm-2.0.0}/.gitignore

@@ -27,3 +27,14 @@ build/
 # Test logs
 test_logs/
 tests/test_logs/
+
+# Agent backups
+src/claude_mpm/agents/templates/backup/
+**/backup/
+
+# Temporary directories
+test_dir/
+ai-trackdown-pytools-bug-support/
+
+# Claude MPM temporary files
+**/.claude-mpm/

claude_mpm-2.0.0/.python-version

@@ -0,0 +1 @@
+3.11

{claude_mpm-1.0.0 → claude_mpm-2.0.0}/CHANGELOG.md

@@ -5,6 +5,65 @@ All notable changes to claude-mpm will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2025-07-27
+
+### BREAKING CHANGES
+- **Agent Schema Standardization**: Complete overhaul of agent definition format
+  - Agent IDs no longer use `_agent` suffix (e.g., `research_agent` → `research`)
+  - Migrated from YAML to JSON format with strict schema validation
+  - All agents must conform to new standardized schema at `src/claude_mpm/schemas/agent_schema.json`
+  - Resource allocation now uses predefined tiers (intensive, standard, lightweight)
+  - Model names standardized (e.g., `claude-sonnet-4-20250514` → `claude-4-sonnet-20250514`)
+
+### Added
+- **Comprehensive Schema Validation Framework**
+  - JSON Schema-based validation for all agent definitions
+  - Business rule validation for resource allocation consistency
+  - Automatic validation on agent load
+  - Migration tools for converting old format to new
+- **Resource Tier System**
+  - Three predefined tiers: intensive (900s/3072MB), standard (600s/2048MB), lightweight (300s/1024MB)
+  - Automatic resource allocation based on agent type
+  - Clear rationale for resource assignments
+- **Enhanced Agent Metadata**
+  - Required metadata fields: name, description, category, tags
+  - Optional fields: author, created_at, updated_at
+  - Improved agent discoverability through standardized tags
+- **Validation API**
+  - `AgentValidator` class for programmatic validation
+  - Detailed error and warning reporting
+  - Integration with CI/CD pipelines
+
+### Changed
+- **Agent Definition Format**
+  - Migrated from YAML to JSON for better schema validation
+  - Standardized field names and structure
+  - Added required version field using semantic versioning
+  - Instructions limited to 8000 characters for consistency
+- **Agent Loader Improvements**
+  - Backward compatibility for old agent IDs (both `research` and `research_agent` work)
+  - Performance improvements through caching (1.6x faster)
+  - Better error messages for validation failures
+- **Model Naming Convention**
+  - Standardized to `claude-{version}-{variant}-{date}` format
+  - Updated all agents to use consistent model names
+
+### Fixed
+- **Validation Issues**
+  - Inconsistent versioning across agents (was using integers, now semantic)
+  - Resource allocation inconsistencies
+  - Missing required fields in some agents
+  - Tool array inconsistencies
+
+### Migration Guide
+- See [Schema Standardization Migration Guide](docs/user/05-migration/schema-standardization-migration.md)
+- Use backward compatibility layer during transition
+- Run validation on all custom agents before deployment
+
+## [1.1.0] - 2025-07-26
+
+## [1.0.1] - 2025-07-26
+
 ## [1.0.0] - 2025-07-26
 
 ### BREAKING CHANGES

claude_mpm-2.0.0/INSTALL.md

@@ -0,0 +1,204 @@
+# Installation Guide
+
+Claude MPM can be installed via UV, pip, or npm. UV is recommended for the best experience.
+
+## Prerequisites
+
+- **Claude Code** 1.0.60 or later (required)
+- **Python** 3.8 or later
+- **Package Manager**: UV (recommended), pip, or npm
+
+## Option 1: Install via UV (Recommended)
+
+[UV](https://github.com/astral-sh/uv) is a fast Python package installer that handles virtual environments automatically:
+
+```bash
+# Install UV if not already installed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install claude-mpm
+uv pip install claude-mpm
+```
+
+## Option 2: Install via pip
+
+Traditional Python installation:
+
+```bash
+# Create virtual environment (recommended)
+python -m venv claude-mpm-env
+source claude-mpm-env/bin/activate  # On Windows: claude-mpm-env\Scripts\activate
+
+# Install claude-mpm
+pip install claude-mpm
+```
+
+## Option 3: Install via npm (Wrapper)
+
+The npm package provides a convenient wrapper that will install the Python package on first run:
+
+```bash
+npm install -g @bobmatnyc/claude-mpm
+```
+
+**Note**: This is just a wrapper - Python 3.8+ must be installed on your system.
+
+## Verify Installation
+
+After installation, verify it works:
+
+```bash
+# Show version and help
+claude-mpm --help
+
+# Test in interactive mode
+claude-mpm
+
+# Run a simple test
+claude-mpm run -i "Say hello" --non-interactive
+```
+
+## Usage
+
+### Interactive Mode (Default)
+
+```bash
+claude-mpm
+```
+
+This launches Claude Code with the PM framework loaded, including:
+- System instructions for orchestration
+- Deployed specialized agents (engineer, qa, research, etc.)
+- Delegation-only operation mode
+
+### Non-Interactive Mode
+
+```bash
+claude-mpm run -i "Your task here" --non-interactive
+```
+
+### Common Options
+
+```bash
+# Disable agent deployment
+claude-mpm --no-native-agents
+
+# Enable debug logging
+claude-mpm --logging DEBUG
+
+# Disable hooks
+claude-mpm --no-hooks
+```
+
+## Terminal UI Mode
+
+Claude MPM includes a terminal UI that shows Claude output, ToDo lists, and tickets in separate panes:
+
+```bash
+# Launch with rich UI (requires pip install claude-mpm[ui])
+claude-mpm --mpm:ui
+
+# Launch with basic curses UI
+claude-mpm --mpm:ui --mode curses
+```
+
+### Terminal UI Features
+
+- **Claude Output Pane**: Live Claude interaction
+- **ToDo List Pane**: Shows current tasks from Claude's todo system
+- **Tickets Pane**: Browse and create tickets
+- **Keyboard Shortcuts**:
+  - `Tab`: Switch between panes
+  - `F5`: Refresh ToDo and ticket lists
+  - `N`: Create new ticket (when in tickets pane)
+  - `Q`: Quit
+
+### Installing UI Dependencies
+
+For the best terminal UI experience:
+
+```bash
+# With UV
+uv pip install claude-mpm[ui]
+
+# With pip
+pip install claude-mpm[ui]
+```
+
+## Development Installation
+
+For contributing or modifying Claude MPM:
+
+```bash
+# Clone repository
+git clone https://github.com/bobmatnyc/claude-mpm.git
+cd claude-mpm
+
+# Run development install script (auto-detects UV)
+./install_dev.sh
+```
+
+## Troubleshooting
+
+### "claude: command not found"
+
+Install Claude Code 1.0.60+ from https://claude.ai/code
+
+### "Python not found"
+
+Install Python 3.8+ from:
+- macOS: `brew install python@3.11`
+- Ubuntu/Debian: `sudo apt install python3.11`
+- Windows/Other: https://python.org
+
+### PEP 668 "externally managed environment" error
+
+Modern systems protect the global Python environment. Solutions:
+
+1. **Use UV** (automatically handles virtual environments)
+2. **Use pipx**: `pipx install claude-mpm`
+3. **Use a virtual environment** (see pip instructions above)
+
+### npm install fails
+
+Ensure you have Node.js 14+ installed. The npm package is just a wrapper - the actual functionality requires Python.
+
+## Updating
+
+### UV
+```bash
+uv pip install --upgrade claude-mpm
+```
+
+### pip
+```bash
+pip install --upgrade claude-mpm
+```
+
+### npm
+```bash
+npm update -g @bobmatnyc/claude-mpm
+```
+
+## Uninstalling
+
+### UV
+```bash
+uv pip uninstall claude-mpm
+```
+
+### pip
+```bash
+pip uninstall claude-mpm
+```
+
+### npm
+```bash
+npm uninstall -g @bobmatnyc/claude-mpm
+```
+
+## Next Steps
+
+- See [Getting Started Guide](docs/user/01-getting-started/README.md)
+- Read the [User Documentation](docs/user/README.md)
+- Check out [Example Usage](docs/user/02-guides/basic-usage.md)

{claude_mpm-1.0.0 → claude_mpm-2.0.0}/MANIFEST.in

@@ -24,6 +24,9 @@ include ticket
 # Include configuration examples
 recursive-include src/claude_mpm/config *.py
 
+# Include hook files (including shell scripts)
+recursive-include src/claude_mpm/hooks *.py *.sh
+
 # Exclude test and cache files
 global-exclude __pycache__
 global-exclude *.py[co]

{claude_mpm-1.0.0 → claude_mpm-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 1.0.0
+Version: 2.0.0
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -44,8 +44,106 @@ Dynamic: requires-python
 
 # Claude MPM - Multi-Agent Project Manager
 
+> **Note**: This project is a fork of [claude-multiagent-pm](https://github.com/kfsone/claude-multiagent-pm), enhanced to integrate with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v1.0.60+'s native agent system. This integration enables seamless orchestration of Claude Code's built-in agents (research, engineer, qa, documentation, security, ops, version_control, data_engineer) through a unified project management interface.
+
+> **⚠️ Version 2.0.0 Breaking Changes**: Agent schema has been standardized. Agent IDs no longer use the `_agent` suffix (e.g., `research_agent` → `research`). See the [migration guide](docs/user/05-migration/schema-standardization-migration.md) for details.
+
 A framework for Claude that enables multi-agent workflows and extensible capabilities through a modular architecture.
 
+## Quick Start
+
+### Why Interactive Mode?
+**Interactive mode is significantly more performant** than non-interactive commands. It maintains context between requests and avoids the overhead of repeatedly launching Claude, making your development workflow much faster and more efficient.
+
+### Installation
+
+```bash
+# Install globally via npm (recommended)
+npm install -g @bobmatnyc/claude-mpm
+
+# Or use npx for one-time usage
+npx @bobmatnyc/claude-mpm
+```
+
+### Three Essential Use Cases
+
+#### 1. 🔍 **Understand Your Codebase**
+Start with codebase exploration - perfect for onboarding or getting oriented:
+
+```bash
+# Launch interactive mode
+claude-mpm
+
+# Then ask:
+> Explain the codebase structure. What are the main components, how do they interact, and what architectural patterns are used?
+```
+
+#### 2. 🚀 **Build a New Project** 
+For greenfield development, use detailed, AI-generated prompts for best results:
+
+```bash
+claude-mpm
+
+# Example detailed prompt (AI-generated prompts work best):
+> Create a modern web application with the following requirements:
+> - Next.js 14 with TypeScript and Tailwind CSS
+> - Authentication using NextAuth.js with GitHub provider
+> - PostgreSQL database with Prisma ORM
+> - User dashboard with CRUD operations for "projects"
+> - API routes following REST conventions
+> - Responsive design with dark/light mode toggle
+> - Form validation using react-hook-form and zod
+> - Include proper error handling and loading states
+> - Set up ESLint, Prettier, and basic testing with Jest
+> - Generate a complete project structure with all necessary files
+```
+
+#### 3. 🔧 **Enhance Existing Code**
+For working on your current codebase, provide rich context:
+
+```bash
+claude-mpm
+
+# Example detailed enhancement prompt:
+> I need to add real-time notifications to my existing Next.js application. Current tech stack:
+> - Next.js 13 with app router
+> - TypeScript
+> - Tailwind CSS
+> - PostgreSQL with Prisma
+> - User authentication already implemented
+> 
+> Requirements:
+> - WebSocket-based real-time notifications
+> - Toast notifications in the UI
+> - Database table to store notification history
+> - Mark as read/unread functionality
+> - Different notification types (info, warning, success, error)
+> - Admin panel to send system-wide notifications
+> - Email fallback for offline users
+> 
+> Please analyze my current codebase structure and implement this feature following my existing patterns and conventions.
+```
+
+### 💡 Pro Tips for Better Results
+
+1. **Use AI to generate your prompts**: Ask ChatGPT or Claude to help you create detailed, specific prompts for your use case
+2. **Provide context**: Include your tech stack, requirements, and any constraints
+3. **Stay interactive**: Keep the conversation going to refine and iterate on solutions
+4. **Ask for explanations**: Request explanations of architectural decisions and trade-offs
+
+### Alternative: Non-Interactive Mode
+For automation or simple one-off tasks:
+
+```bash
+# Quick analysis
+claude-mpm run -i "What testing frameworks are used in this project?" --non-interactive
+
+# With subprocess orchestration for complex tasks
+claude-mpm run --subprocess -i "Audit this codebase for security vulnerabilities" --non-interactive
+```
+
+**Note**: Non-interactive mode has higher overhead and is less efficient for multi-step development workflows.
+
 
 ## 📚 Documentation
 
@@ -117,17 +215,45 @@ Claude MPM provides a modular framework for extending Claude's capabilities:
 
 ## Installation
 
-### From Source
+### Other Installation Methods
+
+#### Using UV (Recommended - Fast)
+UV is a lightning-fast Python package manager written in Rust, offering 10-100x speed improvements over pip.
+
+```bash
+# Install UV (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install claude-mpm with UV
+uv pip install claude-mpm
+
+# Or install from git
+uv pip install git+https://github.com/bobmatnyc/claude-mpm.git
+```
+
+#### Using pip (Traditional)
+```bash
+# Install from PyPI
+pip install claude-mpm
+
+# Or install from git
+pip install git+https://github.com/bobmatnyc/claude-mpm.git
+```
+
+### From Source (Development)
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/claude-mpm.git
+git clone https://github.com/bobmatnyc/claude-mpm.git
 cd claude-mpm
 
-# Run development installation script
-./install_dev.sh
+# Option A: Using UV (Recommended - Much faster)
+uv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+uv pip install -e .
 
-# Activate virtual environment
+# Option B: Traditional approach
+./install_dev.sh
 source venv/bin/activate
 ```
 
@@ -135,7 +261,7 @@ source venv/bin/activate
 
 #### Core Requirements
 - Python 3.8+
-- Claude CLI (must be installed and in PATH)
+- Claude Code CLI 1.0.60+ (must be installed and in PATH)
 
 #### Automatically Installed
 - tree-sitter & language packs (for code analysis)
@@ -181,21 +307,6 @@ Commands:
   info                 Show framework and configuration info
 ```
 
-## Quick Start
-
-```bash
-# 1. Clone and install
-git clone https://github.com/yourusername/claude-mpm.git
-cd claude-mpm
-./install_dev.sh
-source venv/bin/activate
-
-# 2. Run interactive session
-claude-mpm
-
-# 3. Or run a single command
-claude-mpm run -i "Explain the codebase structure" --non-interactive
-```
 
 
 ## Architecture