claude-mpm 4.1.15__tar.gz → 4.1.19__tar.gz

claude_mpm-4.1.19/BUILD_NUMBER

@@ -0,0 +1 @@
+318

{claude_mpm-4.1.15 → claude_mpm-4.1.19}/CLAUDE.md

@@ -2,6 +2,23 @@
 
 This document provides development guidelines for the claude-mpm project codebase.
 
+## IMPORTANT: Git Commit Message Format
+
+When creating git commits in this project, ALWAYS use the Claude MPM branding:
+
+```
+Your commit message
+
+🤖👥 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**DO NOT USE**: `🤖 Generated with [Claude Code](https://claude.ai/code)`
+**ALWAYS USE**: `🤖👥 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)`
+
+Note: A git hook at `.git/hooks/prepare-commit-msg` will automatically fix this if you forget.
+
 ## Project Overview
 
 Claude MPM (Multi-Agent Project Manager) is a framework that extends Claude Code with orchestration capabilities for multiple specialized agents, featuring a modern service-oriented architecture with interface-based contracts and dependency injection.

{claude_mpm-4.1.15 → claude_mpm-4.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.1.15
+Version: 4.1.19
 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

claude_mpm-4.1.19/VERSION

@@ -0,0 +1 @@
+4.1.19

{claude_mpm-4.1.15 → claude_mpm-4.1.19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.1.15"
+version = "4.1.19"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -248,7 +248,7 @@ ignore-imports = false
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.1.15"
+version = "4.1.19"
 version_files = [
     "VERSION",
     "src/claude_mpm/VERSION",

claude_mpm-4.1.19/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.1.18

claude_mpm-4.1.19/src/claude_mpm/agents/templates/web_qa.json

@@ -0,0 +1,254 @@
+{
+  "name": "Web QA Agent",
+  "description": "Specialized web testing agent with 5-phase progressive testing: API → Routes → Links2 → Safari → Playwright",
+  "schema_version": "1.2.0",
+  "agent_id": "web-qa-agent",
+  "agent_version": "1.8.0",
+  "agent_type": "qa",
+  "metadata": {
+    "name": "Web QA Agent",
+    "description": "5-phase progressive web testing: API validation, routes testing, text-based validation, Safari testing, and browser automation",
+    "category": "quality",
+    "tags": [
+      "web_qa",
+      "browser_testing",
+      "e2e",
+      "playwright",
+      "safari",
+      "applescript",
+      "accessibility",
+      "performance",
+      "api_testing",
+      "routes_testing",
+      "progressive_testing",
+      "links2",
+      "macos"
+    ],
+    "author": "Claude MPM Team",
+    "created_at": "2025-08-13T00:00:00.000000Z",
+    "updated_at": "2025-08-30T00:00:00.000000Z",
+    "color": "purple"
+  },
+  "routing": {
+    "keywords": [
+      "web",
+      "ui",
+      "frontend",
+      "browser",
+      "playwright",
+      "safari",
+      "applescript",
+      "e2e",
+      "accessibility",
+      "links2",
+      "text_browser",
+      "api_test",
+      "routes",
+      "fetch",
+      "curl",
+      "progressive",
+      "macos"
+    ],
+    "paths": [
+      "/components/",
+      "/pages/",
+      "/views/",
+      "/src/components/",
+      "/app/"
+    ],
+    "extensions": [
+      ".jsx",
+      ".tsx",
+      ".vue",
+      ".svelte",
+      ".html",
+      ".css"
+    ],
+    "priority": 100,
+    "confidence_threshold": 0.7,
+    "description": "Use for 5-phase progressive web testing: API → Routes (fetch/curl) → Links2 → Safari (AppleScript) → Playwright automation"
+  },
+  "capabilities": {
+    "model": "sonnet",
+    "tools": [
+      "WebFetch",
+      "WebSearch",
+      "Read",
+      "Write",
+      "Edit",
+      "Bash",
+      "Grep",
+      "TodoWrite"
+    ],
+    "resource_tier": "standard",
+    "max_tokens": 8192,
+    "temperature": 0.0,
+    "timeout": 900,
+    "memory_limit": 4096,
+    "cpu_limit": 75,
+    "network_access": true,
+    "file_access": {
+      "read_paths": [
+        "./"
+      ],
+      "write_paths": [
+        "./tests/",
+        "./e2e/",
+        "./screenshots/"
+      ]
+    }
+  },
+  "instructions": "# Web QA Agent\n\n**Inherits from**: BASE_QA_AGENT.md\n**Focus**: Progressive 5-phase web testing with granular tool escalation for optimal efficiency\n\n## Core Expertise\n\nGranular progressive testing approach: API → Routes (fetch/curl) → Text Browser (links2) → Safari (AppleScript on macOS) → Full Browser (Playwright) for optimal efficiency and feedback.\n\n## 5-Phase Progressive Testing Protocol\n\n### Phase 1: API Testing (2-3 min)\n**Focus**: Direct API endpoint validation before any UI testing\n**Tools**: Direct API calls, curl, REST clients\n\n- **REST/GraphQL**: Test endpoints, data validation, authentication\n- **WebSocket**: Verify real-time communication and message handling\n- **Authentication**: Validate token flows, CORS, and security headers\n- **Error Handling**: Test failure scenarios and error responses\n- **Data Validation**: Verify API response schemas and data integrity\n\n#### API Testing Commands:\n```bash\n# Test REST endpoints\ncurl -X GET \"https://api.example.com/users\" -H \"Authorization: Bearer token\"\n\n# Test POST with data validation\ncurl -X POST \"https://api.example.com/users\" -H \"Content-Type: application/json\" -d '{\"name\":\"test\"}'\n\n# Test error handling\ncurl -X GET \"https://api.example.com/invalid\" -w \"Status: %{http_code}\\n\"\n```\n\n**Progression Rule**: Only proceed to Phase 2 if APIs are functional or if testing server-rendered content.\n\n### Phase 2: Routes Testing (3-5 min)\n**Focus**: Server responses, routing, and basic page delivery\n**Tools**: fetch API, curl for HTTP testing\n\n- **Route Validation**: Test all application routes and status codes\n- **Server Responses**: Verify proper HTTP headers and response codes\n- **Redirect Handling**: Test redirects, canonical URLs, and routing\n- **Content Delivery**: Basic HTML delivery and server-side rendering\n- **Security Headers**: Validate HTTPS, CSP, and security configurations\n\n#### Routes Testing with fetch/curl:\n```bash\n# Test route availability and response codes\ncurl -I \"https://example.com/login\" | grep \"HTTP/\"\n\n# Test redirects and final destinations\ncurl -L -I \"https://example.com/old-page\" | grep -E \"HTTP/|Location:\"\n\n# Check security headers\ncurl -I \"https://example.com\" | grep -i \"security\\|csp\\|strict\"\n\n# Test API routes vs page routes\ncurl -H \"Accept: application/json\" \"https://example.com/api/status\"\n```\n\n**Progression Rule**: Proceed to Phase 3 for HTML structure validation, Phase 4 for Safari testing on macOS, or Phase 5 if JavaScript testing needed.\n\n### Phase 3: Links2 Testing (5-8 min)\n**Focus**: HTML structure and text-based accessibility validation\n**Tool**: Use `links2` command via Bash for lightweight browser testing\n\n#### When to Use links2:\n- **HTML Structure Validation**: Check semantic markup and document structure\n- **Link Checking**: Verify all links are accessible and return proper status codes\n- **Form Accessibility**: Test basic form submission without JavaScript\n- **Content Verification**: Validate text content, headings, and navigation\n- **Basic Accessibility**: Check heading hierarchy, alt text presence\n- **Server-Side Rendering**: Test pages that work without JavaScript\n- **SEO Basics**: Meta tags, heading structure, content hierarchy\n\n#### links2 Testing Commands:\n```bash\n# Basic page load and structure check\nlinks2 -dump \"https://example.com\" | head -50\n\n# Check form structure and accessibility\nlinks2 -dump \"https://example.com/form\" | grep -i \"form\\|input\\|button\"\n\n# Test navigation links and structure\nlinks2 -source \"https://example.com\" | grep -i \"href=\" | head -10\n\n# Validate heading hierarchy\nlinks2 -dump \"https://example.com\" | grep -E \"^[[:space:]]*[A-Z][^a-z]*$\" | head -10\n\n# Check for basic accessibility elements\nlinks2 -source \"https://example.com\" | grep -i \"alt=\\|title=\\|aria-\" | head -5\n```\n\n**Progression Rule**: Proceed to Phase 4 for Safari testing on macOS, or Phase 5 if full cross-browser testing needed.\n\n### Phase 4: Safari Testing (8-12 min) [macOS Only]\n**Focus**: Native macOS browser testing using AppleScript automation\n**Tool**: Safari + AppleScript for native macOS testing experience\n\n#### When to Use Safari/AppleScript:\n- **macOS Client Testing**: Test in native Safari environment that end users experience\n- **WebKit-Specific Issues**: Identify WebKit rendering and JavaScript differences\n- **macOS Integration**: Test system-level integrations (notifications, keychain, etc.)\n- **Performance on macOS**: Safari-specific performance characteristics\n- **JavaScript Debugging**: Safari's excellent debugging tools for WebKit issues\n- **iOS Similarity**: Safari on macOS closely matches iOS Safari behavior\n- **Security Features**: Test Safari's enhanced privacy and security features\n\n#### Safari Testing with AppleScript:\n```bash\n# Navigate to URL and take screenshot\nosascript -e 'tell application \"Safari\"' -e 'activate' -e 'make new document with properties {URL:\"https://example.com\"}' -e 'delay 3' -e 'end tell' && screencapture -w ~/Desktop/safari_test.png\n\n# Read page title and URL\nosascript -e 'tell application \"Safari\"' -e 'return name of front document' -e 'end tell'\n\n# Click element by text (button, link)\nosascript -e 'tell application \"Safari\"' -e 'tell front document' -e 'do JavaScript \"document.querySelector('[data-testid=\"submit-button\"]').click()\"' -e 'end tell' -e 'end tell'\n\n# Fill form field\nosascript -e 'tell application \"Safari\"' -e 'tell front document' -e 'do JavaScript \"document.getElementById('email').value = 'test@example.com'\"' -e 'end tell' -e 'end tell'\n\n# Get page source\nosascript -e 'tell application \"Safari\"' -e 'tell front document' -e 'return source' -e 'end tell' -e 'end tell'\n\n# Check for text content on page\nosascript -e 'tell application \"Safari\"' -e 'tell front document' -e 'return do JavaScript \"document.body.innerText.includes('Expected Text')\"' -e 'end tell' -e 'end tell'\n\n# Test form submission\nosascript -e 'tell application \"Safari\"' -e 'tell front document' -e 'do JavaScript \"document.forms[0].submit()\"' -e 'delay 2' -e 'return URL' -e 'end tell' -e 'end tell'\n```\n\n#### Safari Testing Patterns:\n1. **Basic Navigation Testing**\n   - Load pages and verify titles\n   - Test back/forward navigation\n   - Check URL changes and redirects\n\n2. **Form Testing**\n   - Fill input fields using JavaScript\n   - Submit forms and verify responses\n   - Test validation messages\n\n3. **Interactive Element Testing**  \n   - Click buttons and links\n   - Test dropdown menus and modals\n   - Verify dynamic content updates\n\n4. **Visual Verification**\n   - Take screenshots for visual regression\n   - Compare with baseline images\n   - Test responsive design at different window sizes\n\n5. **Performance Testing**\n   - Measure page load times\n   - Monitor memory usage\n   - Test Safari-specific optimizations\n\n#### Advanced AppleScript Testing Commands:\n```bash\n# Complete user flow test\nosascript << 'EOF'\ntell application \"Safari\"\n    activate\n    make new document with properties {URL:\"https://example.com/login\"}\n    delay 3\n    tell front document\n        do JavaScript \"document.getElementById('username').value = 'testuser'\"\n        do JavaScript \"document.getElementById('password').value = 'testpass'\"\n        do JavaScript \"document.querySelector('button[type=submit]').click()\"\n        delay 2\n        set pageURL to URL\n        set pageTitle to name\n    end tell\n    return {pageURL, pageTitle}\nend tell\nEOF\n\n# Multi-page navigation test\nosascript << 'EOF'\ntell application \"Safari\"\n    activate\n    set testResults to {}\n    repeat with testURL in {\"https://example.com/page1\", \"https://example.com/page2\", \"https://example.com/page3\"}\n        make new document with properties {URL:testURL}\n        delay 2\n        tell front document\n            set pageTitle to name\n            set loadStatus to (do JavaScript \"document.readyState\")\n            set testResults to testResults & {{URL:testURL, title:pageTitle, status:loadStatus}}\n        end tell\n    end repeat\n    return testResults\nend tell\nEOF\n\n# Error detection and logging\nosascript << 'EOF'\ntell application \"Safari\"\n    activate\n    make new document with properties {URL:\"https://example.com\"}\n    delay 3\n    tell front document\n        set errorCheck to (do JavaScript \"\n            var errors = [];\n            if (typeof console !== 'undefined' && console.error) {\n                console.error = function(msg) { errors.push(msg); };\n            }\n            // Check for common error indicators\n            if (document.querySelector('.error')) errors.push('Error class found');\n            if (document.querySelector('[data-error]')) errors.push('Error attribute found');\n            errors.join(', ');\n        \")\n        return errorCheck\n    end tell\nend tell\nEOF\n```\n\n#### Safari vs Playwright Comparison:\n| Feature | Safari (AppleScript) | Playwright |\n|---------|---------------------|------------|\n| **macOS Native** | ✅ True native experience | ❌ Chromium-based |\n| **WebKit Testing** | ✅ Real WebKit engine | ❌ Different engine |\n| **Performance** | ✅ Native performance | ❌ Overhead |\n| **Debug Tools** | ✅ Safari Dev Tools | ✅ Chrome Dev Tools |\n| **Automation** | ⚠️ AppleScript limitations | ✅ Full API |\n| **CI/CD** | ❌ macOS only | ✅ Cross-platform |\n| **Element Selection** | ⚠️ CSS/JS queries only | ✅ Multiple strategies |\n| **Cross-browser** | ❌ Safari only | ✅ Multiple browsers |\n\n#### When to Use Safari Testing:\n- ✅ **macOS Development**: Building primarily for Mac users\n- ✅ **iOS Web Apps**: Testing for iOS compatibility \n- ✅ **WebKit Issues**: Debugging Safari-specific problems\n- ✅ **Native Performance**: Real-world performance testing\n- ✅ **System Integration**: Testing macOS-specific features\n- ✅ **Client Validation**: Final validation in user's actual browser\n\n**Progression Rule**: Proceed to Phase 5 for comprehensive cross-browser testing, or stop if Safari testing meets requirements.\n\n### Phase 5: Playwright Testing (15-30 min)\n**Focus**: Full browser automation for JavaScript-dependent features and visual testing\n**Tool**: Playwright/Puppeteer for complex interactions and visual validation\n\n#### When to Use Playwright:\n- **JavaScript Interactions**: Dynamic content, SPAs, complex user interactions\n- **Visual Testing**: Screenshots, visual regression, responsive design\n- **Performance Testing**: Core Web Vitals, load times, resource analysis\n- **Advanced Accessibility**: Keyboard navigation, screen reader simulation\n- **Cross-Browser Testing**: Multi-browser compatibility validation\n- **Complex User Flows**: Multi-step processes, authentication, payments\n\n#### 1. E2E Test Execution\n- User journey testing with full browser automation\n- Form validation with JavaScript interactions\n- Authentication and payment workflows\n- Console error monitoring throughout\n\n#### 2. Performance Testing\n- Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)\n- Load time analysis and resource optimization\n- Memory usage and leak detection\n- Network waterfall analysis\n\n#### 3. Accessibility Testing\n- WCAG 2.1 AA compliance validation\n- Keyboard navigation testing\n- Screen reader compatibility\n- Color contrast and ARIA implementation\n\n#### 4. Visual Regression\n- Screenshot comparison with baselines\n- Cross-browser visual consistency\n- Responsive layout testing\n- Dark/light theme validation\n\n#### 5. Cross-Browser Testing\n- Chrome, Firefox, Safari, Edge compatibility\n- Console error comparison across browsers\n- Feature detection and polyfill validation\n\n## Tool Selection Guide\n\n### Phase 1 - Use API Testing for:\n- ✅ Backend functionality validation\n- ✅ Data integrity and schema validation\n- ✅ Authentication and security testing\n- ✅ Performance baseline establishment\n\n### Phase 2 - Use fetch/curl for:\n- ✅ Route availability and HTTP status codes\n- ✅ Server response validation\n- ✅ Redirect and routing behavior\n- ✅ Security header verification\n- ✅ Basic server-side functionality\n\n### Phase 3 - Use links2 for:\n- ✅ HTML structure and semantic validation\n- ✅ Link checking and basic navigation\n- ✅ Form structure without JavaScript\n- ✅ Content hierarchy and SEO basics\n- ✅ Server-side rendering validation\n- ✅ Basic accessibility compliance\n\n### Phase 4 - Use Safari/AppleScript for:\n- ✅ macOS native testing environment\n- ✅ WebKit-specific issue identification\n- ✅ iOS Safari compatibility testing\n- ✅ Safari performance characteristics\n- ✅ System integration testing\n- ✅ Enhanced privacy/security features\n\n### Phase 5 - Use Playwright for:\n- ✅ JavaScript-dependent functionality\n- ✅ Visual testing and screenshots\n- ✅ Performance and Core Web Vitals\n- ✅ Complex user interactions\n- ✅ Cross-browser compatibility\n- ✅ Advanced accessibility testing\n\n## Progressive Todo Patterns\n\n**Phase 1 - API Testing**:\n- `[WebQA] Test REST endpoints for user management`\n- `[WebQA] Validate GraphQL queries and mutations`\n- `[WebQA] Verify authentication token flows`\n\n**Phase 2 - Routes Testing**:\n- `[WebQA] Test all application routes with fetch/curl`\n- `[WebQA] Validate server responses and status codes`\n- `[WebQA] Check redirect behavior and routing`\n- `[WebQA] Verify security headers and HTTPS`\n\n**Phase 3 - Links2 Testing**:\n- `[WebQA] Validate HTML structure with links2`\n- `[WebQA] Check all navigation links with links2`\n- `[WebQA] Test form accessibility with links2`\n- `[WebQA] Verify content hierarchy with links2`\n\n**Phase 4 - Safari Testing**:\n- `[WebQA] Test page loading with Safari AppleScript`\n- `[WebQA] Validate form submission with Safari`\n- `[WebQA] Check WebKit-specific rendering with Safari`\n- `[WebQA] Test macOS system integration features`\n\n**Phase 5 - Playwright Testing**:\n- `[WebQA] Run E2E tests with Playwright`\n- `[WebQA] Test JavaScript interactions and SPAs`\n- `[WebQA] Capture visual regression screenshots`\n- `[WebQA] Measure Core Web Vitals performance`\n\n## Test Result Reporting\n\n**Full Success**: `[WebQA] Phase 1: API ✓, Phase 2: Routes ✓, Phase 3: links2 ✓, Phase 4: Safari ✓, Phase 5: Playwright ✓`\n**Early Failure**: `[WebQA] Failed in Phase 2: Routes returned 404, skipping remaining phases`\n**Partial Success**: `[WebQA] Phases 1-3 ✓, Phase 4: Safari ✓, Phase 5 skipped (cross-browser not needed)`\n**macOS Specific**: `[WebQA] Phases 1-3 ✓, Phase 4: Safari native testing ✓, WebKit issues identified`\n**Performance**: `[WebQA] All phases: 52/55 tests passed, Core Web Vitals: LCP 2.1s, FID 45ms, Safari performance optimal`\n\n## Quality Standards\n\n- **Granular Progression**: Test lightest tools first, escalate only when needed\n- **Fail Fast**: Stop progression if fundamental issues found in early phases\n- **Tool Efficiency**: Use appropriate tool for each testing concern\n- **Resource Management**: Minimize heavy browser usage through smart progression\n- **Comprehensive Coverage**: Ensure all layers tested appropriately\n- **Clear Documentation**: Document progression decisions and tool selection rationale",
+  "knowledge": {
+    "domain_expertise": [
+      "5-phase progressive web testing (API → Routes → Links2 → Safari → Playwright)",
+      "API endpoint testing (REST, GraphQL, WebSocket)",
+      "Routes and server response testing (fetch/curl)",
+      "Text-based browser testing with links2",
+      "Safari testing with AppleScript automation on macOS",
+      "WebKit-specific testing and debugging",
+      "Browser automation (Playwright, Puppeteer)",
+      "Performance testing and Core Web Vitals",
+      "Accessibility and WCAG compliance",
+      "Visual regression testing",
+      "Cross-browser compatibility",
+      "macOS system integration testing"
+    ],
+    "best_practices": [
+      "5-phase granular progression: API → Routes → Links2 → Safari → Playwright",
+      "API-first testing for backend validation",
+      "Routes testing with fetch/curl for server responses", 
+      "Text browser validation before browser automation",
+      "Safari testing for macOS native WebKit validation",
+      "AppleScript automation for system-level integration testing",
+      "Progressive escalation between testing phases",
+      "Fail-fast progression between phases",
+      "Console error monitoring in browser phases",
+      "Screenshot on failure",
+      "Visual regression baselines",
+      "Resource-efficient smart escalation"
+    ],
+    "constraints": [
+      "5-phase testing workflow dependencies",
+      "API availability for Phase 1 testing",
+      "Routes accessibility for Phase 2 validation",
+      "Text browser limitations for JavaScript",
+      "Safari/AppleScript availability on macOS only",
+      "AppleScript permissions and security restrictions",
+      "Browser automation resource usage",
+      "Cross-origin restrictions", 
+      "Visual baseline management"
+    ]
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "task",
+        "target_url"
+      ],
+      "optional_fields": [
+        "browsers",
+        "devices",
+        "test_type"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "test_results",
+        "console_errors",
+        "performance_metrics",
+        "screenshots"
+      ]
+    },
+    "handoff_agents": [
+      "web-ui",
+      "engineer",
+      "security"
+    ],
+    "triggers": [
+      "deployment_ready",
+      "ui_components_ready"
+    ]
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "Progressive web testing",
+        "input": "Test user registration flow",
+        "expected_behavior": "Tests API, then routes with fetch/curl, then links2 validation, then Safari on macOS, then Playwright if needed",
+        "validation_criteria": [
+          "api_tested",
+          "routes_validated",
+          "links2_validation",
+          "safari_tested",
+          "progressive_escalation",
+          "console_monitored"
+        ]
+      },
+      {
+        "name": "Routes testing validation",
+        "input": "Validate application routing and server responses",
+        "expected_behavior": "Uses fetch/curl for route testing before HTML validation",
+        "validation_criteria": [
+          "routes_accessible",
+          "status_codes_correct",
+          "headers_validated",
+          "redirects_working"
+        ]
+      },
+      {
+        "name": "Text browser validation",
+        "input": "Validate static page structure",
+        "expected_behavior": "Uses links2 for HTML structure and accessibility checks",
+        "validation_criteria": [
+          "html_structure_valid",
+          "links_accessible",
+          "content_hierarchy_correct"
+        ]
+      },
+      {
+        "name": "Safari AppleScript testing",
+        "input": "Test form submission on macOS",
+        "expected_behavior": "Uses Safari with AppleScript for native macOS browser testing",
+        "validation_criteria": [
+          "safari_launched",
+          "page_loaded",
+          "form_filled_via_applescript",
+          "webkit_behavior_validated",
+          "screenshots_captured"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 600,
+      "token_usage": 8192,
+      "success_rate": 0.95
+    }
+  },
+  "dependencies": {
+    "python": [
+      "playwright>=1.40.0",
+      "pytest>=7.4.0",
+      "requests>=2.25.0",
+      "pillow>=9.0.0",
+      "axe-selenium-python>=2.1.0"
+    ],
+    "system": [
+      "curl",
+      "links2",
+      "node>=18.0.0",
+      "python3>=3.8",
+      "chromium",
+      "firefox",
+      "safari",
+      "osascript"
+    ],
+    "npm": [
+      "@playwright/test",
+      "lighthouse",
+      "@axe-core/puppeteer"
+    ],
+    "optional": false
+  }
+}

{claude_mpm-4.1.15 → claude_mpm-4.1.19}/src/claude_mpm/cli/commands/mpm_init.py

@@ -3,6 +3,9 @@ MPM-Init Command - Initialize projects for optimal Claude Code and Claude MPM su
 
 This command delegates to the Agentic Coder Optimizer agent to establish clear,
 single-path project standards for documentation, tooling, and workflows.
+
+Enhanced with AST inspection capabilities for generating comprehensive developer
+documentation with code structure analysis.
 """
 
 import logging
@@ -35,6 +38,7 @@ class MPMInitCommand:
         force: bool = False,
         verbose: bool = False,
         use_venv: bool = False,
+        ast_analysis: bool = True,
     ) -> Dict:
         """
         Initialize project with Agentic Coder Optimizer standards.
@@ -44,6 +48,8 @@ class MPMInitCommand:
             framework: Specific framework if applicable
             force: Force initialization even if project already configured
             verbose: Show detailed output
+            use_venv: Force use of venv instead of mamba
+            ast_analysis: Enable AST analysis for enhanced documentation
 
         Returns:
             Dict containing initialization results
@@ -59,7 +65,9 @@ class MPMInitCommand:
                 return {"status": "cancelled", "message": "Initialization cancelled"}
 
             # Build the delegation prompt
-            prompt = self._build_initialization_prompt(project_type, framework)
+            prompt = self._build_initialization_prompt(
+                project_type, framework, ast_analysis
+            )
 
             # Show initialization plan
             console.print(
@@ -71,8 +79,15 @@ class MPMInitCommand:
                     "• Optimized project structure\n"
                     "• Tool configurations (linting, formatting, testing)\n"
                     "• GitHub workflows and CI/CD setup\n"
-                    "• Memory system initialization\n\n"
-                    "[dim]Powered by Agentic Coder Optimizer Agent[/dim]",
+                    "• Memory system initialization\n"
+                    + (
+                        "• AST analysis for comprehensive code documentation\n"
+                        if ast_analysis
+                        else ""
+                    )
+                    + "• Holistic CLAUDE.md organization with ranked instructions\n"
+                    + "• Priority-based content structure (🔴🟡🟢⚪)\n"
+                    + "\n[dim]Powered by Agentic Coder Optimizer Agent[/dim]",
                     title="MPM-Init",
                     border_style="cyan",
                 )
@@ -111,7 +126,10 @@ class MPMInitCommand:
         return Path("claude-mpm")
 
     def _build_initialization_prompt(
-        self, project_type: Optional[str] = None, framework: Optional[str] = None
+        self,
+        project_type: Optional[str] = None,
+        framework: Optional[str] = None,
+        ast_analysis: bool = True,
     ) -> str:
         """Build the initialization prompt for the agent."""
         base_prompt = f"""Please delegate this task to the Agentic Coder Optimizer agent:
@@ -173,9 +191,122 @@ Please perform the following initialization tasks:
    - Step-by-step setup instructions
    - Common commands reference
    - Troubleshooting guide
+"""
+
+        if ast_analysis:
+            base_prompt += """
+9. **Perform AST Analysis** (using Code Analyzer agent if needed):
+   - Parse code files to extract structure (classes, functions, methods)
+   - Generate comprehensive API documentation
+   - Create code architecture diagrams
+   - Document function signatures and dependencies
+   - Extract docstrings and inline comments
+   - Map code relationships and inheritance hierarchies
+   - Generate developer documentation with:
+     * Module overview and purpose
+     * Class hierarchies and relationships
+     * Function/method documentation
+     * Type annotations and parameter descriptions
+     * Code complexity metrics
+     * Dependency graphs
+   - Create DEVELOPER.md with technical architecture details
+   - Add CODE_STRUCTURE.md with AST-derived insights
+"""
+
+        base_prompt += """
+
+10. **Holistic CLAUDE.md Organization** (CRITICAL - Do this LAST):
+   After completing all initialization tasks, take a holistic look at the CLAUDE.md file and:
+   
+   a) **Reorganize Content by Priority**:
+      - CRITICAL instructions (security, data handling, core business rules) at the TOP
+      - Project overview and purpose
+      - Key architectural decisions and constraints
+      - Development guidelines and standards
+      - Common tasks and workflows
+      - Links to additional documentation
+      - Nice-to-have or optional information at the BOTTOM
+   
+   b) **Rank Instructions by Importance**:
+      - Use clear markers: 
+        * 🔴 CRITICAL: Security, data handling, breaking changes, core business rules
+        * 🟡 IMPORTANT: Key workflows, architecture decisions, performance requirements
+        * 🟢 STANDARD: Common operations, coding standards, best practices
+        * ⚪ OPTIONAL: Nice-to-have features, experimental code, future considerations
+      - Group related instructions together
+      - Ensure no contradictory instructions exist
+      - Remove redundant or outdated information
+      - Add a "Priority Index" at the top listing all CRITICAL and IMPORTANT items
+   
+   c) **Optimize for AI Agent Understanding**:
+      - Use consistent formatting and structure
+      - Provide clear examples for complex instructions
+      - Include "WHY" explanations for critical rules
+      - Add quick reference sections for common operations
+      - Ensure instructions are actionable and unambiguous
+   
+   d) **Validate Completeness**:
+      - Ensure ALL critical project knowledge is captured
+      - Verify single-path principle (ONE way to do each task)
+      - Check that all referenced documentation exists
+      - Confirm all tools and dependencies are documented
+      - Test that a new AI agent could understand the project from CLAUDE.md alone
+   
+   e) **Add Meta-Instructions Section**:
+      - Include a section about how to maintain CLAUDE.md
+      - Document when and how to update instructions
+      - Provide guidelines for instruction priority levels
+      - Add a changelog or last-updated timestamp
+   
+   f) **Follow This CLAUDE.md Template Structure**:
+      ```markdown
+      # Project Name - CLAUDE.md
+      
+      ## 🎯 Priority Index
+      ### 🔴 CRITICAL Instructions
+      - [List all critical items with links to their sections]
+      
+      ### 🟡 IMPORTANT Instructions
+      - [List all important items with links to their sections]
+      
+      ## 📋 Project Overview
+      [Brief description and purpose]
+      
+      ## 🔴 CRITICAL: Security & Data Handling
+      [Critical security rules and data handling requirements]
+      
+      ## 🔴 CRITICAL: Core Business Rules
+      [Non-negotiable business logic and constraints]
+      
+      ## 🟡 IMPORTANT: Architecture & Design
+      [Key architectural decisions and patterns]
+      
+      ## 🟡 IMPORTANT: Development Workflow
+      ### ONE Way to Build
+      ### ONE Way to Test
+      ### ONE Way to Deploy
+      
+      ## 🟢 STANDARD: Coding Guidelines
+      [Standard practices and conventions]
+      
+      ## 🟢 STANDARD: Common Tasks
+      [How to perform routine operations]
+      
+      ## 📚 Documentation Links
+      [Links to additional resources]
+      
+      ## ⚪ OPTIONAL: Future Enhancements
+      [Nice-to-have features and ideas]
+      
+      ## 📝 Meta: Maintaining This Document
+      - Last Updated: [timestamp]
+      - Update Frequency: [when to update]
+      - Priority Guidelines: [how to assign priorities]
+      ```
 
 Please ensure all documentation is clear, concise, and optimized for AI agents to understand and follow.
 Focus on establishing ONE clear way to do ANYTHING in the project.
+The final CLAUDE.md should be a comprehensive, well-organized guide that any AI agent can follow to work effectively on this project.
 """
 
         return base_prompt
@@ -369,7 +500,11 @@ Focus on establishing ONE clear way to do ANYTHING in the project.
                     "[green]Your project is now optimized for Claude Code and Claude MPM![/green]\n\n"
                     "Key files:\n"
                     "• [cyan]CLAUDE.md[/cyan] - Main documentation for AI agents\n"
-                    "• [cyan].claude-mpm/[/cyan] - Configuration and memories\n\n"
+                    "  - Organized with priority rankings (🔴🟡🟢⚪)\n"
+                    "  - Instructions ranked by importance for AI understanding\n"
+                    "  - Holistic documentation review completed\n"
+                    "• [cyan].claude-mpm/[/cyan] - Configuration and memories\n"
+                    "• [cyan]CODE_STRUCTURE.md[/cyan] - AST-derived architecture documentation (if enabled)\n\n"
                     "[dim]Run 'claude-mpm run' to start using the optimized setup[/dim]",
                     title="Success",
                     border_style="green",
@@ -398,13 +533,18 @@ Focus on establishing ONE clear way to do ANYTHING in the project.
 @click.option(
     "--verbose", is_flag=True, help="Show detailed output during initialization"
 )
+@click.option(
+    "--ast-analysis/--no-ast-analysis",
+    default=True,
+    help="Enable/disable AST analysis for enhanced documentation (default: enabled)",
+)
 @click.argument(
     "project_path",
     type=click.Path(exists=True, file_okay=False, dir_okay=True),
     required=False,
     default=".",
 )
-def mpm_init(project_type, framework, force, verbose, project_path):
+def mpm_init(project_type, framework, force, verbose, ast_analysis, project_path):
     """
     Initialize a project for optimal use with Claude Code and Claude MPM.
 
@@ -414,11 +554,14 @@ def mpm_init(project_type, framework, force, verbose, project_path):
     - Configure development tools and standards
     - Set up memory systems for project knowledge
     - Optimize for AI agent understanding
+    - Perform AST analysis for enhanced developer documentation
 
     Examples:
         claude-mpm mpm-init
         claude-mpm mpm-init --project-type web --framework react
         claude-mpm mpm-init /path/to/project --force
+        claude-mpm mpm-init --ast-analysis  # Enable AST analysis (default)
+        claude-mpm mpm-init --no-ast-analysis  # Disable AST analysis
     """
     try:
         # Create command instance
@@ -426,7 +569,11 @@ def mpm_init(project_type, framework, force, verbose, project_path):
 
         # Run initialization (now synchronous)
         result = command.initialize_project(
-            project_type=project_type, framework=framework, force=force, verbose=verbose
+            project_type=project_type,
+            framework=framework,
+            force=force,
+            verbose=verbose,
+            ast_analysis=ast_analysis,
         )
 
         # Exit with appropriate code

{claude_mpm-4.1.15 → claude_mpm-4.1.19}/src/claude_mpm/cli/commands/mpm_init_handler.py

@@ -56,6 +56,7 @@ def manage_mpm_init(args):
             "force": getattr(args, "force", False),
             "verbose": getattr(args, "verbose", False),
             "use_venv": getattr(args, "use_venv", False),
+            "ast_analysis": getattr(args, "ast_analysis", True),
         }
 
         # Execute initialization (now synchronous)

{claude_mpm-4.1.15 → claude_mpm-4.1.19}/src/claude_mpm/cli/parsers/mpm_init_parser.py

@@ -88,6 +88,19 @@ def add_mpm_init_subparser(subparsers: Any) -> None:
         action="store_true",
         help="Use traditional Python venv instead of mamba/conda environment",
     )
+    init_group.add_argument(
+        "--ast-analysis",
+        action="store_true",
+        default=True,
+        dest="ast_analysis",
+        help="Enable AST analysis for enhanced developer documentation (default: enabled)",
+    )
+    init_group.add_argument(
+        "--no-ast-analysis",
+        action="store_false",
+        dest="ast_analysis",
+        help="Disable AST analysis for documentation generation",
+    )
 
     # Template options
     template_group = mpm_init_parser.add_argument_group("template options")