claude-mpm 5.0.2__py3-none-any.whl → 5.4.3__py3-none-any.whl

claude_mpm/cli/commands/mpm_init/prompts.py

@@ -10,7 +10,9 @@ from pathlib import Path
 from typing import Any, Dict, Optional
 
 __all__ = [
+    "build_enhanced_update_prompt",
     "build_initialization_prompt",
+    "build_prompt_engineer_optimization_prompt",
     "build_research_context_prompt",
     "build_update_prompt",
 ]
@@ -305,6 +307,208 @@ preserving valuable project-specific information while refreshing standard secti
     return prompt
 
 
+def build_enhanced_update_prompt(
+    project_path: Path,
+    doc_analysis: Dict[str, Any],
+    git_insights: Dict[str, Any],
+    log_insights: Dict[str, Any],
+    memory_insights: Dict[str, Any],
+    project_type: Optional[str] = None,
+    framework: Optional[str] = None,
+    ast_analysis: bool = True,
+    preserve_custom: bool = True,
+) -> str:
+    """
+    Build enhanced update prompt with extracted knowledge from multiple sources.
+
+    This is the AUTO-DETECTED update mode that enriches CLAUDE.md with:
+    - Git history insights (architectural decisions, tech changes, workflows)
+    - Session log learnings (completed work, patterns)
+    - Memory file knowledge (accumulated project wisdom)
+
+    Args:
+        project_path: Path to the project directory
+        doc_analysis: Analysis results from DocumentationManager
+        git_insights: Extracted git history insights
+        log_insights: Extracted session log insights
+        memory_insights: Extracted memory file insights
+        project_type: Type of project (web, api, cli, library, etc.)
+        framework: Specific framework if applicable
+        ast_analysis: Enable AST analysis for enhanced documentation
+        preserve_custom: Preserve custom sections when updating
+
+    Returns:
+        Formatted prompt string for enhanced update mode
+    """
+    prompt = f"""Please delegate this task to the Agentic Coder Optimizer agent:
+
+ENHANCED UPDATE of existing CLAUDE.md documentation with extracted project knowledge.
+
+Project Path: {project_path}
+Update Mode: Knowledge-enriched smart merge
+"""
+    if project_type:
+        prompt += f"Project Type: {project_type}\n"
+    if framework:
+        prompt += f"Framework: {framework}\n"
+
+    prompt += f"""
+Existing Documentation Analysis:
+- Current CLAUDE.md: {doc_analysis.get("size", 0):,} characters, {doc_analysis.get("lines", 0)} lines
+- Has Priority Index: {"Yes" if doc_analysis.get("has_priority_index") else "No"}
+- Custom Sections: {len(doc_analysis.get("custom_sections", []))} found
+"""
+    if preserve_custom and doc_analysis.get("custom_sections"):
+        prompt += f"- Preserve Custom Sections: {', '.join(doc_analysis['custom_sections'][:5])}\n"
+
+    # Add extracted knowledge sections
+    prompt += "\n## Extracted Project Knowledge\n\n"
+
+    # Git insights
+    if git_insights.get("available"):
+        prompt += "### From Git History (last 90 days):\n\n"
+
+        if git_insights.get("architectural_decisions"):
+            prompt += "**Architectural Patterns Detected:**\n"
+            for decision in git_insights["architectural_decisions"][:10]:
+                prompt += f"- {decision}\n"
+            prompt += "\n"
+
+        if git_insights.get("tech_stack_changes"):
+            prompt += "**Tech Stack Changes:**\n"
+            for change in git_insights["tech_stack_changes"][:10]:
+                prompt += f"- {change}\n"
+            prompt += "\n"
+
+        if git_insights.get("workflow_patterns"):
+            prompt += "**Common Workflows:**\n"
+            for workflow in git_insights["workflow_patterns"][:8]:
+                prompt += f"- {workflow}\n"
+            prompt += "\n"
+
+        if git_insights.get("hot_files"):
+            prompt += "**Hot Files (frequently modified):**\n"
+            for file_info in git_insights["hot_files"][:10]:
+                prompt += (
+                    f"- {file_info['path']} ({file_info['modifications']} changes)\n"
+                )
+            prompt += "\n"
+
+    # Session log insights
+    if log_insights.get("available") and log_insights.get("learnings"):
+        prompt += "### From Session Logs:\n\n"
+        prompt += "**Recent Learnings from PM Summaries:**\n"
+        for learning in log_insights["learnings"][:10]:
+            source = learning.get("source", "unknown")
+            content = learning.get("content", "")
+            # Truncate long content
+            if len(content) > 200:
+                content = content[:200] + "..."
+            prompt += f"- [{source}] {content}\n"
+        prompt += "\n"
+
+        if log_insights.get("common_patterns"):
+            prompt += "**Common Task Patterns:**\n"
+            prompt += f"- {', '.join(log_insights['common_patterns'][:10])}\n\n"
+
+    # Memory insights
+    if memory_insights.get("available"):
+        has_content = False
+
+        if memory_insights.get("architectural_knowledge"):
+            has_content = True
+            prompt += "### From Agent Memories:\n\n"
+            prompt += "**Architectural Knowledge:**\n"
+            for item in memory_insights["architectural_knowledge"][:8]:
+                prompt += f"- {item}\n"
+            prompt += "\n"
+
+        if memory_insights.get("implementation_guidelines"):
+            if not has_content:
+                prompt += "### From Agent Memories:\n\n"
+                has_content = True
+            prompt += "**Implementation Guidelines:**\n"
+            for item in memory_insights["implementation_guidelines"][:8]:
+                prompt += f"- {item}\n"
+            prompt += "\n"
+
+        if memory_insights.get("common_mistakes"):
+            if not has_content:
+                prompt += "### From Agent Memories:\n\n"
+                has_content = True
+            prompt += "**Common Mistakes to Avoid:**\n"
+            for item in memory_insights["common_mistakes"][:8]:
+                prompt += f"- {item}\n"
+            prompt += "\n"
+
+        if memory_insights.get("technical_context"):
+            if not has_content:
+                prompt += "### From Agent Memories:\n\n"
+            prompt += "**Current Technical Context:**\n"
+            for item in memory_insights["technical_context"][:8]:
+                prompt += f"- {item}\n"
+            prompt += "\n"
+
+    # Add update instructions
+    prompt += """
+## UPDATE Tasks with Knowledge Integration:
+
+1. **Review Existing Content**:
+   - Analyze current CLAUDE.md structure and content
+   - Identify outdated or missing information
+   - Preserve valuable custom sections and project-specific knowledge
+
+2. **Integrate Extracted Knowledge**:
+   - Merge architectural decisions from git history into Architecture section
+   - Add tech stack changes to Technology/Dependencies sections
+   - Update workflow patterns in Development Guidelines
+   - Incorporate session learnings into relevant sections
+   - Merge memory insights into appropriate documentation areas
+   - Highlight hot files as critical components
+
+3. **Smart Content Merge**:
+   - Update project overview with recent developments
+   - Refresh architecture documentation with detected patterns
+   - Update development workflows with discovered common patterns
+   - Ensure single-path principle (ONE way to do each task)
+   - Remove duplicate or contradictory information
+
+4. **Update Priority Organization**:
+   - Reorganize content with priority markers (🔴🟡🟢⚪)
+   - Ensure critical instructions are at the top
+   - Update priority index with all important items
+   - Promote frequently-modified files to IMPORTANT sections
+
+5. **Refresh Technical Content**:
+   - Update build/test/deploy commands based on workflow patterns
+   - Verify tool configurations match tech stack changes
+   - Update dependency information with detected changes
+   - Refresh API documentation if applicable
+"""
+    if ast_analysis:
+        prompt += """
+6. **Update Code Documentation** (using Code Analyzer agent):
+   - Re-analyze code structure for changes
+   - Update API documentation
+   - Refresh architecture diagrams
+   - Document hot files and critical components
+"""
+    prompt += """
+7. **Final Optimization**:
+   - Ensure single-path principle throughout
+   - Validate all links and references
+   - Add/update timestamp in meta section
+   - Add "Last Updated" note mentioning knowledge extraction
+   - Verify AI agent readability
+
+IMPORTANT: This is an ENHANCED UPDATE operation with extracted knowledge.
+Intelligently merge insights from git history, session logs, and agent memories
+into the existing CLAUDE.md while preserving valuable custom content.
+The goal is to create a living document that reflects actual project evolution.
+"""
+    return prompt
+
+
 def build_research_context_prompt(git_analysis: Dict[str, Any], days: int) -> str:
     """
     Build structured Research agent delegation prompt from git analysis.
@@ -440,3 +644,79 @@ Keep it concise (<1000 words) but actionable.
 """
 
     return prompt
+
+
+def build_prompt_engineer_optimization_prompt(
+    content: str, estimated_tokens: int
+) -> str:
+    """
+    Build prompt for prompt-engineer to optimize CLAUDE.md.
+
+    Args:
+        content: Current CLAUDE.md content to optimize
+        estimated_tokens: Estimated token count of current content
+
+    Returns:
+        Formatted prompt string for prompt-engineer optimization
+    """
+    return f"""Please delegate this task to the Prompt Engineer agent:
+
+Optimize this CLAUDE.md file for conciseness, clarity, and token efficiency while preserving all critical information.
+
+## Current CLAUDE.md Statistics
+- Estimated tokens: {estimated_tokens:,}
+- Target reduction: 20-30% if possible
+- Priority: Preserve ALL CRITICAL (🔴) and IMPORTANT (🟡) information
+
+## Optimization Goals
+
+1. **Remove Redundancy**:
+   - Eliminate duplicate information across sections
+   - Consolidate similar instructions
+   - Remove verbose explanations where brevity suffices
+
+2. **Tighten Language**:
+   - Use fewer words to convey the same meaning
+   - Replace wordy phrases with concise alternatives
+   - Remove filler words and unnecessary qualifiers
+
+3. **Improve Structure**:
+   - Ensure clear hierarchical organization
+   - Use priority markers (🔴 🟡 🟢 ⚪) effectively
+   - Group related information logically
+   - Maintain scannable headings
+
+4. **Preserve Critical Content**:
+   - Keep ALL security and data handling rules (🔴)
+   - Maintain core business logic and constraints (🔴)
+   - Preserve architectural decisions (🟡)
+   - Keep essential workflows intact (🟡)
+
+5. **Apply Claude Best Practices**:
+   - Use high-level guidance over prescriptive checklists
+   - Provide context for WHY, not just WHAT
+   - Ensure instructions are actionable and unambiguous
+   - Optimize for AI agent understanding
+
+## Current CLAUDE.md Content
+
+{content}
+
+## Output Requirements
+
+Return ONLY the optimized CLAUDE.md content with NO additional explanations.
+The optimized version should:
+- Reduce token count by 20-30% if feasible
+- Maintain all CRITICAL and IMPORTANT instructions
+- Improve clarity and scannability
+- Follow the same structural template (Priority Index, sections with markers)
+
+## Quality Criteria
+
+✅ All 🔴 CRITICAL items preserved
+✅ All 🟡 IMPORTANT items preserved
+✅ No contradictory instructions
+✅ Clear, concise language throughout
+✅ Logical organization maintained
+✅ Token count reduced meaningfully
+"""

claude_mpm/cli/commands/postmortem.py

@@ -0,0 +1,401 @@
+"""
+Postmortem command implementation for claude-mpm.
+
+WHY: Provide a comprehensive analysis tool to help users identify, categorize,
+and fix errors encountered during their session, with automated improvements
+for framework code and suggestions for user code.
+
+DESIGN DECISIONS:
+- Leverages existing FailureTracker for error data
+- Categorizes errors by source (script/skill/agent/user)
+- Provides action-specific handling (auto-fix/update/PR/suggest)
+- Supports dry-run mode for safety
+"""
+
+import sys
+from pathlib import Path
+
+from claude_mpm.core.logging_utils import get_logger
+from claude_mpm.services.analysis import get_postmortem_service
+from claude_mpm.services.analysis.postmortem_reporter import PostmortemReporter
+
+logger = get_logger(__name__)
+
+
+def add_postmortem_parser(subparsers):
+    """Add postmortem command parser.
+
+    WHY: This command helps users analyze session errors and generate
+    actionable improvement suggestions based on error source.
+    """
+    parser = subparsers.add_parser(
+        "postmortem",
+        aliases=["pm-analysis"],
+        help="Analyze session errors and suggest improvements",
+        description="Perform comprehensive analysis of errors encountered during the session",
+    )
+
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview analysis without making changes (default for destructive operations)",
+    )
+
+    parser.add_argument(
+        "--auto-fix",
+        action="store_true",
+        help="Automatically apply fixes to scripts and skills",
+    )
+
+    parser.add_argument(
+        "--create-prs",
+        action="store_true",
+        help="Create pull requests for agent improvements",
+    )
+
+    parser.add_argument(
+        "--session-id",
+        type=str,
+        help="Analyze specific session (default: current session)",
+    )
+
+    parser.add_argument(
+        "--format",
+        choices=["terminal", "json", "markdown"],
+        default="terminal",
+        help="Output format (default: terminal)",
+    )
+
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        help="Save report to file",
+    )
+
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Include detailed error traces and analysis",
+    )
+
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable colored output",
+    )
+
+    parser.set_defaults(func=postmortem_command)
+
+
+def run_postmortem(args):
+    """Main entry point for postmortem command (used by CLI).
+
+    Args:
+        args: Parsed command-line arguments
+
+    Returns:
+        Exit code (0 for success, 1 for warnings, 2 for errors)
+    """
+    return postmortem_command(args)
+
+
+def postmortem_command(args):
+    """Execute the postmortem command.
+
+    WHY: Provides comprehensive error analysis with categorization and
+    actionable improvements, helping users understand and fix issues
+    encountered during their session.
+
+    Args:
+        args: Parsed command-line arguments
+
+    Returns:
+        Exit code (0 for success, 1 for warnings, 2 for errors)
+    """
+    logger.info("Starting postmortem analysis")
+
+    # Get postmortem service
+    service = get_postmortem_service()
+
+    try:
+        # Analyze session
+        report = service.analyze_session(session_id=args.session_id)
+
+        # Handle output file
+        output_file = args.output
+        if output_file:
+            # Ensure file extension matches format
+            if args.format == "json" and not str(output_file).endswith(".json"):
+                output_file = Path(str(output_file) + ".json")
+            elif args.format == "markdown" and not str(output_file).endswith(".md"):
+                output_file = Path(str(output_file) + ".md")
+
+            # Create parent directories
+            output_file = output_file.absolute()
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Determine output format
+        output_format = args.format
+
+        # Create reporter
+        reporter = PostmortemReporter(
+            use_color=not args.no_color,
+            verbose=args.verbose,
+        )
+
+        # Output results
+        if output_file:
+            # Save to file
+            try:
+                with output_file.open("w") as f:
+                    original_output = reporter.output
+                    reporter.output = f
+                    reporter.report(report, format=output_format)
+                    reporter.output = original_output
+
+                print(f"✅ Report saved to: {output_file}")
+
+                # Print brief summary to terminal
+                if report.total_errors > 0:
+                    print(f"\n{report.total_errors} error(s) analyzed")
+                    print(
+                        f"{report.stats['total_actions']} improvement action(s) generated"
+                    )
+                else:
+                    print("\n✅ No errors detected in session!")
+
+            except Exception as e:
+                logger.error(f"Failed to save report: {e}")
+                print(f"❌ Failed to save report: {e!s}")
+                # Still output to terminal
+                reporter.report(report, format="terminal")
+        else:
+            # Output to terminal
+            reporter.report(report, format=output_format)
+
+        # Apply fixes if requested
+        if args.auto_fix and not args.dry_run:
+            exit_code = _apply_auto_fixes(report, args.verbose)
+            if exit_code != 0:
+                return exit_code
+
+        # Create PRs if requested
+        if args.create_prs and not args.dry_run:
+            exit_code = _create_prs(report, args.verbose)
+            if exit_code != 0:
+                return exit_code
+
+        # Dry-run message
+        if args.dry_run and (args.auto_fix or args.create_prs):
+            print("\n🔍 Dry-run mode: No changes applied")
+            print("   Remove --dry-run to apply changes")
+
+        # Determine exit code
+        if report.total_errors == 0:
+            return 0  # No errors
+
+        if report.stats.get("critical_priority", 0) > 0:
+            return 2  # Critical errors found
+
+        return 1  # Non-critical errors found
+
+    except KeyboardInterrupt:
+        print("\nPostmortem analysis interrupted by user")
+        return 130
+
+    except Exception as e:
+        logger.error(f"Postmortem analysis failed: {e}", exc_info=True)
+        print(f"\n❌ Postmortem analysis failed: {e!s}")
+        if args.verbose:
+            import traceback
+
+            traceback.print_exc()
+        return 2
+
+
+def _apply_auto_fixes(report, verbose: bool) -> int:
+    """Apply auto-fix actions from report.
+
+    Args:
+        report: Postmortem report
+        verbose: Show detailed output
+
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    from claude_mpm.services.analysis import ActionType
+
+    auto_fix_actions = report.get_actions_by_type(ActionType.AUTO_FIX)
+
+    if not auto_fix_actions:
+        print("\n✅ No auto-fixable errors found")
+        return 0
+
+    print(f"\n🔧 Applying {len(auto_fix_actions)} auto-fix action(s)...")
+
+    import subprocess
+
+    success_count = 0
+    fail_count = 0
+
+    for i, action in enumerate(auto_fix_actions, 1):
+        print(f"\n[{i}/{len(auto_fix_actions)}] {action.description}")
+
+        # Run each command
+        for cmd in action.commands:
+            if verbose:
+                print(f"  Running: {cmd}")
+
+            try:
+                result = subprocess.run(
+                    cmd,
+                    check=False,
+                    shell=True,
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                )
+
+                if result.returncode == 0:
+                    action.status = "completed"
+                    if verbose:
+                        print(f"  ✅ Success: {cmd}")
+                else:
+                    action.status = "failed"
+                    action.error_message = result.stderr or result.stdout
+                    print(f"  ❌ Failed: {cmd}")
+                    if verbose and result.stderr:
+                        print(f"     {result.stderr}")
+                    fail_count += 1
+                    break  # Stop on first failure for this action
+
+            except subprocess.TimeoutExpired:
+                action.status = "failed"
+                action.error_message = "Command timed out"
+                print(f"  ❌ Timeout: {cmd}")
+                fail_count += 1
+                break
+
+            except Exception as e:
+                action.status = "failed"
+                action.error_message = str(e)
+                print(f"  ❌ Error: {e}")
+                fail_count += 1
+                break
+
+        if action.status == "completed":
+            success_count += 1
+
+    # Summary
+    print("\n📊 Auto-fix Results:")
+    print(f"  ✅ Successful: {success_count}")
+    print(f"  ❌ Failed: {fail_count}")
+
+    return 0 if fail_count == 0 else 1
+
+
+def _create_prs(report, verbose: bool) -> int:
+    """Create PRs for agent improvements.
+
+    Args:
+        report: Postmortem report
+        verbose: Show detailed output
+
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    from claude_mpm.services.analysis import ActionType
+
+    pr_actions = report.get_actions_by_type(ActionType.CREATE_PR)
+
+    if not pr_actions:
+        print("\n✅ No PR actions needed")
+        return 0
+
+    print(f"\n🤖 Creating {len(pr_actions)} PR(s) for agent improvements...")
+
+    # Check if we're in the agent cache git repo
+    agent_cache_path = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+
+    if not agent_cache_path.exists():
+        print(f"❌ Agent cache not found at: {agent_cache_path}")
+        print("   Run 'claude-mpm agents sync' first")
+        return 2
+
+    success_count = 0
+    fail_count = 0
+
+    for i, action in enumerate(pr_actions, 1):
+        print(f"\n[{i}/{len(pr_actions)}] {action.description}")
+
+        try:
+            # Check if file is in agent cache
+            analysis = action.error_analysis
+            if not analysis.affected_file:
+                print("  ⚠️  Cannot determine affected file, skipping")
+                action.status = "failed"
+                action.error_message = "No affected file identified"
+                fail_count += 1
+                continue
+
+            # For MVP, print PR template instead of actually creating
+            # Full implementation would use GitHub CLI or API
+            print("  📝 PR Template Generated:")
+            print(f"     Branch: {action.pr_branch}")
+            print(f"     Title: {action.pr_title}")
+
+            if verbose:
+                print("\n--- PR Body ---")
+                print(action.pr_body)
+                print("--- End PR Body ---\n")
+
+            print("\n  ℹ️  To create PR manually:")
+            print(f"     cd {agent_cache_path}")
+            print(f"     git checkout -b {action.pr_branch}")
+            print(f"     # Make your changes to {analysis.affected_file}")
+            print(f"     git add {analysis.affected_file}")
+            print(f'     git commit -m "{action.pr_title}"')
+            print(f"     git push origin {action.pr_branch}")
+            print(
+                f'     gh pr create --title "{action.pr_title}" --body-file pr_body.md'
+            )
+
+            action.status = "completed"
+            success_count += 1
+
+        except Exception as e:
+            logger.error(f"Failed to create PR: {e}")
+            print(f"  ❌ Error: {e}")
+            action.status = "failed"
+            action.error_message = str(e)
+            fail_count += 1
+
+    # Summary
+    print("\n📊 PR Creation Results:")
+    print(f"  ✅ Templates generated: {success_count}")
+    print(f"  ❌ Failed: {fail_count}")
+
+    return 0 if fail_count == 0 else 1
+
+
+# Optional: Standalone execution for testing
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Claude MPM Postmortem Analysis")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--auto-fix", action="store_true")
+    parser.add_argument("--create-prs", action="store_true")
+    parser.add_argument("--session-id", type=str)
+    parser.add_argument(
+        "--format", choices=["terminal", "json", "markdown"], default="terminal"
+    )
+    parser.add_argument("--output", "-o", type=Path)
+    parser.add_argument("--verbose", "-v", action="store_true")
+    parser.add_argument("--no-color", action="store_true")
+
+    args = parser.parse_args()
+
+    sys.exit(postmortem_command(args))