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

claude_mpm/VERSION

@@ -1 +1 @@
-4.1.15
+4.1.17

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

claude_mpm/dashboard/static/css/activity.css

@@ -261,6 +261,14 @@
     flex-shrink: 0;
 }
 
+.tree-status-icon {
+    font-size: 14px;
+    width: 18px;
+    text-align: center;
+    flex-shrink: 0;
+    margin-left: 2px;
+}
+
 .tree-expand-icon {
     font-size: 12px;
     width: 16px;
@@ -470,6 +478,7 @@ body .activity-tree-container .linear-tree .tree-node.tool.status-in_progress,
     background: #e6fffa !important;
     border-left-color: #38b2ac !important;
     border-left-width: 3px !important;
+    animation: pulse-tool 2s infinite;
 }
 
 body .activity-tree-container .linear-tree .tree-node.tool.status-completed,
@@ -486,6 +495,43 @@ body .activity-tree-container .linear-tree .tree-node.tool.status-failed,
     border-left-width: 2px !important;
 }
 
+/* Tool Status Icons */
+.tree-node.tool .tree-status-icon {
+    color: #718096;
+}
+
+.tree-node.tool.status-in_progress .tree-status-icon {
+    color: #38b2ac;
+    animation: spin 2s linear infinite;
+}
+
+.tree-node.tool.status-completed .tree-status-icon {
+    color: #38a169;
+}
+
+.tree-node.tool.status-failed .tree-status-icon {
+    color: #e53e3e;
+}
+
+/* Spinning animation for in-progress tools */
+@keyframes spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+}
+
+/* Pulse animation for in-progress tools */
+@keyframes pulse-tool {
+    0% {
+        background: #e6fffa !important;
+    }
+    50% {
+        background: #b2f5ea !important;
+    }
+    100% {
+        background: #e6fffa !important;
+    }
+}
+
 /* Privileged Tool (TodoWrite) - High Specificity */
 body .activity-tree-container .linear-tree .tree-node.tool.privileged-tool,
 .tree-node.tool.privileged-tool {
@@ -523,6 +569,7 @@ body .activity-tree-container .linear-tree .tree-node.tool.privileged-tool .tree
     background: #e6fffa !important;
     border-left-color: #38b2ac !important;
     border-left-width: 3px !important;
+    animation: pulse-tool 2s infinite;
 }
 
 .tree-node.tool:not(.privileged-tool).status-completed {
@@ -612,6 +659,44 @@ body .activity-tree-container .linear-tree .tree-node.tool.privileged-tool .tree
     }
 }
 
+/* Pinned TODOs Styles */
+.tree-node.pinned-todos {
+    background: linear-gradient(135deg, #fff8dc 0%, #f0e68c 100%) !important;
+    border-left: 4px solid #daa520 !important;
+    border-radius: 6px !important;
+    margin: 4px 0 !important;
+    font-weight: 600 !important;
+}
+
+.tree-node.pinned-todos:hover {
+    background: linear-gradient(135deg, #f0e68c 0%, #daa520 100%) !important;
+    box-shadow: 0 4px 8px rgba(218, 165, 32, 0.3) !important;
+}
+
+.tree-node.pinned-todos .tree-label {
+    color: #b8860b !important;
+    font-weight: bold !important;
+}
+
+.tree-node.pinned-todos .tree-icon {
+    color: #daa520 !important;
+    font-size: 18px !important;
+}
+
+.tree-node.pinned-todos .tree-params {
+    background: #f5deb3 !important;
+    color: #8b4513 !important;
+    font-weight: 600 !important;
+    border: 1px solid #daa520 !important;
+}
+
+.tree-node.pinned-todos .tree-status {
+    background: #daa520 !important;
+    color: white !important;
+    font-weight: bold !important;
+    text-transform: uppercase !important;
+}
+
 /* Tree Legend */
 .tree-legend {
     position: absolute;
@@ -1518,4 +1603,84 @@ body .activity-tree-container .linear-tree .tree-node.tool.privileged-tool .tree
 .tree-expand-icon:focus {
     outline: 2px solid #4299e1;
     outline-offset: 2px;
+}
+
+/* Active/current item highlighting */
+.tree-node.current-active {
+    background: linear-gradient(90deg, rgba(245, 158, 11, 0.1) 0%, transparent 100%);
+    border-left: 3px solid #f59e0b;
+    animation: pulse-active 2s ease-in-out infinite;
+}
+
+.tree-node.has-active .tree-node-content {
+    font-weight: 600;
+}
+
+.tree-node.todowrite.has-active .tree-icon {
+    animation: rotate-icon 3s linear infinite;
+}
+
+@keyframes pulse-active {
+    0%, 100% {
+        background: linear-gradient(90deg, rgba(245, 158, 11, 0.1) 0%, transparent 100%);
+    }
+    50% {
+        background: linear-gradient(90deg, rgba(245, 158, 11, 0.2) 0%, transparent 100%);
+    }
+}
+
+@keyframes rotate-icon {
+    from {
+        transform: rotate(0deg);
+    }
+    to {
+        transform: rotate(360deg);
+    }
+}
+
+/* Collapsed state indicators */
+.tree-node.agent:not(.expanded) .tree-label {
+    font-style: italic;
+    color: #4b5563;
+}
+
+.tree-node.agent .tree-label .current-status {
+    color: #f59e0b;
+    font-weight: 600;
+    margin-left: 10px;
+}
+
+/* TodoWrite specific styles */
+.tree-node.todowrite {
+    background: rgba(99, 102, 241, 0.05);
+    border-radius: 4px;
+    margin: 2px 0;
+}
+
+.tree-node.todowrite .tree-node-content {
+    padding: 4px 8px;
+}
+
+/* Multiple call/update indicators */
+.tree-node .tree-label .call-count,
+.tree-node .tree-label .update-count {
+    color: #6366f1;
+    font-weight: 600;
+    font-size: 0.85em;
+    opacity: 0.8;
+}
+
+.tree-node.tool .tree-label {
+    position: relative;
+}
+
+.tree-node.tool .call-indicator {
+    display: inline-block;
+    background: #f59e0b;
+    color: white;
+    border-radius: 10px;
+    padding: 0 6px;
+    font-size: 0.75em;
+    margin-left: 5px;
+    font-weight: 600;
 }