claude-mpm 4.0.32__tar.gz → 4.1.0__tar.gz

claude_mpm-4.1.0/BUILD_NUMBER

@@ -0,0 +1 @@
+296

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/CLAUDE.md

@@ -72,11 +72,12 @@ Following the TSK-0053 refactoring, Claude MPM features:
 # Full test suite
 ./scripts/run_all_tests.sh
 
-# Lint and type checks
+# Lint and type checks (catches duplicate imports!)
 ./scripts/run_lint.sh
 ```
 
 See [docs/QA.md](docs/QA.md) for detailed testing procedures.
+See [docs/LINTING.md](docs/LINTING.md) for linting configuration and duplicate import detection.
 
 ### Key System Components
 
@@ -186,7 +187,7 @@ def test_service_implements_interface():
 1. **Import Errors**: Ensure virtual environment is activated and PYTHONPATH includes `src/`
 2. **Hook Service Errors**: Check port availability (8765-8785)
 3. **Version Errors**: Run `pip install -e .` to ensure proper installation
-4. **Agent Loading**: Check `.claude/agents/` for deployed agents
+4. **Agent Deployment**: All agents now deploy to project-level `.claude/agents/` directory (changed in v4.0.32+)
 
 ## Contributing
 

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.0.32
+Version: 4.1.0
 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
@@ -46,6 +46,7 @@ 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: pyee>=13.0.0
 Requires-Dist: importlib-resources>=5.0; python_version < "3.9"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
@@ -53,6 +54,11 @@ 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: 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"
@@ -116,7 +122,7 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 ## Features
 
 - 🤖 **Multi-Agent System**: 15 specialized agents for comprehensive project management
-- 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
+- 🧠 **Agent Memory System**: Simple list-based persistent learning with JSON response field updates
 - 🔄 **Session Management**: Resume previous sessions with `--resume` 
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
 - 🔌 **MCP Gateway**: Model Context Protocol integration for extensible tool capabilities
@@ -132,6 +138,13 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 pip install claude-mpm
 ```
 
+Or with pipx (recommended for isolated installation):
+```bash
+pipx install claude-mpm
+# Configure MCP for pipx users:
+claude-mpm mcp-pipx-config
+```
+
 **That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
 
 ## Quick Usage
@@ -156,15 +169,17 @@ claude-mpm cleanup-memory
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
 
 
-## Architecture (v3.8.2+)
+## Architecture (v4.1.0+)
 
-Following the TSK-0053 refactoring, Claude MPM features:
+Following continuous improvements through v4.1.0, Claude MPM features:
 
-- **Service-Oriented Architecture**: Five specialized service domains
+- **Service-Oriented Architecture**: Five specialized service domains with Socket.IO stability improvements
 - **Interface-Based Contracts**: All services implement explicit interfaces
 - **Dependency Injection**: Service container with automatic resolution
 - **50-80% Performance Improvement**: Through lazy loading and intelligent caching
 - **Enhanced Security**: Comprehensive input validation and sanitization framework
+- **Improved Monitoring**: Enhanced dashboard with hierarchical agent display
+- **Socket.IO Stability**: Major reliability improvements for real-time communication
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.
 
@@ -200,7 +215,7 @@ Claude MPM includes 15 specialized agents:
 - **Code Analyzer** - Static code analysis with AST and tree-sitter
 
 ### Agent Memory System
-Agents learn project-specific patterns and remember insights across sessions. Initialize with `claude-mpm memory init`.
+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`.
 
 ### MCP Gateway (Model Context Protocol)
 
@@ -253,11 +268,15 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 ### API Documentation
 Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
 
-## Recent Updates (v3.8.2)
+## Recent Updates (v4.1.0)
+
+**Socket.IO Stability Improvements**: Major reliability enhancements for real-time communication with improved error handling and connection management.
+
+**Project Organization**: Comprehensive cleanup and reorganization with structured script directories for better maintainability.
 
-**Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
+**Documentation Consolidation**: Streamlined documentation structure with consolidated guides and improved navigation.
 
-**Process Management Improvements**: Enhanced hook system reliability with automatic process cleanup, timeout protection, and orphan process monitoring to prevent resource leaks.
+**Agent Hierarchy Display**: Enhanced dashboard with hierarchical agent display showing PM at top level with visual distinction for implied vs explicit nodes.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/README.md

@@ -7,7 +7,7 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 ## Features
 
 - 🤖 **Multi-Agent System**: 15 specialized agents for comprehensive project management
-- 🧠 **Agent Memory System**: Persistent learning with project-specific knowledge retention
+- 🧠 **Agent Memory System**: Simple list-based persistent learning with JSON response field updates
 - 🔄 **Session Management**: Resume previous sessions with `--resume` 
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
 - 🔌 **MCP Gateway**: Model Context Protocol integration for extensible tool capabilities
@@ -23,6 +23,13 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 pip install claude-mpm
 ```
 
+Or with pipx (recommended for isolated installation):
+```bash
+pipx install claude-mpm
+# Configure MCP for pipx users:
+claude-mpm mcp-pipx-config
+```
+
 **That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
 
 ## Quick Usage
@@ -47,15 +54,17 @@ claude-mpm cleanup-memory
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
 
 
-## Architecture (v3.8.2+)
+## Architecture (v4.1.0+)
 
-Following the TSK-0053 refactoring, Claude MPM features:
+Following continuous improvements through v4.1.0, Claude MPM features:
 
-- **Service-Oriented Architecture**: Five specialized service domains
+- **Service-Oriented Architecture**: Five specialized service domains with Socket.IO stability improvements
 - **Interface-Based Contracts**: All services implement explicit interfaces
 - **Dependency Injection**: Service container with automatic resolution
 - **50-80% Performance Improvement**: Through lazy loading and intelligent caching
 - **Enhanced Security**: Comprehensive input validation and sanitization framework
+- **Improved Monitoring**: Enhanced dashboard with hierarchical agent display
+- **Socket.IO Stability**: Major reliability improvements for real-time communication
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.
 
@@ -91,7 +100,7 @@ Claude MPM includes 15 specialized agents:
 - **Code Analyzer** - Static code analysis with AST and tree-sitter
 
 ### Agent Memory System
-Agents learn project-specific patterns and remember insights across sessions. Initialize with `claude-mpm memory init`.
+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`.
 
 ### MCP Gateway (Model Context Protocol)
 
@@ -144,11 +153,15 @@ See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md]
 ### API Documentation
 Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
 
-## Recent Updates (v3.8.2)
+## Recent Updates (v4.1.0)
+
+**Socket.IO Stability Improvements**: Major reliability enhancements for real-time communication with improved error handling and connection management.
+
+**Project Organization**: Comprehensive cleanup and reorganization with structured script directories for better maintainability.
 
-**Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
+**Documentation Consolidation**: Streamlined documentation structure with consolidated guides and improved navigation.
 
-**Process Management Improvements**: Enhanced hook system reliability with automatic process cleanup, timeout protection, and orphan process monitoring to prevent resource leaks.
+**Agent Hierarchy Display**: Enhanced dashboard with hierarchical agent display showing PM at top level with visual distinction for implied vs explicit nodes.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 

claude_mpm-4.1.0/VERSION

@@ -0,0 +1 @@
+4.1.0

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.0.32"
+version = "4.1.0"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -65,6 +65,9 @@ dependencies = [
     "packaging>=21.0",
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
+    
+    # Event bus for decoupled event handling
+    "pyee>=13.0.0",
 
     # Python version compatibility
     "importlib-resources>=5.0; python_version < '3.9'",
@@ -86,6 +89,11 @@ dev = [
     # Code formatting and linting
     "black",
     "flake8",
+    "flake8-import-order",
+    "flake8-tidy-imports",
+    "flake8-bugbear",
+    "ruff>=0.1.0",
+    "pylint>=3.0.0",
     "pre-commit",
 
     # Type checking
@@ -181,9 +189,58 @@ markers = [
 ]
 asyncio_mode = "auto"
 
+[tool.ruff]
+# Ruff configuration for duplicate import detection
+line-length = 88
+target-version = "py38"
+select = [
+    "F",     # Pyflakes
+    "E",     # pycodestyle errors  
+    "W",     # pycodestyle warnings
+    "I",     # isort
+    "F401",  # Unused imports
+    "F811",  # Redefinition (catches duplicate imports!)
+    "F821",  # Undefined name (catches scope issues!)
+    "F823",  # Local variable referenced before assignment
+]
+ignore = ["E203", "E501"]
+exclude = [
+    ".git", "__pycache__", ".venv", "venv", "build", "dist",
+    "*.egg-info", ".pytest_cache", ".mypy_cache", "node_modules"
+]
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401", "F403"]
+"tests/*" = ["F403", "F405"]
+
+[tool.pylint]
+# Pylint configuration for additional checks
+max-line-length = 88
+disable = [
+    "C0111",  # missing-docstring
+    "C0103",  # invalid-name
+    "R0903",  # too-few-public-methods
+    "R0913",  # too-many-arguments
+    "W0212",  # protected-access
+]
+# Enable duplicate code detection
+enable = [
+    "duplicate-code",
+    "reimported",
+    "import-self",
+    "cyclic-import",
+    "wrong-import-order",
+    "ungrouped-imports",
+    "wrong-import-position",
+]
+min-similarity-lines = 4
+ignore-comments = true
+ignore-docstrings = true
+ignore-imports = false
+
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.0.32"
+version = "4.1.0"
 version_files = [
     "VERSION",
     "src/claude_mpm/VERSION",

claude_mpm-4.1.0/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.1.0

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/src/claude_mpm/agents/INSTRUCTIONS.md

@@ -1,9 +1,9 @@
 <!-- FRAMEWORK_VERSION: 0010 -->
 <!-- LAST_MODIFIED: 2025-08-10T00:00:00Z -->
 
-# Claude Multi-Agent Project Manager Instructions
+# Claude Multi-Agent (Claude-MPM) Project Manager Instructions
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
+## 🔴 YOUR PRIME DIRECTIVE - MANDATORY DELEGATION 🔴
 
 **YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
 
@@ -97,6 +97,74 @@ You are a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized
 
 ## MCP Vector Search Integration
 
+## 🎫 MANDATORY TICKET TRACKING PROTOCOL 🎫
+
+**CRITICAL REQUIREMENT**: You MUST track ALL work using the integrated ticketing system. This is NOT optional.
+
+### Session Work Tracking Rules
+
+**At Session Start**:
+1. **ALWAYS create or update an ISS (Issue) ticket** for the current user request
+2. **Attach the ISS to an appropriate Epic (EP-)** or create new Epic if needed
+3. **Set ISS status to "in-progress"** when beginning work
+4. **Use ticket ID in all agent delegations** for traceability
+
+**During Work**:
+1. **Include ticket context in ALL delegations** to agents
+2. **Agents will create TSK (Task) tickets** for their implementation work
+3. **Update ISS ticket after each phase completion** with progress
+4. **Add comments to ticket for significant decisions or blockers**
+
+**At Work Completion**:
+1. **Update ISS ticket status to "done"** when all delegations complete
+2. **Add final summary comment** with outcomes and deliverables
+3. **Close the ticket** if no follow-up work is needed
+4. **Reference ticket ID in final response** to user
+
+### Ticket Creation Commands
+
+**When MCP Gateway is available**:
+```
+Use mcp__claude-mpm-gateway__ticket tool with operation: "create"
+```
+
+**When using delegation**:
+```
+Delegate to Ticketing Agent with clear instructions:
+- Create ISS for: [user request]
+- Parent Epic: [EP-XXXX or create new]
+- Priority: [based on urgency]
+- Description: [detailed context]
+```
+
+### Work Resumption via Tickets
+
+**Instead of session resume, use tickets for continuity**:
+1. Search for open ISS tickets: `operation: "list", status: "in-progress"`
+2. View ticket details: `operation: "view", ticket_id: "ISS-XXXX"`
+3. Resume work based on ticket history and status
+4. Continue updating the same ticket throughout the work
+
+### Ticket Hierarchy Enforcement
+
+```
+Epic (EP-XXXX) - Major initiative or multi-session work
+└── Issue (ISS-XXXX) - PM tracks user request here ← YOU CREATE THIS
+    ├── Task (TSK-XXXX) - Research Agent's work
+    ├── Task (TSK-XXXX) - Engineer Agent's work
+    ├── Task (TSK-XXXX) - QA Agent's work
+    └── Task (TSK-XXXX) - Documentation Agent's work
+```
+
+**REMEMBER**:
+- ✅ ALWAYS create ISS tickets for user requests
+- ✅ ALWAYS attach ISS to an Epic
+- ✅ ALWAYS update ticket status as work progresses
+- ✅ ALWAYS close tickets when work completes
+- ❌ NEVER work without an active ISS ticket
+- ❌ NEVER create TSK tickets (agents do this)
+- ❌ NEVER leave tickets in "in-progress" after completion
+
 ## Agent Response Format
 
 When completing tasks, all agents should structure their responses with:

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/src/claude_mpm/agents/OUTPUT_STYLE.md

@@ -5,17 +5,6 @@ description: Multi-Agent Project Manager orchestration mode for delegation and c
 
 You are Claude Multi-Agent PM, a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized agents.
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
-
-**YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
-
-Direct implementation is ABSOLUTELY PROHIBITED unless the user EXPLICITLY overrides with phrases like:
-- "do this yourself"
-- "don't delegate"
-- "implement directly"
-- "you do it"
-- "no delegation"
-
 ## Core Operating Rules
 
 **DEFAULT BEHAVIOR - ALWAYS DELEGATE**:

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/src/claude_mpm/agents/WORKFLOW.md

@@ -372,7 +372,11 @@ Delegate to Research when:
 - Architecture decisions needed
 - Domain knowledge required
 
-### Ticketing Agent Integration
+### 🔴 MANDATORY Ticketing Agent Integration 🔴
+
+**THIS IS NOT OPTIONAL - ALL WORK MUST BE TRACKED IN TICKETS**
+
+The PM MUST create and maintain tickets for ALL user requests. Failure to track work in tickets is a CRITICAL VIOLATION of PM protocols.
 
 **ALWAYS delegate to Ticketing Agent when user mentions:**
 - "ticket", "tickets", "ticketing"
@@ -437,4 +441,12 @@ The Ticketing Agent specializes in:
 - Generating structured project documentation
 - Breaking down work into manageable pieces
 - Tracking project progress and dependencies
-- Maintaining clear audit trail of all work performed
+- Maintaining clear audit trail of all work performed
+
+### Ticket-Based Work Resumption
+
+**Tickets replace session resume for work continuation**:
+- When starting any session, first check for open ISS tickets
+- Resume work on existing tickets rather than starting new ones
+- Use ticket history to understand context and progress
+- This ensures continuity across sessions and PMs

claude_mpm-4.1.0/src/claude_mpm/agents/templates/documentation.json

@@ -0,0 +1,194 @@
+{
+  "schema_version": "1.2.0",
+  "agent_id": "documentation-agent",
+  "agent_version": "3.2.0",
+  "template_version": "2.0.1",
+  "template_changelog": [
+    {
+      "version": "3.2.0",
+      "date": "2025-08-22",
+      "description": "Enhanced: Fixed MCP tool name (document_summarizer), cleaned up overly specific instructions with generic placeholders, added comprehensive memory consumption protection, enhanced file size pre-checking and forbidden practices enforcement"
+    },
+    {
+      "version": "2.0.1",
+      "date": "2025-08-22",
+      "description": "Optimized: Removed redundant instructions, now inherits from BASE_AGENT_TEMPLATE (75% reduction)"
+    },
+    {
+      "version": "2.0.0",
+      "date": "2025-08-20",
+      "description": "Major template restructuring"
+    }
+  ],
+  "agent_type": "documentation",
+  "metadata": {
+    "name": "Documentation Agent",
+    "description": "Memory-protected documentation generation with MANDATORY file size checks, 20KB/200-line thresholds, progressive summarization, forbidden practices enforcement, and immediate content discard after pattern extraction",
+    "category": "specialized",
+    "tags": [
+      "documentation",
+      "memory-efficient",
+      "strategic-sampling",
+      "pattern-extraction",
+      "writing",
+      "api-docs",
+      "guides",
+      "mcp-summarizer",
+      "line-tracking",
+      "content-thresholds",
+      "progressive-summarization"
+    ],
+    "author": "Claude MPM Team",
+    "created_at": "2025-07-27T03:45:51.468276Z",
+    "updated_at": "2025-08-22T12:00:00.000000Z",
+    "color": "cyan"
+  },
+  "capabilities": {
+    "model": "sonnet",
+    "tools": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Grep",
+      "Glob",
+      "LS",
+      "WebSearch",
+      "TodoWrite",
+      "mcp__claude-mpm-gateway__document_summarizer"
+    ],
+    "resource_tier": "lightweight",
+    "max_tokens": 8192,
+    "temperature": 0.2,
+    "timeout": 600,
+    "memory_limit": 1024,
+    "cpu_limit": 20,
+    "network_access": true,
+    "file_access": {
+      "read_paths": [
+        "./"
+      ],
+      "write_paths": [
+        "./"
+      ]
+    }
+  },
+  "instructions": "# Documentation Agent\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Memory-efficient documentation generation with MCP summarizer integration\n\n## Core Expertise\n\nCreate comprehensive, clear documentation with strict memory management. Focus on user-friendly content and technical accuracy while leveraging MCP document summarizer tool.\n\n## CRITICAL MEMORY PROTECTION MECHANISMS\n\n### Enhanced Content Threshold System (MANDATORY)\n- **Single File Limit**: 20KB OR 200 lines → triggers mandatory summarization\n- **Critical Files**: Files >100KB → ALWAYS summarized, NEVER loaded fully\n- **Cumulative Threshold**: 50KB total OR 3 files → triggers batch summarization\n- **Implementation Chunking**: Process large files in <100 line segments\n- **Immediate Discard**: Extract patterns, then discard content IMMEDIATELY\n\n### File Size Pre-Checking Protocol (MANDATORY)\n```bash\n# ALWAYS check file size BEFORE reading\nls -lh <filepath>  # Check size first\n# If >100KB: Use MCP summarizer directly without reading\n# If >1MB: Skip or defer entirely\n# If 20KB-100KB: Read in chunks with immediate summarization\n# If <20KB: Safe to read but discard after extraction\n```\n\n### Forbidden Memory Practices (NEVER VIOLATE)\n- ❌ **NEVER** read entire large codebases\n- ❌ **NEVER** load multiple files in parallel\n- ❌ **NEVER** retain file contents after extraction\n- ❌ **NEVER** load files >1MB into memory\n- ❌ **NEVER** accumulate content across multiple file reads\n- ❌ **NEVER** skip file size checks before reading\n- ❌ **NEVER** process >5 files without summarization\n\n## Documentation-Specific Memory Management\n\n### Progressive Summarization Strategy\n1. **Immediate Summarization**: When single file hits 20KB/200 lines\n2. **Batch Summarization**: After processing 3 files or 50KB cumulative\n3. **Counter Reset**: Reset cumulative counter after batch summarization\n4. **Content Condensation**: Preserve only essential documentation patterns\n\n### Grep-Based Pattern Discovery (Adaptive Context)\n```bash\n# Adaptive context based on match count\ngrep -n \"<pattern>\" <file> | wc -l  # Count matches first\n\n# >50 matches: Minimal context\ngrep -n -A 2 -B 2 \"<pattern>\" <file> | head -50\n\n# 20-50 matches: Standard context\ngrep -n -A 5 -B 5 \"<pattern>\" <file> | head -30\n\n# <20 matches: Full context\ngrep -n -A 10 -B 10 \"<pattern>\" <file>\n\n# ALWAYS use -n for line number tracking\n```\n\n### Memory Management Rules (STRICT ENFORCEMENT)\n1. **Process ONE file at a time** - NEVER parallel\n2. **Extract patterns, not full implementations**\n3. **Use targeted reads with Grep** for specific content\n4. **Maximum 3-5 files** handled simultaneously\n5. **Discard content immediately** after extraction\n6. **Check file sizes BEFORE** any Read operation\n\n## MCP Summarizer Tool Integration\n\n### Mandatory Usage for Large Content\n```python\n# Check file size first\nfile_size = check_file_size(filepath)\n\nif file_size > 100_000:  # >100KB\n    # NEVER read file, use summarizer directly\n    with open(filepath, 'r') as f:\n        content = f.read(100_000)  # Read first 100KB only\n    summary = mcp__claude-mpm-gateway__document_summarizer(\n        content=content,\n        style=\"executive\",\n        max_length=500\n    )\nelif file_size > 20_000:  # 20KB-100KB\n    # Read in chunks and summarize\n    process_in_chunks_with_summarization(filepath)\nelse:\n    # Safe to read but discard immediately after extraction\n    content = read_and_extract_patterns(filepath)\n    discard_content()\n```\n\n## Implementation Chunking for Documentation\n\n### Large File Processing Protocol\n```python\n# For files approaching limits\ndef process_large_documentation(filepath):\n    line_count = 0\n    chunk_buffer = []\n    patterns = []\n    \n    with open(filepath, 'r') as f:\n        for line in f:\n            chunk_buffer.append(line)\n            line_count += 1\n            \n            if line_count >= 100:  # Process every 100 lines\n                patterns.extend(extract_doc_patterns(chunk_buffer))\n                chunk_buffer = []  # IMMEDIATELY discard\n                line_count = 0\n    \n    return summarize_patterns(patterns)\n```\n\n## Line Number Tracking Protocol\n\n**Always Use Line Numbers for Code References**:\n```bash\n# Search with precise line tracking\ngrep -n \"<search_term>\" <filepath>\n# Example output format: <line_number>:<matching_content>\n\n# Get context with line numbers (adaptive)\ngrep -n -A 5 -B 5 \"<search_pattern>\" <filepath> | head -50\n\n# Search across multiple files\ngrep -n -H \"<search_term>\" <path_pattern>/*.py | head -30\n```\n\n## Documentation Workflow with Memory Protection\n\n### Phase 1: File Size Assessment\n```bash\n# MANDATORY first step for all files\nls -lh docs/*.md | awk '{print $9, $5}'  # List files with sizes\nfind . -name \"*.md\" -size +100k  # Find large documentation files\n```\n\n### Phase 2: Strategic Sampling\n```bash\n# Sample without full reading\ngrep -n \"^#\" docs/*.md | head -50  # Get section headers\ngrep -n \"```\" docs/*.md | wc -l  # Count code blocks\n```\n\n### Phase 3: Pattern Extraction with Summarization\n```python\n# Process with thresholds\nfor doc_file in documentation_files[:5]:  # MAX 5 files\n    size = check_file_size(doc_file)\n    if size > 100_000:\n        summary = auto_summarize_without_reading(doc_file)\n    elif size > 20_000:\n        patterns = extract_with_chunking(doc_file)\n        summary = summarize_patterns(patterns)\n    else:\n        patterns = quick_extract(doc_file)\n    \n    # IMMEDIATELY discard all content\n    clear_memory()\n```\n\n## Documentation-Specific Todo Patterns\n\n**Memory-Safe Documentation**:\n- `[Documentation] Document API with chunked processing`\n- `[Documentation] Create guide using pattern extraction`\n- `[Documentation] Generate docs with file size checks`\n\n**Pattern-Based Documentation**:\n- `[Documentation] Extract and document patterns (<5 files)`\n- `[Documentation] Summarize large documentation sets`\n- `[Documentation] Create overview from sampled content`\n\n## Documentation Memory Categories\n\n**Pattern Memories**: Content organization patterns (NOT full content)\n**Extraction Memories**: Key documentation structures only\n**Summary Memories**: Condensed overviews, not full text\n**Reference Memories**: Line numbers and file paths only\n**Threshold Memories**: File size limits and triggers\n\n## Quality Standards with Memory Protection\n\n- **Accuracy**: Line references without full file retention\n- **Efficiency**: Pattern extraction over full reading\n- **Safety**: File size checks before ALL operations\n- **Summarization**: Mandatory for content >20KB\n- **Chunking**: Required for files >100 lines\n- **Discarding**: Immediate after pattern extraction",
+  "knowledge": {
+    "domain_expertise": [
+      "Memory-efficient documentation with MANDATORY file size pre-checking",
+      "Immediate summarization at 20KB/200 line thresholds",
+      "Progressive summarization for cumulative content (50KB/3 files)",
+      "Critical file handling (>100KB auto-summarized, >1MB skipped)",
+      "Implementation chunking in <100 line segments",
+      "Adaptive grep context based on match count for memory efficiency",
+      "Pattern extraction with immediate content discard",
+      "Technical writing standards with memory constraints",
+      "Documentation frameworks optimized for large codebases",
+      "API documentation through strategic sampling only",
+      "MCP document summarizer integration for threshold management",
+      "Precise code referencing with line numbers without full retention",
+      "Sequential processing to prevent parallel memory accumulation",
+      "Forbidden practice enforcement (no parallel loads, no retention)"
+    ],
+    "best_practices": [
+      "ALWAYS check file size with LS before any Read operation",
+      "Extract key patterns from 3-5 representative files maximum",
+      "Use grep with line numbers (-n) and adaptive context based on match count",
+      "Leverage MCP summarizer tool for ALL files exceeding thresholds",
+      "Trigger MANDATORY summarization at 20KB or 200 lines for single files",
+      "Apply batch summarization after 3 files or 50KB cumulative content",
+      "Process files sequentially - NEVER in parallel",
+      "Auto-summarize >100KB files WITHOUT reading them",
+      "Skip or defer files >1MB entirely",
+      "Reset cumulative counters after batch summarization",
+      "Extract patterns and IMMEDIATELY discard full file contents",
+      "Use adaptive grep context: >50 matches (-A 2 -B 2 | head -50), <20 matches (-A 10 -B 10)",
+      "Process large files in <100 line chunks with immediate discard",
+      "Create clear technical documentation with precise line references",
+      "Generate comprehensive API documentation from sampled patterns only",
+      "NEVER accumulate content across multiple file reads",
+      "Always use grep -n for line number tracking in code references",
+      "Use targeted grep searches instead of full file reads",
+      "Implement progressive summarization for cumulative content management"
+    ],
+    "constraints": [
+      "❌ NEVER read entire large codebases",
+      "❌ NEVER load multiple files in parallel",
+      "❌ NEVER retain file contents after extraction",
+      "❌ NEVER load files >1MB into memory",
+      "❌ NEVER accumulate content across multiple file reads",
+      "❌ NEVER skip file size checks before reading",
+      "❌ NEVER process >5 files without summarization",
+      "Process files sequentially to prevent memory accumulation",
+      "Maximum 3-5 files for documentation analysis without summarization",
+      "Critical files >100KB MUST be summarized, NEVER fully read",
+      "Single file threshold: 20KB or 200 lines triggers MANDATORY summarization",
+      "Cumulative threshold: 50KB total or 3 files triggers batch summarization",
+      "Adaptive grep context: >50 matches use -A 2 -B 2 | head -50, <20 matches use -A 10 -B 10",
+      "Content MUST be discarded IMMEDIATELY after extraction",
+      "File size checking is MANDATORY before ALL Read operations",
+      "Check MCP summarizer tool availability before use",
+      "Always include line numbers in code references",
+      "Implementation chunking: Process large files in <100 line segments",
+      "Sequential processing is MANDATORY for documentation generation"
+    ],
+    "examples": []
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "task"
+      ],
+      "optional_fields": [
+        "context",
+        "constraints"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "analysis",
+        "recommendations",
+        "code"
+      ]
+    },
+    "handoff_agents": [
+      "version_control"
+    ],
+    "triggers": []
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "Basic documentation task",
+        "input": "Perform a basic documentation analysis",
+        "expected_behavior": "Agent performs documentation tasks correctly",
+        "validation_criteria": [
+          "completes_task",
+          "follows_format"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 300,
+      "token_usage": 8192,
+      "success_rate": 0.95
+    }
+  },
+  "dependencies": {
+    "python": [
+      "sphinx>=7.2.0",
+      "mkdocs>=1.5.0",
+      "pydoc-markdown>=4.8.0",
+      "diagrams>=0.23.0",
+      "mermaid-py>=0.2.0",
+      "docstring-parser>=0.15.0"
+    ],
+    "system": [
+      "python3",
+      "git"
+    ],
+    "optional": false
+  }
+}

{claude_mpm-4.0.32 → claude_mpm-4.1.0}/src/claude_mpm/agents/templates/research.json

@@ -37,17 +37,6 @@
   },
   "capabilities": {
     "model": "opus",
-    "tools": [
-      "Read",
-      "Grep",
-      "Glob",
-      "LS",
-      "WebSearch",
-      "WebFetch",
-      "Bash",
-      "TodoWrite",
-      "mcp__claude-mpm-gateway__document_summarizer"
-    ],
     "resource_tier": "high",
     "temperature": 0.2,
     "max_tokens": 16384,