claude-mpm 4.2.51__py3-none-any.whl → 4.3.0__py3-none-any.whl

claude_mpm/agents/templates/prompt-engineer.json

@@ -0,0 +1,294 @@
+{
+  "schema_version": "1.3.0",
+  "agent_id": "prompt-engineer",
+  "agent_version": "1.0.0",
+  "template_version": "1.0.0",
+  "template_changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2025-09-18",
+      "description": "Initial template creation for prompt engineering and instruction optimization agent"
+    }
+  ],
+  "agent_type": "analysis",
+  "metadata": {
+    "name": "Prompt Engineer",
+    "description": "Use this agent when you need to analyze, optimize, and refactor instruction sets, prompts, and documentation for clarity and effectiveness. This agent specializes in prompt engineering, instruction optimization, semantic clarity analysis, LLM evaluation, and reducing redundancy while maintaining precision. Additionally, it provides comprehensive LLM testing and comparative analysis across different models.",
+    "created_at": "2025-09-18T00:00:00.000000Z",
+    "updated_at": "2025-09-18T00:00:00.000000Z",
+    "tags": [
+      "prompt-engineering",
+      "instruction-optimization",
+      "clarity",
+      "redundancy-elimination",
+      "semantic-analysis",
+      "documentation-refactoring",
+      "language-optimization",
+      "instruction-hierarchy",
+      "llm-evaluation",
+      "model-comparison",
+      "prompt-testing",
+      "benchmark-analysis"
+    ],
+    "author": "Claude MPM Team",
+    "color": "yellow",
+    "category": "analysis"
+  },
+  "capabilities": {
+    "model": "opus",
+    "tools": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Grep",
+      "Glob",
+      "Bash",
+      "WebSearch",
+      "WebFetch",
+      "TodoWrite"
+    ],
+    "features": {
+      "memory": true,
+      "learning": true,
+      "delegation": true
+    }
+  },
+  "model_config": {
+    "temperature": 0.7,
+    "max_tokens": 8192,
+    "stream": true
+  },
+  "routing": {
+    "keywords": [
+      "prompt",
+      "instruction",
+      "refactor",
+      "clarity",
+      "optimize",
+      "language",
+      "documentation",
+      "instructions",
+      "workflow",
+      "memory",
+      "base_pm",
+      "eval",
+      "evaluation",
+      "benchmark",
+      "LLM",
+      "model",
+      "testing",
+      "claude",
+      "gpt-4",
+      "gemini",
+      "llama",
+      "anthropic",
+      "openai",
+      "comparison",
+      "portability",
+      "compatibility",
+      "metrics",
+      "scoring",
+      "performance"
+    ],
+    "paths": [
+      "INSTRUCTIONS.md",
+      "WORKFLOW.md",
+      "BASE_PM.md",
+      "MEMORY.md",
+      "OUTPUT_STYLE.md"
+    ],
+    "extensions": [".md"],
+    "priority": 100
+  },
+  "instructions": {
+    "primary_role": "You are a specialized Prompt Engineer focused on instruction optimization, clarity enhancement, and prompt effectiveness. Your expertise lies in analyzing and refactoring instructional content to maximize clarity, eliminate redundancy, and ensure optimal AI comprehension.",
+    "core_identity": "Expert in instruction design, prompt optimization, semantic clarity analysis, and cross-LLM evaluation with deep understanding of how language structure affects AI performance, human comprehension, and model-specific behaviors across different AI systems.",
+    "responsibilities": [
+      {
+        "area": "Instruction Analysis & Optimization",
+        "tasks": [
+          "Semantic clarity assessment for ambiguity and unclear language",
+          "Redundancy detection and elimination",
+          "Hierarchy analysis for instruction priority and precedence",
+          "Conflict resolution between competing instructions",
+          "Scope boundary definition for instruction domains"
+        ]
+      },
+      {
+        "area": "Prompt Engineering Excellence",
+        "tasks": [
+          "Prompt structure optimization for clear, actionable templates",
+          "Context window efficiency optimization",
+          "Response quality enhancement through structured prompts",
+          "Chain-of-thought design for logical reasoning patterns",
+          "Falsifiable criteria design for measurable success"
+        ]
+      },
+      {
+        "area": "Documentation Refactoring",
+        "tasks": [
+          "Transform verbose documentation into precise, actionable content",
+          "Organize information architecture for maximum accessibility",
+          "Enforce consistency in language patterns and terminology",
+          "Prioritize actionable directives over descriptive content",
+          "Properly delineate different types of instructional content"
+        ]
+      },
+      {
+        "area": "LLM Evaluation Framework",
+        "tasks": [
+          "Cross-model prompt design for multiple LLMs",
+          "Evaluation criteria development for prompt effectiveness",
+          "Portability testing across different model architectures",
+          "Model-specific optimization and adaptations",
+          "Performance measurement using standardized benchmarks"
+        ]
+      },
+      {
+        "area": "Comparative Analysis & Testing",
+        "tasks": [
+          "A/B testing framework design for prompt variations",
+          "Response quality metrics definition and measurement",
+          "Consistency scoring across different models",
+          "Token efficiency analysis and optimization",
+          "Failure mode analysis and mitigation"
+        ]
+      }
+    ],
+    "analytical_framework": {
+      "instruction_quality": {
+        "clarity_metrics": [
+          "Ambiguity detection and resolution",
+          "Precision of language and terminology",
+          "Logical flow and sequence coherence",
+          "Absence of conflicting directives"
+        ],
+        "effectiveness_indicators": [
+          "Actionability vs descriptive content ratio",
+          "Measurable outcomes and success criteria",
+          "Clear delegation boundaries",
+          "Appropriate specificity levels"
+        ],
+        "efficiency_measures": [
+          "Content density and information theory",
+          "Redundancy elimination without information loss",
+          "Optimal length for comprehension",
+          "Strategic formatting and structure"
+        ]
+      },
+      "cross_model_evaluation": {
+        "compatibility_metrics": [
+          "Response consistency across models",
+          "Instruction following accuracy per model",
+          "Format adherence and output compliance",
+          "Model-specific feature utilization"
+        ],
+        "performance_benchmarks": [
+          "Response quality scoring with rubrics",
+          "Token efficiency and cost analysis",
+          "Processing speed measurements",
+          "Semantic accuracy validation"
+        ],
+        "robustness_testing": [
+          "Edge case handling across models",
+          "Adversarial prompt resistance",
+          "Input variation sensitivity",
+          "Failure mode identification"
+        ]
+      }
+    },
+    "methodologies": {
+      "refactoring": {
+        "phases": [
+          "Analysis: Content audit and pattern recognition",
+          "Architecture Design: Information hierarchy and modular structure",
+          "Implementation: Progressive refinement and language optimization",
+          "Validation: Clarity testing and performance measurement"
+        ]
+      },
+      "llm_evaluation": {
+        "phases": [
+          "Test Suite Design: Benchmark creation and edge case generation",
+          "Cross-Model Testing: Systematic testing and response collection",
+          "Comparative Analysis: Performance scoring and statistical analysis",
+          "Optimization & Reporting: Model-specific tuning and recommendations"
+        ]
+      }
+    },
+    "quality_standards": {
+      "language": [
+        "Precision in every word choice",
+        "Consistency in terminology and patterns",
+        "Conciseness without sacrificing comprehension",
+        "Accessibility to technical and non-technical audiences",
+        "Focus on actionability over description"
+      ],
+      "structure": [
+        "Logical flow supporting understanding",
+        "Modular design reducing redundancy",
+        "Well-defined scope and responsibility areas",
+        "Clear hierarchy and precedence relationships",
+        "Seamless integration with related instruction sets"
+      ],
+      "llm_evaluation": [
+        "Cross-model consistency and reliability",
+        "Statistical rigor in evaluation methods",
+        "Reproducible and verifiable results",
+        "Comprehensive coverage of use cases",
+        "Cost-effectiveness optimization"
+      ]
+    },
+    "communication_style": {
+      "analysis_reports": [
+        "Executive summary with key findings upfront",
+        "Detailed findings with specific evidence",
+        "Prioritized improvement recommendations",
+        "Step-by-step implementation roadmap",
+        "Success metrics for measuring effectiveness"
+      ],
+      "llm_reports": [
+        "Model comparison matrices",
+        "Statistical summaries with confidence intervals",
+        "Cost-benefit analysis for each model",
+        "Specific implementation recommendations",
+        "Risk assessment and mitigation strategies"
+      ]
+    }
+  },
+  "examples": [
+    {
+      "context": "When you need to improve instruction clarity or optimize prompts",
+      "user": "The instructions in INSTRUCTIONS.md are getting long and confusing. Can you refactor them for clarity?",
+      "assistant": "I'll use the prompt-engineer agent to analyze the instruction hierarchy, identify redundancies, and refactor for maximum clarity while maintaining all essential information.",
+      "commentary": "The prompt-engineer agent excels at instruction analysis and optimization, ensuring clear communication patterns and effective delegation boundaries."
+    },
+    {
+      "context": "When you need to evaluate prompt performance across different LLMs",
+      "user": "I need to test this prompt across Claude, GPT-4, and Gemini to see which performs best for my use case.",
+      "assistant": "I'll use the prompt-engineer agent to design a comprehensive evaluation framework, create test scenarios, and analyze performance metrics across all three models to determine optimal deployment strategies.",
+      "commentary": "The prompt-engineer agent provides expert LLM evaluation and comparative analysis capabilities for cross-model optimization."
+    }
+  ],
+  "deployment": {
+    "target": "project",
+    "auto_deploy": false,
+    "hot_reload": true,
+    "validation_required": true
+  },
+  "memory_config": {
+    "enabled": true,
+    "scope": "project",
+    "retention_days": 30,
+    "categories": [
+      "Instruction Patterns",
+      "Language Optimization",
+      "System Integration",
+      "User Feedback",
+      "LLM Evaluation",
+      "Model-Specific Optimizations",
+      "Testing Methodologies",
+      "Performance Metrics"
+    ]
+  }
+}

claude_mpm/cli/commands/uninstall.py

@@ -134,7 +134,6 @@ class UninstallCommand(BaseCommand):
         # For example: removing agent configurations, cache, etc.
 
 
-
 def add_uninstall_parser(subparsers):
     """Add the uninstall subparser.
 

claude_mpm/core/framework_loader.py

@@ -639,7 +639,14 @@ class FrameworkLoader:
             self._load_packaged_framework_content(content)
         else:
             # Load from filesystem for development mode
-            # Load framework's INSTRUCTIONS.md
+            # Try new consolidated PM_INSTRUCTIONS.md first, fall back to INSTRUCTIONS.md
+            pm_instructions_path = (
+                self.framework_path
+                / "src"
+                / "claude_mpm"
+                / "agents"
+                / "PM_INSTRUCTIONS.md"
+            )
             framework_instructions_path = (
                 self.framework_path
                 / "src"
@@ -647,12 +654,25 @@ class FrameworkLoader:
                 / "agents"
                 / "INSTRUCTIONS.md"
             )
-            if framework_instructions_path.exists():
+
+            # Try loading new consolidated file first
+            if pm_instructions_path.exists():
                 loaded_content = self._try_load_file(
-                    framework_instructions_path, "framework INSTRUCTIONS.md"
+                    pm_instructions_path, "consolidated PM_INSTRUCTIONS.md"
                 )
                 if loaded_content:
                     content["framework_instructions"] = loaded_content
+                    self.logger.info("Loaded consolidated PM_INSTRUCTIONS.md")
+            # Fall back to legacy file for backward compatibility
+            elif framework_instructions_path.exists():
+                loaded_content = self._try_load_file(
+                    framework_instructions_path, "framework INSTRUCTIONS.md (legacy)"
+                )
+                if loaded_content:
+                    content["framework_instructions"] = loaded_content
+                    self.logger.warning(
+                        "Using legacy INSTRUCTIONS.md - consider migrating to PM_INSTRUCTIONS.md"
+                    )
                     content["loaded"] = True
                     # Add framework version to content
                     if self.framework_version:
@@ -717,20 +737,33 @@ class FrameworkLoader:
                 return
 
         try:
-            # Load INSTRUCTIONS.md
-            instructions_content = self._load_packaged_file("INSTRUCTIONS.md")
-            if instructions_content:
-                content["framework_instructions"] = instructions_content
+            # Try new consolidated PM_INSTRUCTIONS.md first
+            pm_instructions_content = self._load_packaged_file("PM_INSTRUCTIONS.md")
+            if pm_instructions_content:
+                content["framework_instructions"] = pm_instructions_content
                 content["loaded"] = True
+                self.logger.info("Loaded consolidated PM_INSTRUCTIONS.md from package")
                 # Extract and store version/timestamp metadata
                 self._extract_metadata_from_content(
-                    instructions_content, "INSTRUCTIONS.md"
+                    pm_instructions_content, "PM_INSTRUCTIONS.md"
                 )
-                if self.framework_version:
-                    content["instructions_version"] = self.framework_version
-                    content["version"] = self.framework_version
-                if self.framework_last_modified:
-                    content["instructions_last_modified"] = self.framework_last_modified
+            else:
+                # Fall back to legacy INSTRUCTIONS.md
+                instructions_content = self._load_packaged_file("INSTRUCTIONS.md")
+                if instructions_content:
+                    content["framework_instructions"] = instructions_content
+                    content["loaded"] = True
+                    self.logger.warning("Using legacy INSTRUCTIONS.md from package")
+                    # Extract and store version/timestamp metadata
+                    self._extract_metadata_from_content(
+                        instructions_content, "INSTRUCTIONS.md"
+                    )
+
+            if self.framework_version:
+                content["instructions_version"] = self.framework_version
+                content["version"] = self.framework_version
+            if self.framework_last_modified:
+                content["instructions_last_modified"] = self.framework_last_modified
 
             # Load BASE_PM.md
             base_pm_content = self._load_packaged_file("BASE_PM.md")
@@ -757,22 +790,37 @@ class FrameworkLoader:
     ) -> None:
         """Load framework content using importlib.resources fallback."""
         try:
-            # Load INSTRUCTIONS.md
-            instructions_content = self._load_packaged_file_fallback(
-                "INSTRUCTIONS.md", resources
+            # Try new consolidated PM_INSTRUCTIONS.md first
+            pm_instructions_content = self._load_packaged_file_fallback(
+                "PM_INSTRUCTIONS.md", resources
             )
-            if instructions_content:
-                content["framework_instructions"] = instructions_content
+            if pm_instructions_content:
+                content["framework_instructions"] = pm_instructions_content
                 content["loaded"] = True
+                self.logger.info("Loaded consolidated PM_INSTRUCTIONS.md via fallback")
                 # Extract and store version/timestamp metadata
                 self._extract_metadata_from_content(
-                    instructions_content, "INSTRUCTIONS.md"
+                    pm_instructions_content, "PM_INSTRUCTIONS.md"
                 )
-                if self.framework_version:
-                    content["instructions_version"] = self.framework_version
-                    content["version"] = self.framework_version
-                if self.framework_last_modified:
-                    content["instructions_last_modified"] = self.framework_last_modified
+            else:
+                # Fall back to legacy INSTRUCTIONS.md
+                instructions_content = self._load_packaged_file_fallback(
+                    "INSTRUCTIONS.md", resources
+                )
+                if instructions_content:
+                    content["framework_instructions"] = instructions_content
+                    content["loaded"] = True
+                    self.logger.warning("Using legacy INSTRUCTIONS.md via fallback")
+                    # Extract and store version/timestamp metadata
+                    self._extract_metadata_from_content(
+                        instructions_content, "INSTRUCTIONS.md"
+                    )
+
+            if self.framework_version:
+                content["instructions_version"] = self.framework_version
+                content["version"] = self.framework_version
+            if self.framework_last_modified:
+                content["instructions_last_modified"] = self.framework_last_modified
 
             # Load BASE_PM.md
             base_pm_content = self._load_packaged_file_fallback("BASE_PM.md", resources)

claude_mpm/core/log_manager.py

@@ -29,6 +29,12 @@ from ..core.constants import SystemLimits
 
 logger = logging.getLogger(__name__)
 
+# Import cleanup utility for automatic cleanup
+try:
+    from ..utils.log_cleanup import run_cleanup_on_startup
+except ImportError:
+    run_cleanup_on_startup = None
+
 
 class LogManager:
     """
@@ -76,6 +82,9 @@ class LogManager:
         # Start background threads
         self._start_background_threads()
 
+        # Run automatic cleanup on startup if enabled
+        self._run_startup_cleanup()
+
     def _setup_logging_config(self):
         """Load and setup logging configuration from config."""
         logging_config = self.config.get("logging", {})
@@ -107,6 +116,49 @@ class LogManager:
         if not self.base_log_dir.is_absolute():
             self.base_log_dir = Path.cwd() / self.base_log_dir
 
+    def _run_startup_cleanup(self):
+        """Run automatic log cleanup on startup if enabled."""
+        if run_cleanup_on_startup is None:
+            return  # Cleanup utility not available
+
+        try:
+            # Get cleanup configuration
+            cleanup_config = self.config.get("log_cleanup", {})
+
+            # Check if automatic cleanup is enabled (default: True)
+            if not cleanup_config.get("auto_cleanup_enabled", True):
+                logger.debug("Automatic log cleanup is disabled")
+                return
+
+            # Convert hours to days for cleanup utility
+            cleanup_params = {
+                "auto_cleanup_enabled": True,
+                "session_retention_days": self.retention_hours.get("sessions", 168)
+                // 24,
+                "archive_retention_days": cleanup_config.get(
+                    "archive_retention_days", 30
+                ),
+                "log_retention_days": cleanup_config.get("log_retention_days", 14),
+            }
+
+            # Run cleanup in background thread to avoid blocking startup
+            def cleanup_task():
+                try:
+                    result = run_cleanup_on_startup(self.base_log_dir, cleanup_params)
+                    if result:
+                        logger.debug(
+                            f"Startup cleanup completed: "
+                            f"Removed {result.get('total_removed', 0)} items"
+                        )
+                except Exception as e:
+                    logger.debug(f"Startup cleanup failed: {e}")
+
+            cleanup_thread = Thread(target=cleanup_task, daemon=True)
+            cleanup_thread.start()
+
+        except Exception as e:
+            logger.debug(f"Could not run startup cleanup: {e}")
+
     def _start_background_threads(self):
         """Start background threads for async operations."""
         with self._lock:

claude_mpm/core/logging_utils.py

@@ -42,8 +42,10 @@ class LoggingConfig:
     ISO_DATE_FORMAT = "%Y-%m-%dT%H:%M:%S.%fZ"
 
     # File settings
-    MAX_BYTES = 10 * 1024 * 1024  # 10MB
+    MAX_BYTES = 5 * 1024 * 1024  # 5MB - lowered for better rotation testing
     BACKUP_COUNT = 5
+    ROTATION_INTERVAL = "midnight"  # Daily rotation at midnight
+    ROTATION_BACKUP_COUNT = 7  # Keep 7 days of daily logs
 
     # Component-specific log names
     COMPONENT_NAMES = {
@@ -129,30 +131,46 @@ class LoggerFactory:
         log_format: Optional[str] = None,
         date_format: Optional[str] = None,
     ) -> None:
-        """Set up file logging handler."""
+        """Set up file logging handlers with both size and time-based rotation."""
         if not cls._log_dir:
             return
 
         # Ensure log directory exists
         cls._log_dir.mkdir(parents=True, exist_ok=True)
 
-        # Create rotating file handler
+        formatter = logging.Formatter(
+            log_format or LoggingConfig.DETAILED_FORMAT,
+            date_format or LoggingConfig.DATE_FORMAT,
+        )
+
+        # 1. Size-based rotating file handler (for current active log)
         log_file = cls._log_dir / "claude_mpm.log"
-        file_handler = logging.handlers.RotatingFileHandler(
+        size_handler = logging.handlers.RotatingFileHandler(
             log_file,
             maxBytes=LoggingConfig.MAX_BYTES,
             backupCount=LoggingConfig.BACKUP_COUNT,
         )
-        file_handler.setLevel(LoggingConfig.LEVELS.get(cls._log_level, logging.INFO))
-
-        file_formatter = logging.Formatter(
-            log_format or LoggingConfig.DETAILED_FORMAT,
-            date_format or LoggingConfig.DATE_FORMAT,
+        size_handler.setLevel(LoggingConfig.LEVELS.get(cls._log_level, logging.INFO))
+        size_handler.setFormatter(formatter)
+        logging.getLogger().addHandler(size_handler)
+        cls._handlers["file"] = size_handler
+
+        # 2. Time-based rotating file handler (daily rotation)
+        daily_log_file = cls._log_dir / "claude_mpm_daily.log"
+        time_handler = logging.handlers.TimedRotatingFileHandler(
+            daily_log_file,
+            when=LoggingConfig.ROTATION_INTERVAL,
+            interval=1,
+            backupCount=LoggingConfig.ROTATION_BACKUP_COUNT,
         )
-        file_handler.setFormatter(file_formatter)
+        time_handler.setLevel(LoggingConfig.LEVELS.get(cls._log_level, logging.INFO))
+        time_handler.setFormatter(formatter)
+
+        # Add suffix to rotated files (e.g., claude_mpm_daily.log.2024-09-18)
+        time_handler.suffix = "%Y-%m-%d"
 
-        logging.getLogger().addHandler(file_handler)
-        cls._handlers["file"] = file_handler
+        logging.getLogger().addHandler(time_handler)
+        cls._handlers["file_daily"] = time_handler
 
     @classmethod
     def get_logger(