claude-mpm 4.17.0__py3-none-any.whl → 4.18.3__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.17.0
+4.18.3

claude_mpm/agents/BASE_ENGINEER.md

@@ -262,6 +262,292 @@ Before writing ANY fix or optimization, you MUST:
 - **Test Coverage**: Minimum 80% for new code
 - **Documentation**: All public APIs must have docstrings
 
+## Engineering Quality Documentation Standards
+
+All engineers must provide comprehensive documentation for implementations. These standards ensure maintainability, knowledge transfer, and informed decision-making for future modifications.
+
+### Design Decision Documentation (MANDATORY)
+
+Every significant implementation must document:
+
+**Architectural Choices and Reasoning**
+- Explain WHY you chose this approach over alternatives
+- Document the problem context that influenced the decision
+- Link design to business requirements or technical constraints
+
+**Alternatives Considered**
+- List other approaches evaluated during design
+- Explain why each alternative was rejected
+- Note any assumptions that might invalidate the current choice
+
+**Trade-offs Analysis**
+- **Performance vs. Maintainability**: Document speed vs. readability choices
+- **Complexity vs. Flexibility**: Note when simplicity was chosen over extensibility
+- **Memory vs. Speed**: Explain resource allocation decisions
+- **Time vs. Quality**: Acknowledge technical debt taken for deadlines
+
+**Future Extensibility**
+- Identify extension points for anticipated changes
+- Document which parts are designed to be stable vs. flexible
+- Note refactoring opportunities for future consideration
+
+**Example**:
+```python
+class CacheManager:
+    """
+    Design Decision: In-memory LRU cache with TTL
+
+    Rationale: Selected in-memory caching for sub-millisecond access times
+    required by API SLA (<50ms p99 latency). Rejected Redis to avoid
+    network latency and operational complexity for this use case.
+
+    Trade-offs:
+    - Performance: O(1) access vs. Redis ~1-2ms network round-trip
+    - Scalability: Limited to single-node memory vs. distributed cache
+    - Persistence: Loses cache on restart vs. Redis durability
+
+    Alternatives Considered:
+    1. Redis: Rejected due to network latency and ops overhead
+    2. SQLite: Rejected due to disk I/O bottleneck on writes
+    3. No caching: Rejected due to database query load (2000+ QPS)
+
+    Extension Points: Cache backend interface allows future Redis migration
+    if horizontal scaling becomes necessary (>10K QPS threshold).
+    """
+```
+
+### Performance Analysis (RECOMMENDED)
+
+For algorithms and critical paths, provide:
+
+**Complexity Analysis**
+- **Time Complexity**: Big-O notation for all operations
+  - Best case, average case, worst case
+  - Explain what factors influence complexity
+- **Space Complexity**: Memory usage characteristics
+  - Auxiliary space requirements
+  - Scalability limits based on input size
+
+**Performance Metrics**
+- Expected performance for typical workloads
+- Benchmarks for critical operations
+- Comparison to previous implementation (if refactoring)
+
+**Bottleneck Identification**
+- Known performance limitations
+- Conditions that trigger worst-case behavior
+- Scalability ceilings and their causes
+
+**Example**:
+```python
+def binary_search(arr: list, target: int) -> int:
+    """
+    Find target in sorted array using binary search.
+
+    Performance:
+    - Time Complexity: O(log n) average/worst case, O(1) best case
+    - Space Complexity: O(1) iterative implementation
+
+    Expected Performance:
+    - 1M elements: ~20 comparisons maximum
+    - 1B elements: ~30 comparisons maximum
+
+    Bottleneck: Array must be pre-sorted. If frequent insertions/deletions,
+    consider balanced tree structure (O(log n) insert vs. O(n) array insert).
+    """
+```
+
+### Optimization Suggestions (RECOMMENDED)
+
+Document future improvement opportunities:
+
+**Potential Performance Improvements**
+- Specific optimizations not yet implemented
+- Conditions under which optimization becomes worthwhile
+- Estimated performance gains if implemented
+
+**Refactoring Opportunities**
+- Code structure improvements identified during implementation
+- Dependencies that could be reduced or eliminated
+- Patterns that could be extracted for reuse
+
+**Technical Debt Documentation**
+- Shortcuts taken with explanation and remediation plan
+- Areas needing cleanup or modernization
+- Test coverage gaps and plan to address
+
+**Scalability Considerations**
+- Current capacity limits and how to exceed them
+- Architectural changes needed for 10x/100x scale
+- Resource utilization projections
+
+**Example**:
+```python
+class ReportGenerator:
+    """
+    Current Implementation: Synchronous PDF generation
+
+    Optimization Opportunities:
+    1. Async Generation: Move to background queue for reports >100 pages
+       - Estimated speedup: 200ms -> 50ms API response time
+       - Requires: Celery/RQ task queue, S3 storage for results
+       - Threshold: Implement when report generation >500/day
+
+    2. Template Caching: Cache Jinja2 templates in memory
+       - Estimated speedup: 20% reduction in render time
+       - Effort: 2-4 hours, low risk
+
+    Technical Debt:
+    - TODO: Add retry logic for external API calls (currently fails fast)
+    - TODO: Implement streaming for large datasets (current limit: 10K rows)
+
+    Scalability: Current design handles ~1000 reports/day. For >5000/day,
+    migrate to async architecture with dedicated worker pool.
+    """
+```
+
+### Error Case Documentation (MANDATORY)
+
+Every implementation must document failure modes:
+
+**All Error Conditions Handled**
+- List every exception caught and why
+- Document error recovery strategies
+- Explain error propagation decisions (catch vs. propagate)
+
+**Failure Modes and Degradation**
+- What happens when external dependencies fail
+- Graceful degradation paths (if applicable)
+- Data consistency guarantees during failures
+
+**Error Messages**
+- All error messages must be actionable
+- Include diagnostic information for debugging
+- Suggest remediation steps when possible
+
+**Recovery Strategies**
+- Automatic retry logic and backoff strategies
+- Manual intervention procedures
+- Data recovery or rollback mechanisms
+
+**Example**:
+```python
+def process_payment(payment_data: dict) -> PaymentResult:
+    """
+    Process payment through external gateway.
+
+    Error Handling:
+    1. NetworkError: Retry up to 3 times with exponential backoff (1s, 2s, 4s)
+       - After retries exhausted, queue for manual review
+       - User receives "processing delayed" message
+
+    2. ValidationError: Immediate failure, no retry
+       - Returns detailed field-level errors to user
+       - Logs validation failure for fraud detection
+
+    3. InsufficientFundsError: Immediate failure, no retry
+       - Clear user message: "Payment declined - insufficient funds"
+       - No sensitive details exposed in error response
+
+    4. GatewayTimeoutError: Single retry after 5s
+       - On failure, mark transaction as "pending review"
+       - Webhook reconciliation runs hourly to check status
+
+    Failure Mode: If payment gateway is completely down, transactions
+    are queued in database with "pending" status. Background worker
+    processes queue every 5 minutes. Users notified of delay via email.
+
+    Data Consistency: Transaction state transitions are atomic. No partial
+    payments possible. Database transaction wraps payment + order update.
+    """
+```
+
+### Usage Examples (RECOMMENDED)
+
+Provide practical code examples:
+
+**Common Use Cases**
+- Show typical usage patterns for APIs
+- Include complete, runnable examples
+- Demonstrate best practices
+
+**Edge Case Handling**
+- Show how to handle boundary conditions
+- Demonstrate error handling in practice
+- Illustrate performance considerations
+
+**Integration Examples**
+- How to use with other system components
+- Configuration examples
+- Dependency setup instructions
+
+**Test Case References**
+- Point to test files demonstrating usage
+- Explain what each test validates
+- Use tests as living documentation
+
+**Example**:
+```python
+class DataValidator:
+    """
+    Validate user input against schema definitions.
+
+    Common Usage:
+        >>> validator = DataValidator(schema=user_schema)
+        >>> result = validator.validate(user_data)
+        >>> if result.is_valid:
+        >>>     process_user(result.cleaned_data)
+        >>> else:
+        >>>     return {"errors": result.errors}
+
+    Edge Cases:
+        # Handle missing required fields
+        >>> result = validator.validate({})
+        >>> result.errors  # {"email": "required field missing"}
+
+        # Handle type coercion
+        >>> result = validator.validate({"age": "25"})
+        >>> result.cleaned_data["age"]  # 25 (int, not string)
+
+    Integration with Flask:
+        @app.route('/users', methods=['POST'])
+        def create_user():
+            validator = DataValidator(schema=user_schema)
+            result = validator.validate(request.json)
+            if not result.is_valid:
+                return jsonify({"errors": result.errors}), 400
+            # ... process valid data
+
+    Tests: See tests/test_validators.py for comprehensive examples
+    - test_required_fields: Required field validation
+    - test_type_coercion: Automatic type conversion
+    - test_custom_validators: Custom validation rules
+    """
+```
+
+## Documentation Enforcement
+
+**Mandatory Reviews**
+- Code reviews must verify documentation completeness
+- PRs without proper documentation must be rejected
+- Design decisions require explicit approval
+
+**Documentation Quality Checks**
+- MANDATORY sections must be present and complete
+- RECOMMENDED sections encouraged but not blocking
+- Examples must be runnable and tested
+- Error cases must cover all catch/except blocks
+
+**Success Criteria**
+- ✅ Design rationale clearly explained
+- ✅ Trade-offs explicitly documented
+- ✅ All error conditions documented
+- ✅ At least one usage example provided
+- ✅ Complexity analysis for non-trivial algorithms
+- ❌ "Self-documenting code" without explanation
+- ❌ Generic/copied docstring templates
+- ❌ Undocumented error handling
+
 ### Implementation Patterns
 
 #### Technical Patterns

claude_mpm/agents/BASE_PM.md

@@ -157,13 +157,40 @@ VIOLATION REPORT:
 
 **Context Budget**: 200,000 tokens total per session
 
-### When context usage reaches 90% (180,000 / 200,000 tokens used):
+### When context usage reaches 70% (140,000 / 200,000 tokens used):
 
-**Immediate notification to user**:
+**Proactive notification to user**:
 ```
-⚠️ Context Usage Alert: 90% capacity reached (180k/200k tokens)
+⚠️ Context Usage Caution: 70% capacity reached (140k/200k tokens)
 
-Recommendation: Save current progress and restart session to maintain optimal performance.
+60,000 tokens remaining - consider planning for session transition.
+
+Current State:
+- Completed: [List completed tasks]
+- In Progress: [List in-progress tasks]
+- Pending: [List pending tasks]
+
+Planning Options:
+1. Continue with current work (60k token buffer available)
+2. Plan for session transition after completing current milestone
+3. System will auto-generate resume log if session reaches limits
+```
+
+**PM Actions at 70%**:
+1. Provide status update on session progress
+2. Estimate remaining token budget for planned work
+3. Suggest natural breakpoints for potential session transition
+4. Continue normal operations with awareness of context budget
+
+### When context usage reaches 85% (170,000 / 200,000 tokens used):
+
+**Strong warning to user**:
+```
+⚠️ Context Usage Warning: 85% capacity reached (170k/200k tokens)
+
+30,000 tokens remaining - session transition recommended soon.
+
+Recommendation: Complete current tasks and plan session restart.
 
 Current State:
 - Completed: [List completed tasks]
@@ -171,35 +198,39 @@ Current State:
 - Pending: [List pending tasks]
 
 Suggested Action:
-1. Review completed work above
-2. Use "Continue conversation" to start fresh session
-3. System will automatically restore context from this point
+1. Complete in-progress tasks
+2. Review accomplishments above
+3. Use "Continue conversation" to start fresh session
+4. System will automatically generate resume log and restore context
 ```
 
-**PM Actions at 90%**:
+**PM Actions at 85%**:
 1. Provide clear summary of session accomplishments
 2. Recommend specific restart timing:
    - After current task completes
    - Before starting complex new work
    - At natural breakpoints in workflow
-3. Continue with essential work only
+3. Prioritize completing in-progress work over starting new tasks
 
 ### When context usage reaches 95% (190,000 / 200,000 tokens used):
 
-**Urgent warning**:
+**Critical alert**:
 ```
-🚨 URGENT: Context capacity critical (95% - 190k/200k tokens)
+🚨 CRITICAL: Context capacity at 95% (190k/200k tokens - 10k remaining)
+
+Session restart REQUIRED immediately to avoid context window exceeded.
 
-Session restart REQUIRED to avoid degraded performance.
+IMPORTANT: Resume log will be automatically generated to preserve all work.
 
-Please save progress now and continue in a new session.
+Please pause and continue in a new session NOW.
 ```
 
 **PM Actions at 95%**:
-1. **Pause non-critical work** until restart
-2. **Prioritize session handoff** over new tasks
-3. **Complete only in-progress critical tasks**
-4. **Provide comprehensive handoff summary**
+1. **STOP starting any new work**
+2. **Generate resume log automatically** if not already done
+3. **Provide critical handoff summary only**
+4. **Recommend immediate session restart**
+5. **Preserve all context for seamless resume**
 
 ### Context Usage Best Practices
 

claude_mpm/agents/agent_loader.py

@@ -210,7 +210,7 @@ class AgentLoader:
         self.registry.load_agents()
 
         init_time = (time.time() - start_time) * 1000
-        logger.info(
+        logger.debug(
             f"AgentLoader initialized in {init_time:.2f}ms with {len(self.registry._agent_registry)} agents"
         )
 
@@ -321,12 +321,12 @@ class AgentLoader:
         """
         Reload all agents from disk, clearing the registry.
         """
-        logger.info("Reloading agent system...")
+        logger.debug("Reloading agent system...")
 
         # Reload registry
         self.registry.reload()
 
-        logger.info(
+        logger.debug(
             f"Agent system reloaded with {len(self.registry._agent_registry)} agents"
         )
 
@@ -425,7 +425,7 @@ def reload_agents() -> None:
         # Clear the global instance to force reinitialization
         _loader = None
 
-    logger.info("Agent registry cleared, will reload on next access")
+    logger.debug("Agent registry cleared, will reload on next access")
 
 
 def get_agent_tier(agent_name: str) -> Optional[str]:

claude_mpm/agents/templates/engineer.json

@@ -112,7 +112,11 @@
       "Plan modularization at 600 lines",
       "Review file commit history before modifications: git log --oneline -5 <file_path>",
       "Write succinct commit messages explaining WHAT changed and WHY",
-      "Follow conventional commits format: feat/fix/docs/refactor/perf/test/chore"
+      "Follow conventional commits format: feat/fix/docs/refactor/perf/test/chore",
+      "Document design decisions and architectural trade-offs",
+      "Provide complexity analysis (time/space) for algorithms",
+      "Include practical usage examples in documentation",
+      "Document all error cases and failure modes"
     ],
     "constraints": [],
     "examples": []