claude-mpm 4.1.15__py3-none-any.whl → 4.1.19__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.1.15
+4.1.18

claude_mpm/agents/templates/web_qa.json

@@ -1,25 +1,32 @@
 {
   "name": "Web QA Agent",
-  "description": "Specialized web testing agent with dual API and browser automation capabilities",
+  "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.5.0",
+  "agent_version": "1.8.0",
   "agent_type": "qa",
   "metadata": {
     "name": "Web QA Agent",
-    "description": "Web testing with API and browser automation for E2E, performance, and accessibility testing",
+    "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"
+      "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-25T00:00:00.000000Z",
+    "updated_at": "2025-08-30T00:00:00.000000Z",
     "color": "purple"
   },
   "routing": {
@@ -29,8 +36,18 @@
       "frontend",
       "browser",
       "playwright",
+      "safari",
+      "applescript",
       "e2e",
-      "accessibility"
+      "accessibility",
+      "links2",
+      "text_browser",
+      "api_test",
+      "routes",
+      "fetch",
+      "curl",
+      "progressive",
+      "macos"
     ],
     "paths": [
       "/components/",
@@ -49,7 +66,7 @@
     ],
     "priority": 100,
     "confidence_threshold": 0.7,
-    "description": "Use for frontend UI, browser compatibility, and accessibility testing"
+    "description": "Use for 5-phase progressive web testing: API → Routes (fetch/curl) → Links2 → Safari (AppleScript) → Playwright automation"
   },
   "capabilities": {
     "model": "sonnet",
@@ -81,26 +98,45 @@
       ]
     }
   },
-  "instructions": "# Web QA Agent\n\n**Inherits from**: BASE_QA_AGENT.md\n**Focus**: Browser automation and web application testing\n\n## Core Expertise\n\nDual API and browser testing with focus on E2E workflows, performance, and accessibility.\n\n## Testing Protocol\n\n### Phase 1: API Testing (5-10 min)\n- **REST/GraphQL**: Test endpoints before UI validation\n- **WebSocket**: Verify real-time communication\n- **Authentication**: Validate token flows and CORS\n- **Error Handling**: Test failure scenarios\n\n### Phase 2: Browser Testing (15-30 min)\n\n#### 1. E2E Test Execution\n- User journey testing with Playwright/Puppeteer\n- Form validation and submission flows\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## Web QA-Specific Todo Patterns\n\n**API Testing**:\n- `[WebQA] Test REST endpoints for authentication`\n- `[WebQA] Validate GraphQL queries and mutations`\n\n**Browser Testing**:\n- `[WebQA] Run E2E tests with console monitoring`\n- `[WebQA] Test checkout flow across browsers`\n- `[WebQA] Capture visual regression screenshots`\n\n**Performance & Accessibility**:\n- `[WebQA] Measure Core Web Vitals on critical pages`\n- `[WebQA] Run WCAG compliance audit`\n- `[WebQA] Test keyboard navigation`\n\n## Test Result Reporting\n\n**Success**: `[WebQA] Tests: 42/45 passed, Performance: All targets met`\n**Failure**: `[WebQA] Failed: Checkout validation error (screenshot: checkout_error.png)`\n**Console**: `[WebQA] Console: 2 warnings, 0 errors`\n\n## Quality Standards\n\n- Test APIs before UI for faster feedback\n- Monitor console errors during all interactions\n- Capture screenshots on failures\n- Use data-testid for stable selectors\n- Generate comprehensive reports",
+  "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)",
-      "API testing (REST, GraphQL, WebSocket)",
       "Performance testing and Core Web Vitals",
       "Accessibility and WCAG compliance",
       "Visual regression testing",
-      "Cross-browser compatibility"
+      "Cross-browser compatibility",
+      "macOS system integration testing"
     ],
     "best_practices": [
-      "API-first testing approach",
-      "Console error monitoring",
+      "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",
-      "Parallel test execution"
+      "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",
+      "Cross-origin restrictions", 
       "Visual baseline management"
     ]
   },
@@ -138,14 +174,50 @@
   "testing": {
     "test_cases": [
       {
-        "name": "E2E browser testing",
+        "name": "Progressive web testing",
         "input": "Test user registration flow",
-        "expected_behavior": "Tests API then browser with console monitoring",
+        "expected_behavior": "Tests API, then routes with fetch/curl, then links2 validation, then Safari on macOS, then Playwright if needed",
         "validation_criteria": [
           "api_tested",
-          "browser_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": {
@@ -163,10 +235,14 @@
       "axe-selenium-python>=2.1.0"
     ],
     "system": [
+      "curl",
+      "links2",
       "node>=18.0.0",
       "python3>=3.8",
       "chromium",
-      "firefox"
+      "firefox",
+      "safari",
+      "osascript"
     ],
     "npm": [
       "@playwright/test",

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/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/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")

claude_mpm/commands/mpm-init.md

@@ -0,0 +1,162 @@
+# /mpm-init
+
+Initialize your project for optimal use with Claude Code and Claude MPM using the Agentic Coder Optimizer agent.
+
+## Usage
+
+```
+/mpm-init
+/mpm-init --project-type web --framework react
+/mpm-init --force
+/mpm-init --ast-analysis
+/mpm-init --comprehensive
+```
+
+## Description
+
+This command delegates to the Agentic Coder Optimizer agent to establish clear, single-path project standards for documentation, tooling, and workflows. It creates comprehensive documentation optimized for AI agents.
+
+## Features
+
+- **📚 Comprehensive CLAUDE.md**: Creates AI-optimized project documentation
+- **🎯 Priority-based Organization**: Ranks instructions by importance (🔴🟡🟢⚪)
+- **🔍 AST Analysis**: Deep code structure analysis for enhanced documentation
+- **🚀 Single-path Workflows**: Establishes ONE way to do ANYTHING
+- **🧠 Memory System**: Initializes project knowledge retention
+- **🔧 Tool Configuration**: Sets up linting, formatting, testing
+- **📝 Holistic Review**: Final organization and validation pass
+
+## Options
+
+- `--project-type [type]`: Specify project type (web, api, cli, library, etc.)
+- `--framework [name]`: Specify framework (react, vue, django, fastapi, etc.)
+- `--force`: Force reinitialization even if project is already configured
+- `--ast-analysis`: Enable AST analysis for enhanced documentation (default: enabled)
+- `--no-ast-analysis`: Disable AST analysis for faster initialization
+- `--comprehensive`: Create comprehensive setup including CI/CD and deployment
+- `--minimal`: Create minimal configuration (CLAUDE.md only)
+
+## What This Command Does
+
+### 1. Project Analysis
+- Scans project structure and existing configurations
+- Identifies project type, language, and frameworks
+- Checks for existing documentation and tooling
+
+### 2. CLAUDE.md Creation/Update
+The command creates a well-organized CLAUDE.md with:
+
+```markdown
+## 🎯 Priority Index
+### 🔴 CRITICAL Instructions
+- Security rules, data handling, core business logic
+
+### 🟡 IMPORTANT Instructions  
+- Key workflows, architecture decisions
+
+### 🟢 STANDARD Instructions
+- Common operations, coding standards
+
+### ⚪ OPTIONAL Instructions
+- Nice-to-have features, future enhancements
+```
+
+### 3. Single-Path Standards
+- ONE command for building: `make build`
+- ONE command for testing: `make test`
+- ONE command for deployment: `make deploy`
+- Clear documentation of THE way to do things
+
+### 4. AST Analysis (Optional)
+When enabled, performs:
+- Code structure extraction (classes, functions, methods)
+- API documentation generation
+- Architecture diagram creation
+- Function signature and dependency mapping
+- Creates DEVELOPER.md with technical details
+- Adds CODE_STRUCTURE.md with AST insights
+
+### 5. Tool Configuration
+- Linting setup and configuration
+- Code formatting standards
+- Testing framework setup
+- Pre-commit hooks if needed
+
+### 6. Memory System
+- Creates `.claude-mpm/memories/` directory
+- Initializes memory files for project knowledge
+- Documents memory usage patterns
+
+### 7. Holistic Organization (Final Step)
+After all tasks, performs a comprehensive review:
+- Reorganizes content by priority
+- Validates completeness
+- Ensures single-path principle
+- Adds meta-instructions for maintenance
+
+## Examples
+
+### Basic Initialization
+```bash
+/mpm-init
+```
+Analyzes current directory and creates optimal setup.
+
+### Web Project with React
+```bash
+/mpm-init --project-type web --framework react
+```
+Initializes with web-specific configurations and React patterns.
+
+### Force Reinitialization
+```bash
+/mpm-init --force --comprehensive
+```
+Overwrites existing configuration with comprehensive setup.
+
+### Fast Mode (No AST)
+```bash
+/mpm-init --no-ast-analysis --minimal
+```
+Quick initialization without code analysis.
+
+## Implementation
+
+This command executes:
+```bash
+claude-mpm mpm-init [options]
+```
+
+The command delegates to the Agentic Coder Optimizer agent which:
+1. Analyzes your project structure
+2. Creates comprehensive documentation
+3. Establishes single-path workflows
+4. Configures development tools
+5. Sets up memory systems
+6. Performs AST analysis (if enabled)
+7. Organizes everything with priority rankings
+
+## Expected Output
+
+After successful execution:
+- ✅ **CLAUDE.md**: Main AI agent documentation with priority rankings
+- ✅ **Single-path workflows**: Clear commands for all operations
+- ✅ **Tool configurations**: Linting, formatting, testing setup
+- ✅ **Memory system**: Initialized for knowledge retention
+- ✅ **Developer docs**: Technical documentation (with AST analysis)
+- ✅ **Priority organization**: Instructions ranked by importance
+
+## Notes
+
+- The command uses the Agentic Coder Optimizer agent for implementation
+- AST analysis is enabled by default for comprehensive documentation
+- Priority rankings help AI agents focus on critical instructions first
+- The holistic review ensures documentation quality and completeness
+- All documentation is optimized for AI agent understanding
+
+## Related Commands
+
+- `/mpm-status`: Check current project setup status
+- `/mpm-agents`: Manage specialized agents
+- `/mpm-config`: Configure Claude MPM settings
+- `/mpm-doctor`: Diagnose and fix issues