claude-mpm 5.4.41__py3-none-any.whl → 5.6.72__py3-none-any.whl

claude_mpm/utils/agent_dependency_loader.py

@@ -65,6 +65,7 @@ class AgentDependencyLoader:
         self.deployment_state_file = (
             Path.cwd() / ".claude" / "agents" / ".mpm_deployment_state"
         )
+        self.is_uv_tool = self._check_uv_tool_installation()
 
     def discover_deployed_agents(self) -> Dict[str, Path]:
         """
@@ -191,9 +192,42 @@ class AgentDependencyLoader:
         logger.debug(f"Loaded dependencies for {len(agent_dependencies)} agents")
         return agent_dependencies
 
+    def _check_uv_tool_installation(self) -> bool:
+        """
+        Check if running in UV tool environment (no pip available).
+
+        WHY: UV tool environments don't have pip installed. The executable
+        path typically contains ".local/share/uv/tools/" and the UV_TOOL_DIR
+        environment variable is set. In such environments, we need to use
+        'uv pip' instead of 'python -m pip'.
+
+        Returns:
+            True if UV tool environment, False otherwise
+        """
+        import os
+
+        # Check UV_TOOL_DIR environment variable
+        uv_tool_dir = os.environ.get("UV_TOOL_DIR", "")
+        if uv_tool_dir and "claude-mpm" in uv_tool_dir:
+            logger.debug(f"UV tool environment detected via UV_TOOL_DIR: {uv_tool_dir}")
+            return True
+
+        # Check executable path for UV tool patterns
+        executable = sys.executable
+        if ".local/share/uv/tools/" in executable or "/uv/tools/" in executable:
+            logger.debug(
+                f"UV tool environment detected via executable path: {executable}"
+            )
+            return True
+
+        return False
+
     def check_python_dependency(self, package_spec: str) -> Tuple[bool, Optional[str]]:
         """
-        Check if a Python package dependency is satisfied.
+        Check if a Python package dependency is satisfied in the TARGET environment.
+
+        WHY: UV tool environments use a separate Python installation. We must check
+        packages in the same environment where they would be installed/used.
 
         Args:
             package_spec: Package specification (e.g., "pandas>=2.0.0")
@@ -221,7 +255,70 @@ class AgentDependencyLoader:
                 )
                 return True, "optional-skipped"
 
-            # Try to import and check version
+            # For UV tool environments, check via UV's Python
+            if self.is_uv_tool:
+                try:
+                    verify_cmd = [
+                        "uv",
+                        "run",
+                        "--no-project",
+                        "python",
+                        "-c",
+                        f"import importlib.metadata; print(importlib.metadata.version('{package_name}'))",
+                    ]
+                    result = subprocess.run(
+                        verify_cmd, capture_output=True, timeout=30, check=False
+                    )
+                    if result.returncode == 0:
+                        version = result.stdout.decode().strip()
+                        self.checked_packages.add(package_name)
+                        if req.specifier.contains(version):
+                            logger.debug(
+                                f"Package {package_name} {version} satisfied in UV environment"
+                            )
+                            return True, version
+                        logger.debug(
+                            f"{package_name} {version} does not satisfy {req.specifier}"
+                        )
+                        return False, version
+                    # Check alternatives for optional packages
+                    if package_name in self.OPTIONAL_DB_PACKAGES:
+                        for alternative in self.OPTIONAL_DB_PACKAGES[package_name]:
+                            alt_cmd = [
+                                "uv",
+                                "run",
+                                "--no-project",
+                                "python",
+                                "-c",
+                                f"import importlib.metadata; print(importlib.metadata.version('{alternative}'))",
+                            ]
+                            alt_result = subprocess.run(
+                                alt_cmd, capture_output=True, timeout=30, check=False
+                            )
+                            if alt_result.returncode == 0:
+                                alt_version = alt_result.stdout.decode().strip()
+                                logger.info(
+                                    f"Using {alternative} as alternative to {package_name}"
+                                )
+                                self.checked_packages.add(package_name)
+                                return True, f"{alternative}:{alt_version}"
+                        # If no alternatives work, mark as optional failure
+                        self.optional_failed[package_name] = "No alternatives available"
+                        logger.warning(
+                            f"Optional package {package_name} not found, marking as optional"
+                        )
+                        return True, "optional-not-found"
+                    return False, None
+                except subprocess.TimeoutExpired:
+                    logger.warning(f"Timeout checking {package_name} in UV environment")
+                    return False, None
+                except Exception as e:
+                    logger.debug(
+                        f"Error checking {package_name} in UV environment: {e}"
+                    )
+                    return False, None
+
+            # For normal Python, try to import and check version
             try:
                 import importlib.metadata
 
@@ -671,8 +768,10 @@ class AgentDependencyLoader:
                 )
 
                 if is_uv_tool:
-                    cmd = ["uv", "pip", "install"]
-                    logger.debug("Using 'uv pip install' for UV tool environment")
+                    cmd = ["uv", "pip", "install", "--python", sys.executable]
+                    logger.debug(
+                        f"Using 'uv pip install --python {sys.executable}' for UV tool environment"
+                    )
                 else:
                     cmd = [sys.executable, "-m", "pip", "install"]
 

claude_mpm/utils/robust_installer.py

@@ -332,10 +332,12 @@ class RobustPackageInstaller:
         Returns:
             Command as list of arguments
         """
-        # UV tool environments don't have pip; use uv pip instead
+        # UV tool environments don't have pip; use uv pip install --python instead
         if self.is_uv_tool:
-            base_cmd = ["uv", "pip", "install"]
-            logger.debug("Using 'uv pip install' for UV tool environment")
+            base_cmd = ["uv", "pip", "install", "--python", sys.executable]
+            logger.debug(
+                f"Using 'uv pip install --python {sys.executable}' for UV tool environment"
+            )
         else:
             base_cmd = [sys.executable, "-m", "pip", "install"]
 
@@ -478,42 +480,56 @@ class RobustPackageInstaller:
 
     def _verify_installation(self, package_spec: str) -> bool:
         """
-        Verify that a package was successfully installed.
+        Verify that a package was successfully installed in the TARGET environment.
+
+        WHY: UV installs packages to its own Python environment, not the current process.
+        We must verify in the same environment where packages were installed.
 
         Args:
             package_spec: Package specification
 
         Returns:
-            True if package is installed and importable
+            True if package is installed and importable in the target environment
         """
         package_name = self._extract_package_name(package_spec)
 
-        # Convert package name to import name (e.g., tree-sitter-ruby -> tree_sitter_ruby)
-        import_name = package_name.replace("-", "_")
-
         try:
-            # Check if package is installed
+            if self.is_uv_tool:
+                # For UV tool, verify via UV's Python environment
+                verify_cmd = [
+                    "uv",
+                    "run",
+                    "--no-project",
+                    "python",
+                    "-c",
+                    f"import importlib.metadata; print(importlib.metadata.version('{package_name}'))",
+                ]
+                result = subprocess.run(
+                    verify_cmd, capture_output=True, timeout=30, check=False
+                )
+                if result.returncode == 0:
+                    logger.debug(
+                        f"Package {package_name} verified in UV environment: {result.stdout.decode().strip()}"
+                    )
+                    return True
+                logger.debug(
+                    f"Package {package_name} not found in UV environment: {result.stderr.decode().strip()}"
+                )
+                return False
+            # For normal Python, use importlib.metadata in current process
             import importlib.metadata
 
             try:
                 version = importlib.metadata.version(package_name)
                 logger.debug(f"Package {package_name} version {version} is installed")
-
-                # For tree-sitter packages, don't try to import (they have C extensions)
-                if package_name.startswith("tree-sitter-"):
-                    return True
-
-                # Try to import the package
-                try:
-                    __import__(import_name)
-                    return True
-                except ImportError:
-                    # Some packages have different import names, that's OK
-                    return True
+                return True
 
             except importlib.metadata.PackageNotFoundError:
                 return False
 
+        except subprocess.TimeoutExpired:
+            logger.warning(f"Verification timeout for {package_name}")
+            return False
         except ImportError:
             # Fallback for older Python versions
             try:
@@ -523,6 +539,9 @@ class RobustPackageInstaller:
                 return True
             except pkg_resources.DistributionNotFound:
                 return False
+        except Exception as e:
+            logger.debug(f"Verification error for {package_name}: {e}")
+            return False
 
     def _is_retryable_error(self, error: Optional[str]) -> bool:
         """
@@ -687,10 +706,12 @@ class RobustPackageInstaller:
             Tuple of (success, error_message)
         """
         try:
-            # UV tool environments don't have pip; use uv pip instead
+            # UV tool environments don't have pip; use uv pip install --python instead
             if self.is_uv_tool:
-                cmd = ["uv", "pip", "install"]
-                logger.debug("Using 'uv pip install' for batch installation")
+                cmd = ["uv", "pip", "install", "--python", sys.executable]
+                logger.debug(
+                    f"Using 'uv pip install --python {sys.executable}' for batch installation"
+                )
             else:
                 cmd = [sys.executable, "-m", "pip", "install"]
 

claude_mpm-5.6.72.dist-info/METADATA

@@ -0,0 +1,416 @@
+Metadata-Version: 2.4
+Name: claude-mpm
+Version: 5.6.72
+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
+License: Elastic-2.0
+Project-URL: Homepage, https://github.com/bobmatnyc/claude-mpm
+Project-URL: Repository, https://github.com/bobmatnyc/claude-mpm.git
+Project-URL: Issues, https://github.com/bobmatnyc/claude-mpm/issues
+Project-URL: Documentation, https://github.com/bobmatnyc/claude-mpm/blob/main/README.md
+Keywords: claude,orchestration,multi-agent,ticket-management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE-FAQ.md
+Requires-Dist: ai-trackdown-pytools>=1.4.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pexpect>=4.8.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: flask>=3.0.0
+Requires-Dist: flask-cors>=4.0.0
+Requires-Dist: watchdog>=3.0.0
+Requires-Dist: python-socketio>=5.14.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiohttp-cors<0.8.0,>=0.7.0
+Requires-Dist: python-engineio>=4.8.0
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: python-frontmatter>=1.0.0
+Requires-Dist: mistune>=3.0.0
+Requires-Dist: tree-sitter>=0.21.0
+Requires-Dist: ijson>=3.2.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: packaging>=21.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: pyee>=13.0.0
+Requires-Dist: pathspec>=0.11.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=0.1.0; extra == "mcp"
+Requires-Dist: mcp-vector-search>=0.1.0; extra == "mcp"
+Requires-Dist: mcp-browser>=0.1.0; extra == "mcp"
+Requires-Dist: mcp-ticketer>=0.1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.8.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"
+Requires-Dist: types-requests>=2.25.0; extra == "dev"
+Provides-Extra: eval
+Requires-Dist: deepeval>=1.0.0; extra == "eval"
+Requires-Dist: pytest>=7.4.0; extra == "eval"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "eval"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "eval"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
+Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "docs"
+Provides-Extra: monitor
+Requires-Dist: python-socketio>=5.14.0; extra == "monitor"
+Requires-Dist: aiohttp>=3.9.0; extra == "monitor"
+Requires-Dist: aiohttp-cors<0.8.0,>=0.7.0; extra == "monitor"
+Requires-Dist: python-engineio>=4.8.0; extra == "monitor"
+Requires-Dist: aiofiles>=23.0.0; extra == "monitor"
+Requires-Dist: websockets>=12.0; extra == "monitor"
+Provides-Extra: data-processing
+Requires-Dist: pandas>=2.1.0; extra == "data-processing"
+Requires-Dist: openpyxl>=3.1.0; extra == "data-processing"
+Requires-Dist: xlsxwriter>=3.1.0; extra == "data-processing"
+Requires-Dist: numpy>=1.24.0; extra == "data-processing"
+Requires-Dist: pyarrow>=14.0.0; extra == "data-processing"
+Requires-Dist: dask>=2023.12.0; extra == "data-processing"
+Requires-Dist: polars>=0.19.0; extra == "data-processing"
+Requires-Dist: xlrd>=2.0.0; extra == "data-processing"
+Requires-Dist: xlwt>=1.3.0; extra == "data-processing"
+Requires-Dist: csvkit>=1.3.0; extra == "data-processing"
+Requires-Dist: tabulate>=0.9.0; extra == "data-processing"
+Requires-Dist: python-dateutil>=2.8.0; extra == "data-processing"
+Requires-Dist: lxml>=4.9.0; extra == "data-processing"
+Requires-Dist: sqlalchemy>=2.0.0; extra == "data-processing"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "data-processing"
+Requires-Dist: pymongo>=4.5.0; extra == "data-processing"
+Requires-Dist: redis>=5.0.0; extra == "data-processing"
+Requires-Dist: beautifulsoup4>=4.12.0; extra == "data-processing"
+Requires-Dist: jsonschema>=4.19.0; extra == "data-processing"
+Provides-Extra: memory
+Requires-Dist: kuzu-memory>=1.1.5; extra == "memory"
+Dynamic: license-file
+
+# Claude MPM - Multi-Agent Project Manager
+
+A powerful orchestration framework for **Claude Code (CLI)** that enables multi-agent workflows, session management, and real-time monitoring through a streamlined Rich-based interface.
+
+> **⚠️ Important**: Claude MPM **requires Claude Code CLI** (v2.1.3+), not Claude Desktop (app). All MCP integrations work with Claude Code's CLI interface only.
+>
+> **Don't have Claude Code?** Install from: https://docs.anthropic.com/en/docs/claude-code
+>
+> **Quick Start**: See [Getting Started Guide](docs/getting-started/README.md) to get running in 5 minutes!
+
+---
+
+## Who Should Use Claude MPM?
+
+- 👥 **[Non-Technical Users (Founders/PMs)](docs/usecases/non-technical-users.md)** - Research and understand codebases using Research Mode - no coding experience required
+- 💻 **[Developers](docs/usecases/developers.md)** - Multi-agent development workflows with semantic code search and advanced features
+- 🏢 **[Teams](docs/usecases/teams.md)** - Collaboration patterns, session management, and coordinated workflows
+
+---
+
+## What is Claude MPM?
+
+Claude MPM transforms Claude Code into a **multi-agent orchestration platform** with:
+
+- **47+ Specialized Agents** - From Git repositories (Python, Rust, QA, Security, Ops, etc.)
+- **Intelligent Task Routing** - PM agent delegates work to specialist agents
+- **Session Management** - Resume previous sessions with full context preservation
+- **Semantic Code Search** - AI-powered discovery of existing code and patterns
+- **Real-Time Monitoring** - Live dashboard showing agent activity and performance
+- **Git Repository Integration** - Always up-to-date agents and skills from curated repositories
+
+---
+
+## Quick Installation
+
+### Prerequisites
+
+1. **Python 3.11+** (required - older versions will install outdated claude-mpm)
+2. **Claude Code CLI v2.1.3+** (required!)
+
+> ⚠️ **Python Version Note**: Claude MPM requires Python 3.11 or higher. If you have Python 3.9 or 3.10, you'll get an old version (4.x) that lacks current features. Check with `python3 --version` before installing.
+
+```bash
+# Verify Claude Code is installed
+claude --version
+
+# If not installed, get it from:
+# https://docs.anthropic.com/en/docs/claude-code
+```
+
+### Install Claude MPM
+
+**Homebrew (macOS):**
+```bash
+brew install claude-mpm --with-monitor
+```
+
+**pipx/uv (recommended):**
+```bash
+# With pipx
+pipx install "claude-mpm[monitor]"
+
+# Or with uv
+uv tool install "claude-mpm[monitor]"
+```
+
+**pip:**
+```bash
+pip install "claude-mpm[monitor]"
+```
+
+### Verify Installation
+
+```bash
+# Check versions
+claude-mpm --version
+claude --version
+
+# Run diagnostics
+claude-mpm doctor
+
+# Verify agents deployed
+ls ~/.claude/agents/    # Should show 47+ agents
+```
+
+**What You Should See:**
+- ✅ 47+ agents deployed to `~/.claude/agents/`
+- ✅ 17 bundled skills (in Python package)
+- ✅ Agent sources configured
+- ✅ Progress bars showing sync and deployment
+
+**💡 Recommended Partners**: Install [kuzu-memory](https://github.com/bobmatnyc/kuzu-memory) (persistent context) and [mcp-vector-search](https://github.com/bobmatnyc/mcp-vector-search) (semantic search) for enhanced capabilities.
+
+**💡 Tool Version Management**: Use [ASDF version manager](docs/guides/asdf-tool-versions.md) to avoid Python/uv version conflicts across projects.
+
+---
+
+## Key Features
+
+### 🎯 Multi-Agent Orchestration
+- **47+ Specialized Agents** from Git repositories covering all development needs
+- **Smart Task Routing** via PM agent intelligently delegating to specialists
+- **Session Management** with `--resume` flag for seamless continuity
+- **Resume Log System** with automatic 10k-token summaries at 70%/85%/95% thresholds
+
+[→ Learn more: Multi-Agent Development](docs/usecases/developers.md#multi-agent-development)
+
+### 📦 Git Repository Integration
+- **Curated Content** with 47+ agents automatically deployed from repositories
+- **Always Up-to-Date** with ETag-based caching (95%+ bandwidth reduction)
+- **Hierarchical BASE-AGENT.md** for template inheritance and DRY principles
+- **Custom Repositories** via `claude-mpm agent-source add`
+
+[→ Learn more: Agent Sources](docs/user/agent-sources.md)
+
+### 🎯 Skills System
+- **17 Bundled Skills** covering Git, TDD, Docker, API docs, testing, and more
+- **Three-Tier Organization**: Bundled/user/project with priority resolution
+- **Auto-Linking** to relevant agents based on roles
+- **Custom Skills** via `.claude/skills/` or skill repositories
+
+[→ Learn more: Skills Guide](docs/user/skills-guide.md)
+
+### 🔍 Semantic Code Search
+- **AI-Powered Discovery** with mcp-vector-search integration
+- **Find by Intent** not just keywords ("authentication logic" finds relevant code)
+- **Pattern Recognition** for discovering similar implementations
+- **Live Updates** tracking code changes automatically
+
+[→ Learn more: Developer Use Cases](docs/usecases/developers.md#semantic-code-search)
+
+### 🧪 MPM Commander (ALPHA)
+- **Multi-Project Orchestration** with autonomous AI coordination across codebases
+- **Tmux Integration** for isolated project environments and session management
+- **Event-Driven Architecture** with inbox system for cross-project communication
+- **LLM-Powered Decisions** via OpenRouter for autonomous work queue processing
+- **Real-Time Monitoring** with state tracking (IDLE, WORKING, BLOCKED, PAUSED, ERROR)
+- ⚠️ **Experimental** - API and CLI interface subject to change
+
+[→ Commander Documentation](docs/commander/usage-guide.md)
+
+### 🔌 Advanced Integration
+- **MCP Integration** with full Model Context Protocol support
+- **Real-Time Monitoring** via `--monitor` flag and web dashboard
+- **Multi-Project Support** with per-session working directories
+- **Git Integration** with diff viewing and change tracking
+
+[→ Learn more: MCP Gateway](docs/developer/13-mcp-gateway/README.md)
+
+### 🔐 OAuth & Google Workspace Integration
+- **Browser-Based OAuth** for secure authentication with MCP services
+- **Google Workspace MCP** built-in server for Gmail, Calendar, and Drive
+- **Encrypted Token Storage** using Fernet encryption with system keychain
+- **Automatic Token Refresh** handles expiration seamlessly
+
+```bash
+# Set up Google Workspace OAuth
+claude-mpm oauth setup workspace-mcp
+
+# Check token status
+claude-mpm oauth status workspace-mcp
+
+# List OAuth-capable services
+claude-mpm oauth list
+```
+
+[→ Learn more: OAuth Setup Guide](docs/guides/oauth-setup.md)
+
+### ⚡ Performance & Security
+- **Simplified Architecture** with ~3,700 lines removed for better performance
+- **Enhanced Security** with comprehensive input validation
+- **Intelligent Caching** with ~200ms faster startup via hash-based invalidation
+- **Memory Management** with cleanup commands for large conversation histories
+
+[→ Learn more: Architecture](docs/developer/ARCHITECTURE.md)
+
+---
+
+## Quick Usage
+
+```bash
+# Start interactive mode
+claude-mpm
+
+# Start with monitoring dashboard
+claude-mpm run --monitor
+
+# Resume previous session
+claude-mpm run --resume
+
+# Semantic code search
+claude-mpm search "authentication logic"
+# or inside Claude Code:
+/mpm-search "authentication logic"
+
+# Health diagnostics
+claude-mpm doctor
+
+# Verify MCP services
+claude-mpm verify
+
+# Manage memory
+claude-mpm cleanup-memory
+```
+
+**💡 Update Checking**: Claude MPM automatically checks for updates and verifies Claude Code compatibility on startup. Configure in `~/.claude-mpm/configuration.yaml` or see [docs/update-checking.md](docs/update-checking.md).
+
+[→ Complete usage examples: User Guide](docs/user/user-guide.md)
+
+---
+
+## What's New in v5.0
+
+### Git Repository Integration for Agents & Skills
+
+- **📦 Massive Library**: 47+ agents and hundreds of skills deployed automatically
+- **🏢 Official Content**: Anthropic's official skills repository included by default
+- **🔧 Fully Extensible**: Add your own repositories with immediate testing
+- **🌳 Smart Organization**: Hierarchical BASE-AGENT.md inheritance
+- **📊 Clear Visibility**: Two-phase progress bars (sync + deployment)
+- **✅ Fail-Fast Testing**: Test repositories before they cause startup issues
+
+**Quick Start with Custom Repositories:**
+```bash
+# Add custom agent repository
+claude-mpm agent-source add https://github.com/yourorg/your-agents
+
+# Add custom skill repository
+claude-mpm skill-source add https://github.com/yourorg/your-skills
+
+# Test repository without saving
+claude-mpm agent-source add https://github.com/yourorg/your-agents --test
+```
+
+[→ Full details: What's New](CHANGELOG.md)
+
+---
+
+## Documentation
+
+**📚 [Complete Documentation Hub](docs/README.md)** - Start here for all documentation!
+
+### Quick Links by User Type
+
+#### 👥 For Users
+- **[🚀 5-Minute Quick Start](docs/user/quickstart.md)** - Get running immediately
+- **[📦 Installation Guide](docs/user/installation.md)** - All installation methods
+- **[📖 User Guide](docs/user/user-guide.md)** - Complete user documentation
+- **[❓ FAQ](docs/guides/FAQ.md)** - Common questions answered
+
+#### 💻 For Developers
+- **[🏗️ Architecture Overview](docs/developer/ARCHITECTURE.md)** - Service-oriented system design
+- **[💻 Developer Guide](docs/developer/README.md)** - Complete development documentation
+- **[🧪 Contributing](docs/developer/03-development/README.md)** - How to contribute
+- **[📊 API Reference](docs/API.md)** - Complete API documentation
+
+#### 🤖 For Agent Creators
+- **[🤖 Agent System](docs/AGENTS.md)** - Complete agent development guide
+- **[📝 Creation Guide](docs/developer/07-agent-system/creation-guide.md)** - Step-by-step tutorials
+- **[📋 Schema Reference](docs/developer/10-schemas/agent_schema_documentation.md)** - Agent format specifications
+
+#### 🚀 For Operations
+- **[🚀 Deployment](docs/DEPLOYMENT.md)** - Release management & versioning
+- **[📊 Monitoring](docs/MONITOR.md)** - Real-time dashboard & metrics
+- **[🐛 Troubleshooting](docs/TROUBLESHOOTING.md)** - Enhanced `doctor` command with auto-fix
+
+---
+
+## Contributing
+
+Contributions are welcome! Please see:
+- **[Contributing Guide](docs/developer/03-development/README.md)** - How to contribute
+- **[Code Formatting](docs/developer/CODE_FORMATTING.md)** - Code quality standards
+- **[Project Structure](docs/reference/STRUCTURE.md)** - Codebase organization
+
+**Development Workflow:**
+```bash
+# Complete development setup
+make dev-complete
+
+# Or step by step:
+make setup-dev          # Install in development mode
+make setup-pre-commit   # Set up automated code formatting
+```
+
+---
+
+## 📜 License
+
+[![License](https://img.shields.io/badge/License-Elastic_2.0-blue.svg)](LICENSE)
+
+Licensed under the [Elastic License 2.0](LICENSE) - free for internal use and commercial products.
+
+**Main restriction:** Cannot offer as a hosted SaaS service without a commercial license.
+
+📖 [Licensing FAQ](LICENSE-FAQ.md) | 💼 Commercial licensing: bob@matsuoka.com
+
+---
+
+## Credits
+
+- Based on [claude-multiagent-pm](https://github.com/kfsone/claude-multiagent-pm)
+- Enhanced for [Claude Code (CLI)](https://docs.anthropic.com/en/docs/claude-code) integration
+- Built with ❤️ by the Claude MPM community