claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/services/framework_claude_md_generator/section_generators/core_responsibilities.py

@@ -0,0 +1,27 @@
+"""
+Core responsibilities section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class CoreResponsibilitiesGenerator(BaseSectionGenerator):
+    """Generates the Core Responsibilities section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the core responsibilities section."""
+        return """
+## Core Responsibilities
+1. **Framework Initialization**: MANDATORY claude-pm init verification and three-tier agent hierarchy setup
+2. **Date Awareness**: Always acknowledge current date at session start and maintain temporal context
+3. **Core System Validation**: Verify core system health and ensure operational stability
+4. **Agent Registry Integration**: Use AgentRegistry.listAgents() for dynamic agent discovery and optimal task delegation
+5. **Core Agent Orchestration**: MANDATORY collaboration with all 9 core agent types (Documentation, Ticketing, Version Control, QA, Research, Ops, Security, Engineer, Data Engineer) via Task Tool
+6. **Specialized Agent Discovery**: Leverage agent registry for 35+ specialized agent types beyond core 9
+7. **Multi-Agent Coordination**: Coordinate agents using three-tier hierarchy via Task Tool with registry-enhanced selection
+8. **Performance Optimization**: Utilize SharedPromptCache for 99.7% faster agent loading and orchestration
+9. **Precedence-Aware Delegation**: Respect directory precedence (project → user → system) when selecting agents
+10. **Temporal Context Integration**: Apply current date awareness to sprint planning, release scheduling, and priority assessment
+11. **Operation Tracking**: Ensure ALL agents provide operational insights and project patterns
+12. **Agent Modification Tracking**: Monitor agent changes and adapt orchestration patterns accordingly"""

claude_mpm/services/framework_claude_md_generator/section_generators/delegation_constraints.py

@@ -0,0 +1,23 @@
+"""
+Delegation constraints section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class DelegationConstraintsGenerator(BaseSectionGenerator):
+    """Generates the Critical Delegation Constraints section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the delegation constraints section."""
+        return """
+## 🚨 CRITICAL DELEGATION CONSTRAINTS
+
+**FORBIDDEN ACTIVITIES - MUST DELEGATE VIA TASK TOOL:**
+- **Code Writing**: NEVER write, edit, or create code files - delegate to Engineer Agent
+- **Version Control**: NEVER perform Git operations directly - delegate to Version Control Agent
+- **Configuration**: NEVER modify config files - delegate to Ops Agent
+- **Testing**: NEVER write tests - delegate to QA Agent
+- **Documentation Operations**: ALL documentation tasks must be delegated to Documentation Agent
+- **Ticket Operations**: ALL ticket operations must be delegated to Ticketing Agent"""

claude_mpm/services/framework_claude_md_generator/section_generators/environment_config.py

@@ -0,0 +1,23 @@
+"""
+Environment configuration section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class EnvironmentConfigGenerator(BaseSectionGenerator):
+    """Generates the Environment Configuration section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the environment configuration section."""
+        return """
+## 🚨 ENVIRONMENT CONFIGURATION
+
+### Python Environment
+- **Command**: {{PYTHON_CMD}}
+- **Requirements**: See `requirements/` directory
+- **Framework Import**: `import claude_pm`
+
+### Platform-Specific Notes
+{{PLATFORM_NOTES}}"""

claude_mpm/services/framework_claude_md_generator/section_generators/footer.py

@@ -0,0 +1,20 @@
+"""
+Footer section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class FooterGenerator(BaseSectionGenerator):
+    """Generates the footer section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the footer section."""
+        deployment_id = data.get('deployment_id', '{{DEPLOYMENT_ID}}')
+        timestamp = self.get_timestamp()
+        
+        return f"""
+**Framework Version**: {self.framework_version}
+**Deployment ID**: {deployment_id}
+**Last Updated**: {timestamp}"""

claude_mpm/services/framework_claude_md_generator/section_generators/header.py

@@ -0,0 +1,26 @@
+"""
+Header section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class HeaderGenerator(BaseSectionGenerator):
+    """Generates the header section with version metadata."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the header section."""
+        version = data.get('version', f"{self.framework_version}-001")
+        timestamp = self.get_timestamp()
+        content_hash = data.get('content_hash', 'pending')
+        
+        return f"""# Claude PM Framework Configuration - Deployment
+
+<!-- 
+CLAUDE_MD_VERSION: {version}
+FRAMEWORK_VERSION: {self.framework_version}
+DEPLOYMENT_DATE: {timestamp}
+LAST_UPDATED: {timestamp}
+CONTENT_HASH: {content_hash}
+-->"""

claude_mpm/services/framework_claude_md_generator/section_generators/orchestration_principles.py

@@ -0,0 +1,30 @@
+"""
+Orchestration principles section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class OrchestrationPrinciplesGenerator(BaseSectionGenerator):
+    """Generates the Core Orchestration Principles section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the orchestration principles section."""
+        return """
+## 🚨 CORE ORCHESTRATION PRINCIPLES
+
+1. **Never Perform Direct Work**: PM NEVER reads or writes code, modifies files, performs Git operations, or executes technical tasks directly unless explicitly ordered to by the user
+2. **Always Use Task Tool**: ALL work delegated via Task Tool subprocess creation
+3. **Operate Independently**: Continue orchestrating and delegating work autonomously as long as possible
+4. **Comprehensive Context Provision**: Provide rich, filtered context specific to each agent's domain
+5. **Results Integration**: Actively receive, analyze, and integrate agent results to inform project progress
+6. **Cross-Agent Coordination**: Orchestrate workflows that span multiple agents with proper sequencing
+7. **TodoWrite Integration**: Use TodoWrite to track and coordinate complex multi-agent workflows
+8. **Operation Tracking**: Systematic capture of operational insights and project patterns
+9. **Agent Registry Integration**: Use AgentRegistry.listAgents() for dynamic agent discovery and optimal task delegation
+10. **Precedence-Aware Orchestration**: Respect directory precedence (project → user → system) when selecting agents
+11. **Performance-Optimized Delegation**: Leverage SharedPromptCache for 99.7% faster agent loading and orchestration
+12. **Specialization-Based Routing**: Route tasks to agents with appropriate specializations beyond core 9 types using registry discovery
+
+---"""

claude_mpm/services/framework_claude_md_generator/section_generators/role_designation.py

@@ -0,0 +1,37 @@
+"""
+Role designation section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class RoleDesignationGenerator(BaseSectionGenerator):
+    """Generates the AI Assistant Role Designation section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the role designation section."""
+        deployment_date = data.get('deployment_date', self.get_timestamp())
+        
+        return f"""
+## 🤖 AI ASSISTANT ROLE DESIGNATION
+
+**You are operating within a Claude PM Framework deployment**
+
+Your primary role is operating as a multi-agent orchestrator. Your job is to orchestrate projects by:
+- **Delegating tasks** to other agents via Task Tool (subprocesses)
+- **Providing comprehensive context** to each agent for their specific domain
+- **Receiving and integrating results** to inform project progress and next steps
+- **Coordinating cross-agent workflows** to achieve project objectives
+- **Maintaining project visibility** and strategic oversight throughout execution
+
+### Framework Context
+- **Version**: {self.framework_version}
+- **Deployment Date**: {deployment_date}
+- **Platform**: {{{{PLATFORM}}}}
+- **Python Command**: {{{{PYTHON_CMD}}}}
+- **Agent Hierarchy**: Three-tier (Project → User → System) with automatic discovery
+- **Core System**: 🔧 Framework orchestration and agent coordination
+- **Performance**: ⚡ <15 second health monitoring (77% improvement)
+
+---"""

claude_mpm/services/framework_claude_md_generator/section_generators/subprocess_validation.py

@@ -0,0 +1,111 @@
+"""
+Subprocess validation section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class SubprocessValidationGenerator(BaseSectionGenerator):
+    """Generates the Subprocess Validation Protocol section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the subprocess validation section."""
+        return """
+## 🔥🚨 CRITICAL: SUBPROCESS VALIDATION PROTOCOL 🚨🔥
+
+**⚠️ WARNING: SUBPROCESS REPORTS CAN BE MISLEADING ⚠️**
+
+### 🚨 MANDATORY REAL-WORLD VERIFICATION
+
+**CRITICAL REQUIREMENT: PM MUST ALWAYS VERIFY SUBPROCESS CLAIMS WITH DIRECT TESTING**
+
+#### The Subprocess Communication Problem
+- **Task Tool subprocesses may report "SUCCESS" while actual functionality is BROKEN**
+- **Agents may validate code structure without testing runtime behavior**
+- **Import errors, version mismatches, and async failures often go undetected**
+- **Subprocess isolation creates blind spots where real errors don't surface**
+
+#### 🔥 MANDATORY VERIFICATION REQUIREMENTS
+
+**BEFORE MARKING ANY TASK COMPLETE, PM MUST:**
+
+1. **🚨 DIRECT CLI TESTING** - ALWAYS run actual CLI commands to verify functionality:
+   ```bash
+   # MANDATORY: Test actual CLI commands, not just code existence
+   claude-pm --version    # Verify actual version numbers
+   claude-pm init         # Test real initialization
+   python3 -c "import claude_pm; print(claude_pm.__version__)"  # Verify imports
+   ```
+
+2. **🚨 REAL IMPORT VALIDATION** - NEVER trust subprocess claims about imports:
+   ```bash
+   # MANDATORY: Test actual imports that will be used
+   python3 -c "from claude_pm.services.core import unified_core_service"
+   python3 -c "import asyncio; asyncio.run(test_function())"
+   ```
+
+3. **🚨 VERSION CONSISTENCY VERIFICATION** - ALWAYS check version synchronization:
+   ```bash
+   # MANDATORY: Verify all version numbers match across systems
+   grep -r "version" package.json pyproject.toml claude_pm/_version.py
+   claude-pm --version  # Must match package version
+   ```
+
+4. **🚨 FUNCTIONAL END-TO-END TESTING** - Test actual user workflows:
+   ```bash
+   # MANDATORY: Simulate real user scenarios
+   cd /tmp && mkdir test_install && cd test_install
+   npm install -g @bobmatnyc/claude-multiagent-pm
+   claude-pm init  # Must work without errors
+   ```
+
+#### 🔥 CRITICAL: SUBPROCESS TRUST VERIFICATION
+
+**WHEN SUBPROCESS REPORTS SUCCESS:**
+- ❌ **DO NOT TRUST IMMEDIATELY**
+- ✅ **VERIFY WITH DIRECT TESTING**
+- ✅ **TEST RUNTIME BEHAVIOR, NOT JUST CODE STRUCTURE**
+- ✅ **VALIDATE ACTUAL USER EXPERIENCE**
+
+**WHEN SUBPROCESS REPORTS PASSING TESTS:**
+- ❌ **DO NOT ASSUME REAL FUNCTIONALITY WORKS**
+- ✅ **RUN THE ACTUAL COMMANDS USERS WILL RUN**
+- ✅ **TEST IMPORTS AND ASYNC OPERATIONS DIRECTLY**
+- ✅ **VERIFY VERSION NUMBERS ARE CORRECT IN REALITY**
+
+#### 🚨 ESCALATION TRIGGERS
+
+**IMMEDIATELY ESCALATE TO USER WHEN:**
+- Subprocess reports success but direct testing reveals failures
+- Version numbers don't match between CLI output and package files
+- Import errors occur for modules that subprocess claims exist
+- CLI commands fail despite subprocess validation claims
+- Any discrepancy between subprocess reports and actual functionality
+
+#### 🔥 IMPLEMENTATION REQUIREMENT
+
+**PM MUST IMPLEMENT THIS VALIDATION AFTER EVERY SUBPROCESS DELEGATION:**
+
+```bash
+# Template for MANDATORY post-subprocess validation
+echo "🔍 VERIFYING SUBPROCESS CLAIMS..."
+
+# Test actual CLI functionality
+claude-pm --version
+claude-pm --help
+
+# Test actual imports
+python3 -c "import claude_pm; print('✅ Basic import works')"
+python3 -c "from claude_pm.services.core import [specific_function]; print('✅ Specific import works')"
+
+# Test version consistency
+echo "📋 VERSION VERIFICATION:"
+echo "Package.json: $(grep '"version"' package.json)"
+echo "CLI Output: $(claude-pm --version 2>/dev/null || echo 'CLI FAILED')"
+echo "Python Module: $(python3 -c 'import claude_pm; print(claude_pm.__version__)' 2>/dev/null || echo 'IMPORT FAILED')"
+
+# If ANY of the above fail, IMMEDIATELY inform user and fix issues
+```
+
+---"""

claude_mpm/services/framework_claude_md_generator/section_generators/todo_task_tools.py

@@ -0,0 +1,89 @@
+"""
+Todo and Task Tools section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class TodoTaskToolsGenerator(BaseSectionGenerator):
+    """Generates the Todo and Task Tools section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the todo and task tools section."""
+        return """
+## B) TODO AND TASK TOOLS
+
+### 🚨 MANDATORY: TodoWrite Integration with Task Tool
+
+**Workflow Pattern:**
+1. **Create TodoWrite entries** for complex multi-agent tasks with automatic agent name prefixes
+2. **Mark todo as in_progress** when delegating via Task Tool
+3. **Update todo status** based on subprocess completion
+4. **Mark todo as completed** when agent delivers results
+
+### Agent Name Prefix System
+
+**Standard TodoWrite Entry Format:**
+- **Research tasks** → `Researcher: [task description]`
+- **Documentation tasks** → `Documentater: [task description]`
+- **Changelog tasks** → `Documentater: [changelog description]`
+- **QA tasks** → `QA: [task description]`
+- **DevOps tasks** → `Ops: [task description]`
+- **Security tasks** → `Security: [task description]`
+- **Version Control tasks** → `Versioner: [task description]`
+- **Version Management tasks** → `Versioner: [version management description]`
+- **Code Implementation tasks** → `Engineer: [implementation description]`
+- **Data Operations tasks** → `Data Engineer: [data management description]`
+
+### Task Tool Subprocess Naming Conventions
+
+**Template Pattern:**
+```
+**[Agent Nickname]**: [Specific task description with clear deliverables]
+```
+
+**Examples of Proper Naming:**
+- ✅ **Documentationer**: Update framework/CLAUDE.md with Task Tool naming conventions
+- ✅ **QA**: Execute comprehensive test suite validation for merge readiness
+- ✅ **Versioner**: Create feature branch and sync with remote repository
+- ✅ **Researcher**: Investigate Next.js 14 performance optimization patterns
+- ✅ **Engineer**: Implement user authentication system with JWT tokens
+- ✅ **Data Engineer**: Configure PostgreSQL database and optimize query performance
+
+### 🚨 MANDATORY: THREE SHORTCUT COMMANDS
+
+#### 1. **"push"** - Version Control, Quality Assurance & Release Management
+**Enhanced Delegation Flow**: PM → Documentation Agent (changelog & version docs) → QA Agent (testing/linting) → Data Engineer Agent (data validation & API checks) → Version Control Agent (tracking, version bumping & Git operations)
+
+**Components:**
+1. **Documentation Agent**: Generate changelog, analyze semantic versioning impact
+2. **QA Agent**: Execute test suite, perform quality validation
+3. **Data Engineer Agent**: Validate data integrity, verify API connectivity, check database schemas
+4. **Version Control Agent**: Track files, apply version bumps, create tags, execute Git operations
+
+#### 2. **"deploy"** - Local Deployment Operations
+**Delegation Flow**: PM → Ops Agent (local deployment) → QA Agent (deployment validation)
+
+#### 3. **"publish"** - Package Publication Pipeline
+**Delegation Flow**: PM → Documentation Agent (version docs) → Ops Agent (package publication)
+
+### Multi-Agent Coordination Workflows
+
+**Example Integration:**
+```
+TodoWrite: Create prefixed todos for "Push release"
+- ☐ Documentation Agent: Generate changelog and analyze version impact
+- ☐ QA Agent: Execute full test suite and quality validation
+- ☐ Data Engineer Agent: Validate data integrity and verify API connectivity
+- ☐ Version Control Agent: Apply semantic version bump and create release tags
+
+Task Tool → Documentation Agent: Generate changelog and analyze version impact
+Task Tool → QA Agent: Execute full test suite and quality validation
+Task Tool → Data Engineer Agent: Validate data integrity and verify API connectivity
+Task Tool → Version Control Agent: Apply semantic version bump and create release tags
+
+Update TodoWrite status based on agent completions
+```
+
+---"""

claude_mpm/services/framework_claude_md_generator/section_generators/troubleshooting.py

@@ -0,0 +1,39 @@
+"""
+Troubleshooting section generator for framework CLAUDE.md.
+"""
+
+from typing import Dict, Any
+from . import BaseSectionGenerator
+
+
+class TroubleshootingGenerator(BaseSectionGenerator):
+    """Generates the Troubleshooting section."""
+    
+    def generate(self, data: Dict[str, Any]) -> str:
+        """Generate the troubleshooting section."""
+        return """
+## 🚨 TROUBLESHOOTING
+
+### Common Issues
+1. **CLI Not Working**: Check claude-pm installation and path
+2. **Python Import Errors**: Verify Python environment and dependencies
+3. **Health Check Failures**: Run `claude-pm init --verify` for diagnostics
+4. **Permission Issues**: Ensure proper file permissions on CLI executables
+
+### claude-pm init and Agent Hierarchy Issues
+5. **Missing .claude-pm Directories**: Run `claude-pm init --setup`
+6. **Agent Hierarchy Validation Errors**: Run `claude-pm init --verify` for detailed validation
+
+### Core System Issues
+7. **Core System Issues**: Update initialization to use proper configuration
+8. **Core System Not Working**: Verify API keys and network connectivity
+9. **Core System Performance Issues**: Implement system optimization
+
+### Agent Registry Issues
+10. **Agent Registry Discovery Failures**: Run `python -c "from claude_pm.core.agent_registry import AgentRegistry; AgentRegistry().health_check()"`
+11. **Agent Precedence Problems**: Verify directory structure with `claude-pm init --verify`
+12. **Specialization Discovery Issues**: Check agent metadata and specialization tags
+13. **Performance Cache Problems**: Clear SharedPromptCache and reinitialize registry
+14. **Agent Modification Tracking Errors**: Verify agent file permissions and timestamps
+15. **Custom Agent Loading Issues**: Verify user-agents directory structure and agent file format
+16. **Directory Precedence Problems**: Check user-agents directory hierarchy and parent directory traversal"""

claude_mpm/services/framework_claude_md_generator/section_manager.py

@@ -0,0 +1,106 @@
+"""
+Section management for framework CLAUDE.md templates.
+
+Manages section registration, ordering, and updates.
+"""
+
+from typing import Dict, List, Optional, Callable, Any
+from collections import OrderedDict
+
+
+class SectionManager:
+    """Manages sections for framework CLAUDE.md generation."""
+    
+    def __init__(self):
+        """Initialize section manager."""
+        self.sections = OrderedDict()
+    
+    def register_section(self, 
+                        name: str, 
+                        generator: Callable[[Dict[str, Any]], str],
+                        data: Optional[Dict[str, Any]] = None):
+        """
+        Register a section generator.
+        
+        Args:
+            name: Section name
+            generator: Function that generates section content
+            data: Optional data to pass to generator
+        """
+        self.sections[name] = (generator, data or {})
+    
+    def update_section(self, section_name: str, content: str) -> bool:
+        """
+        Update a specific section's generator to return custom content.
+        
+        Args:
+            section_name: Name of section to update
+            content: New content for the section
+            
+        Returns:
+            bool: Success status
+        """
+        if section_name not in self.sections:
+            return False
+        
+        # Create a lambda that returns the custom content
+        self.sections[section_name] = (lambda data: content, {})
+        return True
+    
+    def add_custom_section(self, 
+                          section_name: str, 
+                          content: str, 
+                          after: Optional[str] = None):
+        """
+        Add a custom section to the generator.
+        
+        Args:
+            section_name: Name for the new section
+            content: Content for the section
+            after: Section name to insert after (None = append at end)
+        """
+        new_section = (lambda data: content, {})
+        
+        if after is None or after not in self.sections:
+            self.sections[section_name] = new_section
+        else:
+            # Insert after specified section
+            new_sections = OrderedDict()
+            for key, value in self.sections.items():
+                new_sections[key] = value
+                if key == after:
+                    new_sections[section_name] = new_section
+            self.sections = new_sections
+    
+    def get_section_list(self) -> List[str]:
+        """
+        Get list of all section names in order.
+        
+        Returns:
+            List of section names
+        """
+        return list(self.sections.keys())
+    
+    def get_sections(self) -> OrderedDict:
+        """
+        Get all sections.
+        
+        Returns:
+            OrderedDict of section definitions
+        """
+        return self.sections
+    
+    def remove_section(self, section_name: str) -> bool:
+        """
+        Remove a section.
+        
+        Args:
+            section_name: Name of section to remove
+            
+        Returns:
+            bool: Success status
+        """
+        if section_name in self.sections:
+            del self.sections[section_name]
+            return True
+        return False

claude_mpm/services/framework_claude_md_generator/version_manager.py

@@ -0,0 +1,121 @@
+"""
+Version management for framework CLAUDE.md templates.
+
+Handles version parsing, incrementing, and comparison operations.
+"""
+
+import re
+from typing import Tuple, Optional
+from pathlib import Path
+
+
+class VersionManager:
+    """Manages version numbering for framework CLAUDE.md templates."""
+    
+    def __init__(self):
+        """Initialize version manager."""
+        self.framework_version = self._get_framework_version()
+    
+    def _get_framework_version(self) -> str:
+        """
+        Get the current framework version from framework/VERSION file.
+        
+        Returns:
+            str: Framework version (e.g., "015")
+        """
+        # Check if we're in a wheel installation
+        package_path = Path(__file__).parent.parent.parent
+        path_str = str(package_path.resolve())
+        if 'site-packages' in path_str or 'dist-packages' in path_str:
+            # For wheel installations, check data directory
+            version_path = package_path / "data" / "framework" / "VERSION"
+            if not version_path.exists():
+                # Try package root as fallback
+                version_path = package_path.parent / "framework" / "VERSION"
+        else:
+            # Source installation
+            version_path = package_path.parent / "framework" / "VERSION"
+        
+        if version_path.exists():
+            with open(version_path, 'r') as f:
+                version_content = f.read().strip()
+                # Framework VERSION file contains just the framework version number
+                try:
+                    return f"{int(version_content):03d}"
+                except ValueError:
+                    # If not a plain number, try to extract from version string
+                    match = re.match(r'(\d+)', version_content)
+                    if match:
+                        return f"{int(match.group(1)):03d}"
+        return "014"  # Default fallback
+    
+    def parse_current_version(self, content: str) -> str:
+        """
+        Parse the current CLAUDE_MD_VERSION from existing content.
+        
+        Args:
+            content: Existing CLAUDE.md content
+            
+        Returns:
+            str: Version number (e.g., "016")
+        """
+        # First try simple serial format
+        match = re.search(r'CLAUDE_MD_VERSION:\s*(\d+)(?!-)', content)
+        if match:
+            return match.group(1)
+        
+        # Handle old format for backward compatibility
+        match = re.search(r'CLAUDE_MD_VERSION:\s*(\d+)-(\d+)', content)
+        if match:
+            return match.group(1)  # Return just the framework part
+        
+        return self.framework_version
+    
+    def auto_increment_version(self, current_content: Optional[str] = None) -> str:
+        """
+        Get the current framework version (no auto-increment for simple serial numbers).
+        
+        Args:
+            current_content: Current CLAUDE.md content (unused with simple serials)
+            
+        Returns:
+            str: Current framework version (e.g., "016")
+        """
+        # With simple serial numbers, we just use the framework version
+        # Incrementing is done by updating the framework/VERSION file
+        return self.framework_version
+    
+    def compare_versions(self, version1: str, version2: str) -> int:
+        """
+        Compare two version strings.
+        
+        Args:
+            version1: First version string (e.g., "016")
+            version2: Second version string (e.g., "017")
+            
+        Returns:
+            int: -1 if version1 < version2, 0 if equal, 1 if version1 > version2
+        """
+        def parse_version(v: str) -> int:
+            # Handle simple serial format
+            if '-' not in v:
+                try:
+                    return int(v)
+                except ValueError:
+                    return 0
+            
+            # Handle old format for backward compatibility
+            match = re.match(r'(\d+)-(\d+)', v)
+            if match:
+                return int(match.group(1))  # Just compare framework part
+            return 0
+        
+        v1 = parse_version(version1)
+        v2 = parse_version(version2)
+        
+        if v1 < v2:
+            return -1
+        elif v1 > v2:
+            return 1
+        else:
+            return 0