claude-mpm 4.14.2 → 5.3.0

package/README.md

@@ -2,32 +2,147 @@
 
 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 extends **Claude Code (CLI)**, not Claude Desktop (app). All MCP integrations work with Claude Code's CLI interface only.
+> **⚠️ Important**: Claude MPM **requires Claude Code CLI** (v1.0.92+), 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
+>
+> **Version Requirements:**
+> - Minimum: v1.0.92 (hooks support)
+> - Recommended: v2.0.30+ (latest features)
 
-> **Quick Start**: See [QUICKSTART.md](QUICKSTART.md) to get running in 5 minutes!
+> **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**: 15 specialized agents for comprehensive project management
-- 🧠 **Persistent Knowledge System**: Project-specific kuzu-memory integration for intelligent context retention
-- 🔄 **Session Management**: Resume previous sessions with `--resume`
-- 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
-- 🔌 **Smart MCP Services**: Interactive auto-install for mcp-vector-search on first use (pip/pipx choice)
-- 🔍 **Semantic Code Search**: Optional vector search with graceful fallback to grep/glob
-- 📁 **Multi-Project Support**: Per-session working directories with persistent knowledge graphs
-- 🔍 **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
 
+### Prerequisites
+
+**Before installing Claude MPM**, ensure you have:
+
+1. **Python 3.11+** (required for kuzu-memory dependency)
+2. **Claude Code CLI v1.0.92+** (required!)
+
+```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
+
 ```bash
 # Basic installation
 pip install claude-mpm
 
-# Install with optional MCP services (recommended)
-pip install "claude-mpm[mcp]"
+# Install with monitoring dashboard (recommended)
+pip install "claude-mpm[monitor]"
 ```
 
 Or with pipx (recommended for isolated installation):
@@ -35,31 +150,175 @@ Or with pipx (recommended for isolated installation):
 # Basic installation
 pipx install claude-mpm
 
-# Install with optional MCP services (recommended)
-pipx install "claude-mpm[mcp]"
+# Install with monitoring dashboard (recommended)
+pipx install "claude-mpm[monitor]"
+```
+
+### Verify Installation
+
+```bash
+# Check versions
+claude-mpm --version
+claude --version
+
+# Run diagnostics (checks Claude Code compatibility)
+claude-mpm doctor
 
-# Install with all features
-pipx install "claude-mpm[mcp,monitor]"
+# Verify Git repositories are synced
+ls ~/.claude/agents/    # Should show 47+ agents
+ls ~/.claude/skills/    # Should show hundreds of skills
 
-# Configure MCP for pipx users:
-claude-mpm mcp-pipx-config
+# 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**:
-- `[mcp]` - Include MCP services (mcp-vector-search, mcp-browser, mcp-ticketer)
 - `[monitor]` - Full monitoring dashboard with Socket.IO and async web server components
-- **Combine both**: Use `"claude-mpm[mcp,monitor]"` to install all features
-- **Note**: kuzu-memory is now a required dependency, always included with Claude MPM
-- **Auto-Install**: mcp-vector-search offers interactive installation on first use (pip/pipx choice)
-- Without pre-installed MCP dependencies, services install on-demand with user confirmation
+- `[mcp]` - Additional MCP services (mcp-browser, mcp-ticketer) - most users won't need this
 
 **🎉 Pipx Support Now Fully Functional!** Recent improvements ensure complete compatibility:
 - ✅ Socket.IO daemon script path resolution (fixed)
-- ✅ Commands directory access (fixed) 
+- ✅ Commands directory access (fixed)
 - ✅ Resource files properly packaged for pipx environments
 - ✅ Python 3.13+ fully supported
 
-**That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
+## 🤝 Recommended Partner Products
+
+Claude MPM works excellently with these complementary MCP tools. While optional, we **strongly recommend** installing them for enhanced capabilities:
+
+### kuzu-memory - Advanced Memory Management
+
+**What it does**: Provides persistent, project-specific knowledge graphs that enable agents to learn and retain context across sessions. Your agents will remember project patterns, architectural decisions, and important context automatically.
+
+**Installation:**
+```bash
+pipx install kuzu-memory
+```
+
+**Benefits with Claude MPM:**
+- 🧠 **Persistent Context**: Agents remember project-specific patterns and decisions across sessions
+- 🎯 **Intelligent Prompts**: Automatically enriches agent prompts with relevant historical context
+- 📊 **Knowledge Graphs**: Structured storage of project knowledge, not just flat memory
+- 🔄 **Seamless Integration**: Works transparently in the background with zero configuration
+- 💡 **Smart Learning**: Agents improve over time as they learn your project's patterns
+
+**Perfect for**: Long-running projects, teams needing consistent context, complex codebases with deep architectural patterns.
+
+**Learn more**: [kuzu-memory on PyPI](https://pypi.org/project/kuzu-memory/) | [GitHub Repository](https://github.com/bobmatnyc/kuzu-memory)
+
+---
+
+### mcp-vector-search - Semantic Code Search
+
+**What it does**: Enables semantic code search across your entire codebase using AI embeddings. Find code by what it *does*, not just what it's *named*. Search for "authentication logic" and find relevant functions even if they're named differently.
+
+**Installation:**
+```bash
+pipx install mcp-vector-search
+```
+
+**Benefits with Claude MPM:**
+- 🔍 **Semantic Discovery**: Find code by intent and functionality, not just keywords
+- 🎯 **Context-Aware**: Understand code relationships and similarities automatically
+- ⚡ **Fast Indexing**: Efficient vector embeddings for large codebases
+- 🔄 **Live Updates**: Automatically tracks code changes and updates index
+- 📊 **Pattern Recognition**: Discover similar code patterns and potential refactoring opportunities
+
+**Use with**: `/mpm-search "authentication logic"` command in Claude Code sessions or `claude-mpm search` CLI command.
+
+**Perfect for**: Large codebases, discovering existing functionality, finding similar implementations, architectural exploration.
+
+**Learn more**: [mcp-vector-search on PyPI](https://pypi.org/project/mcp-vector-search/) | [GitHub Repository](https://github.com/bobmatnyc/mcp-vector-search)
+
+---
+
+### Quick Setup - Both Tools
+
+Install both recommended tools in one go:
+
+```bash
+pipx install kuzu-memory
+pipx install mcp-vector-search
+```
+
+Then verify they're working:
+
+```bash
+claude-mpm verify
+```
+
+**That's it!** These tools integrate automatically with Claude MPM once installed. No additional configuration needed.
+
+**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/remote-agents/`.
+
+### Cache Structure
+
+```
+~/.claude-mpm/cache/remote-agents/
+└── bobmatnyc/
+    └── claude-mpm-agents/
+        ├── .git/              # Git repository
+        ├── agents/            # 45+ agent templates
+        └── docs/
+```
+
+### 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
 
@@ -104,18 +363,200 @@ claude-mpm verify --json
 
 # Manage memory for large conversation histories
 claude-mpm cleanup-memory
+
+# Check for updates (including Claude Code compatibility)
+claude-mpm doctor --checks updates
+```
+
+**💡 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).
+
+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
+
+Skills are automatically deployed from Git repositories, just like agents. Claude MPM includes **hundreds of skills** from curated repositories:
+
+- **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
 ```
 
-See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
+### 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 (v4.4.1)
 
-Following Phase 3 architectural simplification in v4.4.1, Claude MPM features:
+## Architecture
+
+Claude MPM features a clean, service-oriented architecture:
 
 - **Streamlined Rich Interface**: Removed complex TUI system (~2,500 lines) for cleaner user experience
-- **Optional MCP Services**: mcp-vector-search and kuzu-memory with automatic fallback installation
-- **Persistent Knowledge System**: Project-specific kuzu-memory databases with intelligent prompt enrichment
+- **MCP Integration**: Full support for Model Context Protocol services with automatic detection
 - **Service-Oriented Architecture**: Simplified five specialized service domains
 - **Interface-Based Contracts**: All services implement explicit interfaces
 - **Enhanced Performance**: ~3,700 lines removed for better startup time and maintainability
@@ -131,11 +572,26 @@ Claude MPM includes 15 specialized agents:
 
 #### Core Development
 - **Engineer** - Software development and implementation
-- **Research** - Code analysis and research  
+- **Research** - Code analysis and research
 - **Documentation** - Documentation creation and maintenance
 - **QA** - Testing and quality assurance
 - **Security** - Security analysis and implementation
 
+#### Language-Specific Engineers
+- **Python Engineer (v2.3.0)** - Type-safe, async-first Python with SOA patterns for non-trivial applications
+  - Service-oriented architecture with ABC interfaces for applications
+  - Lightweight script patterns for automation and one-off tasks
+  - Clear decision criteria for when to use DI/SOA vs simple functions
+  - Dependency injection containers with auto-resolution
+  - Use for: Web applications, microservices, data pipelines (DI/SOA) or scripts, CLI tools, notebooks (simple functions)
+
+- **Rust Engineer (v1.1.0)** - Memory-safe, high-performance systems with trait-based service architecture
+  - Dependency injection with traits (constructor injection, trait objects)
+  - Service-oriented architecture patterns (repository, builder)
+  - Decision criteria for when to use DI/SOA vs simple code
+  - Async programming with tokio and zero-cost abstractions
+  - Use for: Web services, microservices (DI/SOA) or CLI tools, scripts (simple code)
+
 #### Operations & Infrastructure
 - **Ops** - Operations and deployment with advanced git commit authority and security verification (v2.2.2+)
 - **Version Control** - Git and version management
@@ -157,6 +613,41 @@ Claude MPM includes 15 specialized agents:
 ### 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`.
 
+### Skills System
+
+Claude MPM includes a powerful skills system that eliminates redundant agent guidance through reusable skill modules:
+
+**20 Bundled Skills** covering essential development workflows (all versioned starting at 0.1.0):
+- Git workflow, TDD, code review, systematic debugging
+- API documentation, refactoring patterns, performance profiling
+- Docker containerization, database migrations, security scanning
+- JSON/PDF/XLSX handling, async testing, ImageMagick operations
+- Local development servers: Next.js, FastAPI, Vite, Express
+- Web performance: Lighthouse metrics, Core Web Vitals optimization
+
+**Three-Tier Organization:**
+- **Bundled**: Core skills included with Claude MPM (~15,000 lines of reusable guidance)
+- **User**: Custom skills in `~/.config/claude-mpm/skills/`
+- **Project**: Project-specific skills in `.claude-mpm/skills/`
+
+**Version Tracking:**
+- All skills support semantic versioning (MAJOR.MINOR.PATCH)
+- Check versions with `/mpm-version` command in Claude Code
+- See [Skills Versioning Guide](docs/user/skills-versioning.md) for details
+
+**Quick Access:**
+```bash
+# Interactive skills management
+claude-mpm configure
+# Choose option 2: Skills Management
+
+# Auto-link skills to agents based on their roles
+# Configure custom skill assignments
+# View current skill mappings
+```
+
+Skills are automatically injected into agent prompts, reducing template size by 85% while maintaining full capability coverage.
+
 ### MCP Gateway (Model Context Protocol)
 
 Claude MPM includes a powerful MCP Gateway that enables:
@@ -179,10 +670,76 @@ claude-mpm cleanup-memory
 claude-mpm cleanup-memory --days 7
 ```
 
+### Resume Log System
+
+**NEW in v4.17.2** - Proactive context management for seamless session continuity.
+
+The Resume Log System automatically generates structured 10k-token logs when approaching Claude's context window limits, enabling you to resume work without losing important context.
+
+**Key Features**:
+- 🎯 **Graduated Thresholds**: Warnings at 70% (60k buffer), 85% (30k buffer), and 95% (10k buffer)
+- 📋 **Structured Logs**: 10k-token budget intelligently distributed across 7 key sections
+- 🔄 **Seamless Resumption**: Automatically loads previous session context on startup
+- 📁 **Human-Readable**: Markdown format for both Claude and human review
+- ⚙️ **Zero-Configuration**: Works automatically with sensible defaults
+
+**How It Works**:
+1. Monitor token usage continuously throughout session
+2. Display proactive warnings at 70%, 85%, and 95% thresholds
+3. Automatically generate resume log when approaching limits
+4. Load previous resume log when starting new session
+5. Continue work seamlessly with full context preservation
+
+**Example Resume Log Structure**:
+```markdown
+# Session Resume Log: 20251101_115000
+
+## Context Metrics (500 tokens)
+- Token usage and percentage
+
+## Mission Summary (1,000 tokens)
+- Overall goal and purpose
+
+## Accomplishments (2,000 tokens)
+- What was completed
+
+## Key Findings (2,500 tokens)
+- Important discoveries
+
+## Decisions & Rationale (1,500 tokens)
+- Why choices were made
+
+## Next Steps (1,500 tokens)
+- What to do next
+
+## Critical Context (1,000 tokens)
+- Essential state, IDs, paths
+```
+
+**Configuration** (`.claude-mpm/configuration.yaml`):
+```yaml
+context_management:
+  enabled: true
+  budget_total: 200000
+  thresholds:
+    caution: 0.70   # First warning - plan transition
+    warning: 0.85   # Strong warning - wrap up
+    critical: 0.95  # Urgent - stop new work
+  resume_logs:
+    enabled: true
+    auto_generate: true
+    max_tokens: 10000
+    storage_dir: ".claude-mpm/resume-logs"
+```
+
+**QA Status**: 40/41 tests passing (97.6% coverage), APPROVED FOR PRODUCTION ✅
+
+See [docs/user/resume-logs.md](docs/user/resume-logs.md) for complete documentation.
+
 ### Real-Time Monitoring
 The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
 
-See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
+See [docs/reference/MEMORY.md](docs/reference/MEMORY.md) and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
 
 
 ## 📚 Documentation
@@ -195,7 +752,7 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 - **[🚀 5-Minute Quick Start](docs/user/quickstart.md)** - Get running immediately
 - **[📦 Installation Guide](docs/user/installation.md)** - All installation methods
 - **[📖 User Guide](docs/user/README.md)** - Complete user documentation
-- **[❓ FAQ](docs/user/faq.md)** - Common questions answered
+- **[❓ FAQ](docs/guides/FAQ.md)** - Common questions answered
 
 #### 💻 For Developers
 - **[🏗️ Architecture Overview](docs/developer/ARCHITECTURE.md)** - Service-oriented system design
@@ -217,19 +774,39 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 - **Single Entry Point**: [docs/README.md](docs/README.md) is your navigation hub
 - **Clear User Paths**: Organized by user type and experience level
 - **Cross-Referenced**: Links between related topics and sections
-- **Up-to-Date**: Version 4.3.3 with current information
-
-## Recent Updates (v4.3.3)
-
-**Enhanced PM Instructions**: PM2 deployment support and mandatory web-qa verification for quality assurance.
-
-**Improved Version Management**: Better version comparison logic and agent override warnings for smoother operations.
-
-**Code Quality Improvements**: Auto-fix code formatting and import management with enhanced standard tools recognition.
-
-**Documentation Overhaul**: Unified documentation architecture with single entry point and clear navigation paths.
-
-**Performance Enhancements**: Continued 50-80% performance improvements through intelligent caching and lazy loading.
+- **Up-to-Date**: Version 4.16.3 with web performance optimization skill
+
+## 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
 
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/user/MIGRATION.md](docs/user/MIGRATION.md) for upgrade instructions.
 
@@ -256,7 +833,7 @@ The project uses automated code formatting and quality checks:
 See [docs/developer/CODE_FORMATTING.md](docs/developer/CODE_FORMATTING.md) for details.
 
 ### Contributing
-Contributions are welcome! Please see our [project structure guide](docs/STRUCTURE.md) and follow the established patterns.
+Contributions are welcome! Please see our [project structure guide](docs/reference/STRUCTURE.md) and follow the established patterns.
 
 **Development Workflow**:
 1. Run `make dev-complete` to set up your environment
@@ -264,7 +841,7 @@ Contributions are welcome! Please see our [project structure guide](docs/STRUCTU
 3. All code must pass quality checks before merging
 
 ### Project Structure
-See [docs/STRUCTURE.md](docs/STRUCTURE.md) for codebase organization.
+See [docs/reference/STRUCTURE.md](docs/reference/STRUCTURE.md) for codebase organization.
 
 ### License
 MIT License - see [LICENSE](LICENSE) file.

package/npm-bin/claude-mpm.js

@@ -15,11 +15,11 @@ function checkPythonVersion(pythonCmd) {
     try {
         const versionOutput = execSync(`${pythonCmd} --version`, { encoding: 'utf8', stdio: 'pipe' });
         const versionMatch = versionOutput.match(/Python (\d+)\.(\d+)\.(\d+)/);
-        
+
         if (!versionMatch) return false;
-        
+
         const [, major, minor] = versionMatch.map(Number);
-        return major > REQUIRED_PYTHON_VERSION[0] || 
+        return major > REQUIRED_PYTHON_VERSION[0] ||
                (major === REQUIRED_PYTHON_VERSION[0] && minor >= REQUIRED_PYTHON_VERSION[1]);
     } catch (error) {
         return false;
@@ -28,7 +28,7 @@ function checkPythonVersion(pythonCmd) {
 
 function findPython() {
     const pythonCommands = ['python3', 'python', 'python3.11', 'python3.10', 'python3.9', 'python3.8'];
-    
+
     for (const cmd of pythonCommands) {
         if (checkPythonVersion(cmd)) {
             return cmd;
@@ -39,7 +39,7 @@ function findPython() {
 
 function main() {
     const pythonCmd = findPython();
-    
+
     if (!pythonCmd) {
         console.error(`
 ❌ Error: Python ${REQUIRED_PYTHON_VERSION.join('.')}+ is required but not found.
@@ -77,9 +77,9 @@ Or using pip directly:
 
     // Launch claude-mpm with all arguments
     const args = process.argv.slice(2);
-    const child = spawn(pythonCmd, ['-m', 'claude_mpm'].concat(args), { 
+    const child = spawn(pythonCmd, ['-m', 'claude_mpm'].concat(args), {
         stdio: 'inherit',
-        env: process.env 
+        env: process.env
     });
 
     child.on('exit', (code) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mpm",
-  "version": "4.14.2",
+  "version": "5.3.0",
   "description": "NPM wrapper for claude-mpm Python package - Requires Python 3.8+. Orchestrate Claude with agent delegation and ticket tracking",
   "keywords": [
     "claude",