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

{claude_mpm-4.24.0.dist-info → claude_mpm-5.4.41.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.24.0
+Version: 5.4.41
 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: MIT
+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
@@ -12,15 +12,15 @@ Project-URL: Documentation, https://github.com/bobmatnyc/claude-mpm/blob/main/RE
 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.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
+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>=0.19.0
@@ -46,8 +46,8 @@ 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: importlib-resources>=5.0; python_version < "3.9"
 Requires-Dist: pathspec>=0.11.0
 Requires-Dist: kuzu-memory>=1.1.5
 Provides-Extra: mcp
@@ -59,17 +59,17 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 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: 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"
@@ -81,81 +81,6 @@ 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: agents
-Requires-Dist: alembic>=1.13.0; extra == "agents"
-Requires-Dist: astroid>=3.0.0; extra == "agents"
-Requires-Dist: axe-selenium-python>=2.1.0; extra == "agents"
-Requires-Dist: bandit>=1.7.5; extra == "agents"
-Requires-Dist: beautifulsoup4>=4.12.0; extra == "agents"
-Requires-Dist: black>=24.0.0; extra == "agents"
-Requires-Dist: click>=8.1.0; extra == "agents"
-Requires-Dist: commitizen>=3.13.0; extra == "agents"
-Requires-Dist: coverage>=7.0.0; extra == "agents"
-Requires-Dist: csvkit>=1.3.0; extra == "agents"
-Requires-Dist: dask>=2023.12.0; extra == "agents"
-Requires-Dist: detect-secrets>=1.4.0; extra == "agents"
-Requires-Dist: diagrams>=0.23.0; extra == "agents"
-Requires-Dist: docstring-parser>=0.15.0; extra == "agents"
-Requires-Dist: faker>=20.0.0; extra == "agents"
-Requires-Dist: flake8>=7.0.0; extra == "agents"
-Requires-Dist: gitlint>=0.19.0; extra == "agents"
-Requires-Dist: gitpython>=3.1.40; extra == "agents"
-Requires-Dist: google-auth>=2.0.0; extra == "agents"
-Requires-Dist: google-cloud-core>=2.0.0; extra == "agents"
-Requires-Dist: hypothesis>=6.98.0; extra == "agents"
-Requires-Dist: isort>=5.13.0; extra == "agents"
-Requires-Dist: jinja2>=3.1.0; extra == "agents"
-Requires-Dist: jsonschema>=4.19.0; extra == "agents"
-Requires-Dist: libcst>=1.1.0; extra == "agents"
-Requires-Dist: lizard>=1.17.0; extra == "agents"
-Requires-Dist: lxml>=4.9.0; extra == "agents"
-Requires-Dist: mermaid-py>=0.2.0; extra == "agents"
-Requires-Dist: mkdocs>=1.5.0; extra == "agents"
-Requires-Dist: mutmut>=2.4.0; extra == "agents"
-Requires-Dist: mypy>=1.8.0; extra == "agents"
-Requires-Dist: numpy>=1.24.0; extra == "agents"
-Requires-Dist: openpyxl>=3.1.0; extra == "agents"
-Requires-Dist: pandas>=2.1.0; extra == "agents"
-Requires-Dist: pathlib; extra == "agents"
-Requires-Dist: pillow>=9.0.0; extra == "agents"
-Requires-Dist: playwright>=1.40.0; extra == "agents"
-Requires-Dist: polars>=0.19.0; extra == "agents"
-Requires-Dist: pre-commit>=3.5.0; extra == "agents"
-Requires-Dist: prometheus-client>=0.19.0; extra == "agents"
-Requires-Dist: psycopg2-binary>=2.9.0; extra == "agents"
-Requires-Dist: pyarrow>=14.0.0; extra == "agents"
-Requires-Dist: pydantic>=2.6.0; extra == "agents"
-Requires-Dist: pydoc-markdown>=4.8.0; extra == "agents"
-Requires-Dist: pydriller>=2.5.0; extra == "agents"
-Requires-Dist: pygments>=2.17.0; extra == "agents"
-Requires-Dist: pyjwt>=2.8.0; extra == "agents"
-Requires-Dist: pylint>=3.0.0; extra == "agents"
-Requires-Dist: pymongo>=4.5.0; extra == "agents"
-Requires-Dist: pymysql>=1.1.0; extra == "agents"
-Requires-Dist: pytest>=8.0.0; extra == "agents"
-Requires-Dist: pytest-asyncio>=0.23.0; extra == "agents"
-Requires-Dist: pytest-benchmark>=4.0.0; extra == "agents"
-Requires-Dist: pytest-cov>=4.1.0; extra == "agents"
-Requires-Dist: python-dateutil>=2.8.0; extra == "agents"
-Requires-Dist: pyyaml>=6.0; extra == "agents"
-Requires-Dist: radon>=6.0.0; extra == "agents"
-Requires-Dist: redis>=5.0.0; extra == "agents"
-Requires-Dist: requests>=2.31.0; extra == "agents"
-Requires-Dist: rich>=13.0.0; extra == "agents"
-Requires-Dist: rope>=1.11.0; extra == "agents"
-Requires-Dist: safety>=3.0.0; extra == "agents"
-Requires-Dist: semantic-version>=2.10.0; extra == "agents"
-Requires-Dist: semgrep>=1.45.0; extra == "agents"
-Requires-Dist: sphinx>=7.2.0; extra == "agents"
-Requires-Dist: sqlalchemy>=2.0.0; extra == "agents"
-Requires-Dist: sqlparse>=0.4.4; extra == "agents"
-Requires-Dist: tabulate>=0.9.0; extra == "agents"
-Requires-Dist: tree-sitter>=0.21.0; extra == "agents"
-Requires-Dist: vaex>=4.17.0; extra == "agents"
-Requires-Dist: validators>=0.20.0; extra == "agents"
-Requires-Dist: xlrd>=2.0.0; extra == "agents"
-Requires-Dist: xlsxwriter>=3.1.0; extra == "agents"
-Requires-Dist: xlwt>=1.3.0; extra == "agents"
 Provides-Extra: data-processing
 Requires-Dist: pandas>=2.1.0; extra == "data-processing"
 Requires-Dist: openpyxl>=3.1.0; extra == "data-processing"
@@ -176,8 +101,6 @@ 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: agents-load-testing
-Requires-Dist: locust>=2.15.0; extra == "agents-load-testing"
 Dynamic: license-file
 
 # Claude MPM - Multi-Agent Project Manager
@@ -194,19 +117,111 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 
 > **Quick Start**: See [docs/user/getting-started.md](docs/user/getting-started.md) to get running in 5 minutes!
 
+## 🚀 What's New in v5.0
+
+### Git Repository Integration for Agents & Skills
+
+Claude MPM now supports **Git repositories** for distributing and managing agents and skills - the most requested feature from our community!
+
+**🎯 Key Highlights:**
+- **📦 Massive Library**: 47+ agents and hundreds of skills deployed automatically from curated repositories
+- **🏢 Official Content**: Anthropic's official skills repository included by default
+- **🔧 Fully Extensible**: Add your own agent/skill repositories with immediate testing
+- **🌳 Smart Organization**: Hierarchical BASE-AGENT.md inheritance for shared templates
+- **📊 Clear Visibility**: Two-phase progress bars show sync and deployment status
+- **✅ Fail-Fast Testing**: Test repositories before they cause startup issues
+
+#### Quick Start: Add Your Own Repository
+
+```bash
+# Add custom agent repository (with immediate testing)
+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
+
+# List all configured sources
+claude-mpm agent-source list
+```
+
+#### Default Repositories
+
+**Agents** (47+ agents):
+- 🏢 System: `bobmatnyc/claude-mpm-agents` - Core agent templates
+
+**Skills** (hundreds of skills):
+- 🏢 System: `bobmatnyc/claude-mpm-skills` - Community skills
+- 🎯 Official: `anthropics/skills` - Anthropic's official skills (14+ skills)
+
+**What This Means:**
+- ✅ **Automatic Setup**: Everything deploys on first run
+- ✅ **Always Updated**: Git repositories sync on startup
+- ✅ **Nested Support**: Repositories with subdirectories are automatically flattened
+- ✅ **Template Inheritance**: BASE-AGENT.md files cascade from parent directories
+- ✅ **Priority System**: Control which sources win when multiple repos provide the same agent/skill
+
+#### Hierarchical Organization Example
+
+Support for BASE-AGENT.md enables powerful template inheritance:
+
+```
+your-agents/
+  BASE-AGENT.md              # Root shared content (all agents inherit)
+  engineering/
+    BASE-AGENT.md            # Engineering-specific (engineering/* agents inherit)
+    python/
+      fastapi-engineer.md    # Inherits both BASE files
+```
+
+See [docs/features/hierarchical-base-agents.md](docs/features/hierarchical-base-agents.md) for complete guide.
+
 ## Features
 
-- 🤖 **Multi-Agent System**: 37 specialized agents for comprehensive project management
-- 🎯 **Skills System**: 21 bundled skills with auto-linking, three-tier organization (bundled/user/project), and interactive configuration
-- 🔄 **Session Management**: Resume previous sessions with `--resume`
-- 📋 **Resume Log System**: Proactive context management with automatic 10k-token session logs at 70%/85%/95% thresholds
-- 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
-- 🔌 **MCP Integration**: Full support for Model Context Protocol services
-- 📁 **Multi-Project Support**: Per-session working directories
-- 🔍 **Git Integration**: View diffs and track changes across projects
-- 🎯 **Smart Task Orchestration**: PM agent intelligently routes work to specialists
-- ⚡ **Simplified Architecture**: ~3,700 lines removed for better performance and maintainability
-- 🔒 **Enhanced Security**: Comprehensive input validation and sanitization framework
+### 🎯 Multi-Agent Orchestration
+
+- **47+ Specialized Agents**: Comprehensive coverage from Git repositories (Python, Rust, QA, Security, Ops, etc.)
+- **Smart Task Routing**: PM agent intelligently delegates work to specialist agents
+- **Session Management**: Resume previous sessions with `--resume`
+- **Resume Log System**: Proactive context management with automatic 10k-token session logs at 70%/85%/95% thresholds
+
+### 📦 Git Repository Integration (NEW in v5.0)
+
+- **🏢 Curated Content**: Default repositories with 47+ agents and hundreds of skills
+- **🎯 Official Skills**: Anthropic's official skills included by default
+- **🔧 Custom Repositories**: Add your own via CLI or configuration
+- **🌳 Nested Support**: Automatic flattening of nested directory structures
+- **📝 Template Inheritance**: BASE-AGENT.md for hierarchical organization
+- **✅ Immediate Testing**: Fail-fast validation when adding repositories
+- **📊 Progress Visibility**: Two-phase progress bars (sync + deployment)
+- **⚡ Smart Caching**: ETag-based caching reduces bandwidth by 95%+
+
+### 🎯 Skills System
+
+- **Hundreds of Skills**: Comprehensive skill library from curated repositories
+- **Official Skills**: 14+ skills from Anthropic's official repository
+- **Three-Tier Organization**: Bundled/user/project skills with priority resolution
+- **Auto-Linking**: Skills automatically linked to relevant agents
+- **Interactive Configuration**: Skills wizard via `claude-mpm configure`
+- **Version Tracking**: Semantic versioning for all skills
+
+### 🔌 Advanced Integration
+
+- **MCP Integration**: Full support for Model Context Protocol services
+- **Real-Time Monitoring**: Live dashboard with `--monitor` flag
+- **Multi-Project Support**: Per-session working directories
+- **Git Integration**: View diffs and track changes across projects
+
+### ⚡ Performance & Security
+
+- **Simplified Architecture**: ~3,700 lines removed for better performance
+- **Enhanced Security**: Comprehensive input validation and sanitization
+- **Intelligent Caching**: File-based instruction caching for optimal performance
+  - ✅ Eliminates ARG_MAX limits on Linux (exceeds by 19.1%) and Windows (exceeds by 476%)
+  - ✅ ~200ms faster agent startup with hash-based cache invalidation
+  - ✅ Automatic and transparent (no configuration required)
 
 ## Quick Installation
 
@@ -214,7 +229,7 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 
 **Before installing Claude MPM**, ensure you have:
 
-1. **Python 3.8+** (3.11+ recommended)
+1. **Python 3.11+** (required for kuzu-memory dependency)
 2. **Claude Code CLI v1.0.92+** (required!)
 
 ```bash
@@ -231,17 +246,28 @@ claude --version
 # Basic installation
 pip install claude-mpm
 
+# Or with uv (faster)
+uv tool install claude-mpm
+
 # Install with monitoring dashboard (recommended)
 pip install "claude-mpm[monitor]"
+uv tool install "claude-mpm[monitor]"
 ```
 
-Or with pipx (recommended for isolated installation):
+Or with pipx/uvx (recommended for isolated installation):
 ```bash
 # Basic installation
 pipx install claude-mpm
 
+# Or with uv tool (permanent installation)
+uv tool install claude-mpm
+
+# Or with uvx (one-off execution)
+uvx claude-mpm
+
 # Install with monitoring dashboard (recommended)
 pipx install "claude-mpm[monitor]"
+uv tool install "claude-mpm[monitor]"
 ```
 
 ### Verify Installation
@@ -253,8 +279,25 @@ claude --version
 
 # Run diagnostics (checks Claude Code compatibility)
 claude-mpm doctor
+
+# Verify Git repositories are synced
+ls ~/.claude/agents/    # Should show 47+ agents
+ls ~/.claude/skills/    # Should show hundreds of skills
+
+# Check agent sources
+claude-mpm agent-source list
+
+# Check skill sources
+claude-mpm skill-source list
 ```
 
+**What You Should See:**
+- ✅ 47+ agents deployed to `~/.claude/agents/`
+- ✅ Hundreds of skills deployed to `~/.claude/skills/`
+- ✅ Two agent sources configured (system + official)
+- ✅ Two skill sources configured (system + official)
+- ✅ Progress bars showing sync and deployment phases
+
 **💡 Optional Dependencies**:
 - `[monitor]` - Full monitoring dashboard with Socket.IO and async web server components
 - `[mcp]` - Additional MCP services (mcp-browser, mcp-ticketer) - most users won't need this
@@ -276,6 +319,8 @@ Claude MPM works excellently with these complementary MCP tools. While optional,
 **Installation:**
 ```bash
 pipx install kuzu-memory
+# Or with uv
+uv tool install kuzu-memory
 ```
 
 **Benefits with Claude MPM:**
@@ -298,6 +343,8 @@ pipx install kuzu-memory
 **Installation:**
 ```bash
 pipx install mcp-vector-search
+# Or with uv
+uv tool install mcp-vector-search
 ```
 
 **Benefits with Claude MPM:**
@@ -322,6 +369,10 @@ Install both recommended tools in one go:
 ```bash
 pipx install kuzu-memory
 pipx install mcp-vector-search
+
+# Or with uv
+uv tool install kuzu-memory
+uv tool install mcp-vector-search
 ```
 
 Then verify they're working:
@@ -334,6 +385,67 @@ claude-mpm verify
 
 **That's it!** See [docs/user/getting-started.md](docs/user/getting-started.md) for immediate usage.
 
+## Cache Management
+
+Claude MPM maintains a local cache of agent templates at `~/.claude-mpm/cache/agents/`.
+
+### Cache Structure
+
+```
+~/.claude-mpm/cache/agents/
+└── bobmatnyc/
+    └── claude-mpm-agents/
+        ├── .git/              # Git repository
+        ├── agents/            # 45+ agent templates
+        └── docs/
+```
+
+> **Note**: Prior to v5.4.23, agents were cached to `~/.claude-mpm/cache/remote-agents/`. This has been standardized to `~/.claude-mpm/cache/agents/`. Existing caches are automatically migrated.
+
+### Git Workflow (Optional)
+
+If your cache is a git repository, you can manage agents with git operations:
+
+```bash
+# Check cache status
+claude-mpm agents cache-status
+
+# Pull latest agents
+claude-mpm agents cache-pull
+
+# Commit local changes
+claude-mpm agents cache-commit --message "feat: update agents"
+
+# Push changes
+claude-mpm agents cache-push
+
+# Full sync workflow
+claude-mpm agents cache-sync
+```
+
+**Or use Makefile targets:**
+
+```bash
+make agents-cache-status   # Show git status
+make agents-cache-pull     # Pull latest
+make agents-cache-sync     # Full sync (pull + commit + push)
+make deploy-agents         # Deploy with auto-pull
+```
+
+### HTTP Sync Fallback
+
+If cache is not a git repository, Claude MPM automatically falls back to HTTP sync with GitHub API.
+
+### Migration from Legacy Cache
+
+If you have an old `cache/agents/` directory, run the migration script:
+
+```bash
+python scripts/migrate_cache_to_remote_agents.py
+```
+
+**See also:** [docs/CACHE_MANAGEMENT.md](docs/CACHE_MANAGEMENT.md) for comprehensive cache management guide.
+
 ## Quick Usage
 
 ```bash
@@ -386,10 +498,188 @@ claude-mpm doctor --checks updates
 
 See [docs/user/getting-started.md](docs/user/getting-started.md) for complete usage examples.
 
+## Managing Agent & Skill Repositories
+
+Claude MPM uses **Git repositories** to distribute and manage agents and skills. This provides automatic updates, version control, and easy sharing of agent/skill libraries.
+
+### Quick Start
+
+```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 (fail-fast validation)
+claude-mpm agent-source add https://github.com/yourorg/your-agents --test
+
+# List configured sources
+claude-mpm agent-source list
+claude-mpm skill-source list
+
+# Update from all sources
+claude-mpm agent-source update
+claude-mpm skill-source update
+```
+
+### Priority System
+
+When multiple sources provide the same agent/skill, priority controls which one wins:
+
+- **Lower number = Higher precedence** (priority 10 beats priority 100)
+- **Local agents/skills** (`.claude-mpm/agents/`, `.claude-mpm/skills/`) always override
+- **System defaults** provide fallback
+
+**Example Configuration:**
+
+```yaml
+# ~/.claude-mpm/config/agent_sources.yaml
+repositories:
+  - url: https://github.com/myteam/agents
+    priority: 10    # Highest precedence (custom agents)
+
+  - url: https://github.com/bobmatnyc/claude-mpm-agents
+    priority: 100   # System default (official agents)
+```
+
+### Hierarchical Organization with BASE-AGENT.md
+
+Support for BASE-AGENT.md enables powerful template inheritance:
+
+```
+your-agents/
+  BASE-AGENT.md              # Root shared content (all agents inherit)
+  engineering/
+    BASE-AGENT.md            # Engineering-specific (engineering/* inherit)
+    python/
+      fastapi-engineer.md    # Inherits both BASE files
+      django-engineer.md     # Inherits both BASE files
+    rust/
+      systems-engineer.md    # Inherits both BASE files
+```
+
+**How It Works:**
+1. **Cascading Inheritance**: Each agent inherits from all BASE-AGENT.md files in parent directories
+2. **Automatic Flattening**: Nested repositories are automatically flattened during deployment
+3. **DRY Templates**: Share common instructions across related agents
+4. **Maintainability**: Update shared content in one place
+
+See [docs/features/hierarchical-base-agents.md](docs/features/hierarchical-base-agents.md) for complete guide.
+
+### Configuration via YAML
+
+Edit configuration files directly:
+- **Agents**: `~/.claude-mpm/config/agent_sources.yaml`
+- **Skills**: `~/.claude-mpm/config/skill_sources.yaml`
+
+**Example agent_sources.yaml:**
+
+```yaml
+repositories:
+  - url: https://github.com/bobmatnyc/claude-mpm-agents
+    priority: 100
+    enabled: true
+
+  - url: https://github.com/yourorg/custom-agents
+    priority: 10
+    enabled: true
+```
+
+### Benefits
+
+✅ **Always Up-to-Date**: Repositories sync automatically on startup
+✅ **Bandwidth Efficient**: ETag-based caching reduces network usage by 95%+
+✅ **Version Control**: Track changes through Git history
+✅ **Immediate Testing**: Fail-fast validation prevents startup issues
+✅ **Nested Support**: Automatic flattening of directory structures
+✅ **Template Inheritance**: BASE-AGENT.md for DRY principles
+✅ **Progress Visibility**: Two-phase progress bars (sync + deployment)
+✅ **Community Access**: Latest improvements available immediately
+✅ **Organization Libraries**: Share team-specific content across projects
+
+### Documentation
+
+- **[Agent Sources User Guide](docs/user/agent-sources.md)** - Complete guide with examples
+- **[CLI Reference](docs/reference/cli-agent-source.md)** - All `agent-source` commands
+- **[Hierarchical BASE-AGENT.md](docs/features/hierarchical-base-agents.md)** - Template inheritance guide
+- **[Migration Guide](docs/migration/agent-sources-git-default-v4.5.0.md)** - Upgrading from v4.4.x
+- **[Troubleshooting](docs/user/troubleshooting.md#agent-source-issues)** - Common issues and solutions
+
+## Skills Deployment
 
-## Architecture (v4.4.1)
+Skills are automatically deployed from Git repositories, just like agents. Claude MPM includes **hundreds of skills** from curated repositories:
 
-Following Phase 3 architectural simplification in v4.4.1, Claude MPM features:
+- **System Skills**: Community skills from `bobmatnyc/claude-mpm-skills`
+- **Official Skills**: Anthropic's official skills from `anthropics/skills`
+- **Custom Skills**: Add your own skill repositories
+
+### Quick Usage
+
+```bash
+# Skills are automatically deployed on first run
+# No manual deployment needed!
+
+# Add custom skill repository
+claude-mpm skill-source add https://github.com/yourorg/custom-skills
+
+# List configured skill sources
+claude-mpm skill-source list
+
+# Update skills from all sources
+claude-mpm skill-source update
+```
+
+### How Skills Work
+
+1. **Automatic Deployment**: All skills from configured repositories deploy on startup
+2. **Three-Tier Organization**:
+   - **Bundled**: System and official skills (hundreds)
+   - **User**: Custom skills in `~/.config/claude-mpm/skills/`
+   - **Project**: Project-specific skills in `.claude-mpm/skills/`
+3. **Priority Resolution**: Project → User → Bundled (local always wins)
+4. **Auto-Linking**: Skills automatically linked to relevant agents
+5. **Version Tracking**: All skills support semantic versioning
+
+### Technology → Skills Mapping
+
+The Research agent automatically analyzes your project and recommends relevant skills:
+
+| Your Technology | Auto-Recommended Skills |
+|-----------------|-------------------------|
+| Python + pytest | test-driven-development, python-style |
+| FastAPI/Flask | backend-engineer |
+| React/Next.js | frontend-development, web-frameworks |
+| Docker | docker-workflow |
+| GitHub Actions | ci-cd-pipeline-builder |
+| Playwright | webapp-testing |
+
+### Interactive Management
+
+```bash
+# Interactive skills wizard
+claude-mpm configure
+# Choose option 2: Skills Management
+
+# Features:
+# - View all deployed skills
+# - Configure skill assignments to agents
+# - Auto-link skills based on agent roles
+# - Manage custom skill repositories
+```
+
+### Important Notes
+
+- ⚠️ Skills load at **Claude Code startup only** - restart required after adding repositories
+- ✅ Batch add related skill repositories to minimize restarts
+- ✅ Research agent automatically recommends missing skills during project analysis
+- See [Skills Deployment Guide](docs/guides/skills-deployment-guide.md) for comprehensive details
+- See [Skills Quick Reference](docs/reference/skills-quick-reference.md) for command reference
+
+
+## Architecture
+
+Claude MPM features a clean, service-oriented architecture:
 
 - **Streamlined Rich Interface**: Removed complex TUI system (~2,500 lines) for cleaner user experience
 - **MCP Integration**: Full support for Model Context Protocol services with automatic detection
@@ -447,7 +737,19 @@ Claude MPM includes 15 specialized agents:
 - **Code Analyzer** - Static code analysis with AST and tree-sitter
 
 ### Agent Memory System
-Agents learn project-specific patterns using a simple list format and can update memories via JSON response fields (`remember` for incremental updates, `MEMORIES` for complete replacement). Initialize with `claude-mpm memory init`.
+
+**NEW in v5.4.13**: Runtime memory loading for instant updates and better efficiency.
+
+**How It Works:**
+- **Memory Files**: Store agent memories in `.claude-mpm/memories/{agent_id}.md` (e.g., `engineer.md`, `qa.md`)
+- **Runtime Loading**: Memories loaded dynamically when agents are delegated to (no restart required)
+- **Instant Updates**: Memory changes take effect immediately
+- **Event Observability**: Memory loading tracked via EventBus (`agent.memory.loaded` events)
+
+**Memory Format:**
+Agents learn project-specific patterns using a simple markdown list format and can update memories via JSON response fields (`remember` for incremental updates, `MEMORIES` for complete replacement).
+
+**See:** [Memory Flow Architecture](docs/architecture/memory-flow.md) for complete technical details.
 
 ### Skills System
 
@@ -612,25 +914,49 @@ See [docs/reference/MEMORY.md](docs/reference/MEMORY.md) and [docs/developer/11-
 - **Cross-Referenced**: Links between related topics and sections
 - **Up-to-Date**: Version 4.16.3 with web performance optimization skill
 
-## Recent Updates (v4.16.3)
-
-**Web Performance Optimization**: New `web-performance-optimization` skill for Lighthouse metrics, Core Web Vitals (LCP, INP, CLS), and framework-specific optimization patterns.
-
-## Previous Updates (v4.16.1)
+## Recent Updates (v5.0) 🎉
+
+**Major Release**: Git Repository Integration for Agents & Skills
+
+**🚀 What's New:**
+- **Git Repository Support**: Agents and skills now deploy from Git repositories
+- **47+ Agents**: Comprehensive agent library from curated repositories
+- **Hundreds of Skills**: System skills + Official Anthropic skills automatically deployed
+- **Hierarchical BASE-AGENT.md**: Template inheritance for DRY principles
+- **Nested Repository Support**: Automatic flattening of directory structures
+- **Immediate Testing**: Fail-fast validation when adding repositories
+- **Two-Phase Progress**: Clear visibility during sync and deployment
+- **ETag Caching**: 95%+ bandwidth reduction with intelligent caching
+
+**🔧 Repository Management:**
+- `claude-mpm agent-source add/list/update` - Manage agent repositories
+- `claude-mpm skill-source add/list/update` - Manage skill repositories
+- Priority-based resolution for multiple sources
+- YAML configuration support
+
+**📚 Documentation:**
+- Complete guides for Git repository integration
+- Hierarchical BASE-AGENT.md documentation
+- Migration guides for existing installations
+- Troubleshooting and best practices
+
+**🎯 Benefits:**
+- Always up-to-date content from repositories
+- Community-driven agent and skill libraries
+- Easy sharing of organizational content
+- Version control for all templates
 
-**Local Development Skills**: Added 4 new toolchain-specific skills: `nextjs-local-dev`, `fastapi-local-dev`, `vite-local-dev`, and `express-local-dev` for professional local server management with PM2, HMR, and production-grade patterns.
-
-**Skills System Integration**: 20 bundled skills with auto-linking, three-tier organization, and interactive configuration. Eliminates 85% of redundant guidance across agent templates (~15,000 lines of reusable content).
+See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/user/MIGRATION.md](docs/user/MIGRATION.md) for upgrade instructions.
 
-**Enhanced Documentation**: Complete documentation suite with PDF guides, reorganized structure, and comprehensive design documents for skills integration.
+## 📜 License
 
-**Agent Template Improvements**: Cleaned agent templates with skills integration, removing redundant guidance while maintaining full capability coverage.
+[![License](https://img.shields.io/badge/License-Elastic_2.0-blue.svg)](LICENSE)
 
-**Interactive Skills Management**: New skills wizard accessible via `claude-mpm configure` for viewing, configuring, and auto-linking skills to agents.
+Licensed under the [Elastic License 2.0](LICENSE) - free for internal use and commercial products.
 
-**Bug Fixes**: Resolved agent template inconsistencies and improved configuration management.
+**Main restriction:** Cannot offer as a hosted SaaS service without a commercial license.
 
-See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/user/MIGRATION.md](docs/user/MIGRATION.md) for upgrade instructions.
+📖 [Licensing FAQ](LICENSE-FAQ.md) | 💼 Commercial licensing: bob@matsuoka.com
 
 ## Development
 
@@ -665,9 +991,6 @@ Contributions are welcome! Please see our [project structure guide](docs/referen
 ### Project Structure
 See [docs/reference/STRUCTURE.md](docs/reference/STRUCTURE.md) for codebase organization.
 
-### License
-MIT License - see [LICENSE](LICENSE) file.
-
 ## Credits
 
 - Based on [claude-multiagent-pm](https://github.com/kfsone/claude-multiagent-pm)