claude-mpm 4.13.2__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/agents/frontmatter_validator.py

@@ -23,6 +23,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 import yaml
 
+from claude_mpm.core.enums import ModelTier
 from claude_mpm.core.logging_utils import get_logger
 
 logger = get_logger(__name__)
@@ -54,33 +55,8 @@ class FrontmatterValidator:
     - Logging of all corrections made
     """
 
-    # Model name mappings for normalization
-    MODEL_MAPPINGS = {
-        # Sonnet variations
-        "claude-3-5-sonnet-20241022": "sonnet",
-        "claude-3-5-sonnet-20240620": "sonnet",
-        "claude-sonnet-4-20250514": "sonnet",
-        "claude-4-sonnet-20250514": "sonnet",
-        "claude-3-sonnet-20240229": "sonnet",
-        "20241022": "sonnet",  # Common shorthand - maps to current Sonnet
-        "20240620": "sonnet",  # Previous Sonnet version
-        "3.5-sonnet": "sonnet",
-        "sonnet-3.5": "sonnet",
-        "sonnet-4": "sonnet",
-        # Opus variations
-        "claude-3-opus-20240229": "opus",
-        "claude-opus-4-20250514": "opus",
-        "claude-4-opus-20250514": "opus",
-        "3-opus": "opus",
-        "opus-3": "opus",
-        "opus-4": "opus",
-        # Haiku variations
-        "claude-3-haiku-20240307": "haiku",
-        "claude-3-5-haiku-20241022": "haiku",
-        "3-haiku": "haiku",
-        "haiku-3": "haiku",
-        "haiku-3.5": "haiku",
-    }
+    # NOTE: Model normalization now handled by ModelTier.normalize()
+    # This enum-based approach replaced 26 lines of manual mappings
 
     # Tool name corrections (case normalization)
     TOOL_CORRECTIONS = {
@@ -179,13 +155,44 @@ class FrontmatterValidator:
         Returns:
             ValidationResult with validation status and corrected frontmatter
         """
-        errors = []
-        warnings = []
-        corrections = []
+        errors: List[str] = []
+        warnings: List[str] = []
+        corrections: List[str] = []
         corrected = frontmatter.copy()
-        field_corrections = {}  # Track only the fields that actually need correction
+        field_corrections: Dict[str, Any] = {}
+
+        # Check required fields
+        self._validate_required_fields(corrected, errors)
+
+        # Validate and correct individual fields
+        self._validate_name_field(corrected, field_corrections, errors, corrections)
+        self._validate_model_field(corrected, field_corrections, errors, corrections)
+        self._validate_tools_field(corrected, field_corrections, warnings, corrections)
+        self._validate_version_fields(corrected, field_corrections, errors, corrections)
+        self._validate_description_field(corrected, errors, warnings)
+        self._validate_category_field(corrected, warnings)
+        self._validate_resource_tier_field(corrected, warnings)
+        self._validate_color_field(corrected, errors)
+        self._validate_author_field(corrected, errors, warnings)
+        self._validate_tags_field(corrected, errors, warnings)
+        self._validate_numeric_fields(corrected, errors, warnings)
+
+        # Determine if valid
+        is_valid = len(errors) == 0
+
+        return ValidationResult(
+            is_valid=is_valid,
+            errors=errors,
+            warnings=warnings,
+            corrections=corrections,
+            corrected_frontmatter=corrected if corrections else None,
+            field_corrections=field_corrections if field_corrections else None,
+        )
 
-        # Required fields check (from schema)
+    def _validate_required_fields(
+        self, corrected: Dict[str, Any], errors: List[str]
+    ) -> None:
+        """Check that all required fields are present."""
         required_fields = (
             self.schema.get("required", ["name", "description", "version", "model"])
             if self.schema
@@ -195,227 +202,271 @@ class FrontmatterValidator:
             if field not in corrected:
                 errors.append(f"Missing required field: {field}")
 
-        # Validate and correct name field
-        if "name" in corrected:
-            name = corrected["name"]
-            if not isinstance(name, str):
-                errors.append(
-                    f"Field 'name' must be a string, got {type(name).__name__}"
-                )
-            elif not re.match(r"^[a-z][a-z0-9_]*$", name):
-                # Try to fix the name
-                fixed_name = name.lower().replace("-", "_").replace(" ", "_")
-                fixed_name = re.sub(r"[^a-z0-9_]", "", fixed_name)
-                if fixed_name and fixed_name[0].isalpha():
-                    corrected["name"] = fixed_name
-                    field_corrections["name"] = fixed_name
-                    corrections.append(
-                        f"Corrected name from '{name}' to '{fixed_name}'"
-                    )
-                else:
-                    errors.append(f"Invalid name format: {name}")
-
-        # Validate and correct model field
-        if "model" in corrected:
-            model = corrected["model"]
-
-            # Convert to string if it's a number (YAML might parse dates as integers)
-            if isinstance(model, (int, float)):
-                model = str(model)
-                corrected["model"] = model
-                field_corrections["model"] = model
-                corrections.append(f"Converted model from number to string: {model}")
-
-            if not isinstance(model, str):
-                errors.append(
-                    f"Field 'model' must be a string, got {type(model).__name__}"
-                )
+    def _validate_name_field(
+        self,
+        corrected: Dict[str, Any],
+        field_corrections: Dict[str, Any],
+        errors: List[str],
+        corrections: List[str],
+    ) -> None:
+        """Validate and correct the name field."""
+        if "name" not in corrected:
+            return
+
+        name = corrected["name"]
+        if not isinstance(name, str):
+            errors.append(f"Field 'name' must be a string, got {type(name).__name__}")
+            return
+
+        if not re.match(r"^[a-z][a-z0-9_]*$", name):
+            # Try to fix the name
+            fixed_name = name.lower().replace("-", "_").replace(" ", "_")
+            fixed_name = re.sub(r"[^a-z0-9_]", "", fixed_name)
+            if fixed_name and fixed_name[0].isalpha():
+                corrected["name"] = fixed_name
+                field_corrections["name"] = fixed_name
+                corrections.append(f"Corrected name from '{name}' to '{fixed_name}'")
             else:
-                normalized_model = self._normalize_model(model)
-                if normalized_model != model:
-                    corrected["model"] = normalized_model
-                    field_corrections["model"] = normalized_model
-                    corrections.append(
-                        f"Normalized model from '{model}' to '{normalized_model}'"
-                    )
-
-                if normalized_model not in self.VALID_MODELS:
-                    errors.append(
-                        f"Invalid model: {model} (normalized to {normalized_model})"
-                    )
-
-        # Validate and correct tools field
-        if "tools" in corrected:
-            tools = corrected["tools"]
-            corrected_tools, tool_corrections = self._correct_tools(tools)
-            if tool_corrections:
-                corrected["tools"] = corrected_tools
-                field_corrections["tools"] = corrected_tools
-                corrections.extend(tool_corrections)
-
-            # Validate tool names
-            invalid_tools = []
-            for tool in corrected_tools:
-                if tool not in self.VALID_TOOLS:
-                    # Try to correct the tool name
-                    corrected_tool = self.TOOL_CORRECTIONS.get(tool.lower())
-                    if corrected_tool:
-                        idx = corrected_tools.index(tool)
-                        corrected_tools[idx] = corrected_tool
-                        corrected["tools"] = corrected_tools
-                        field_corrections["tools"] = corrected_tools
-                        corrections.append(
-                            f"Corrected tool '{tool}' to '{corrected_tool}'"
-                        )
-                    else:
-                        invalid_tools.append(tool)
-
-            if invalid_tools:
-                warnings.append(f"Unknown tools: {', '.join(invalid_tools)}")
+                errors.append(f"Invalid name format: {name}")
+
+    def _validate_model_field(
+        self,
+        corrected: Dict[str, Any],
+        field_corrections: Dict[str, Any],
+        errors: List[str],
+        corrections: List[str],
+    ) -> None:
+        """Validate and correct the model field."""
+        if "model" not in corrected:
+            return
+
+        model = corrected["model"]
+
+        # Convert to string if it's a number (YAML might parse dates as integers)
+        if isinstance(model, (int, float)):
+            model = str(model)
+            corrected["model"] = model
+            field_corrections["model"] = model
+            corrections.append(f"Converted model from number to string: {model}")
+
+        if not isinstance(model, str):
+            errors.append(f"Field 'model' must be a string, got {type(model).__name__}")
+            return
+
+        normalized_model = self._normalize_model(model)
+        if normalized_model != model:
+            corrected["model"] = normalized_model
+            field_corrections["model"] = normalized_model
+            corrections.append(
+                f"Normalized model from '{model}' to '{normalized_model}'"
+            )
 
-        # Validate version fields
+        if normalized_model not in self.VALID_MODELS:
+            errors.append(f"Invalid model: {model} (normalized to {normalized_model})")
+
+    def _validate_tools_field(
+        self,
+        corrected: Dict[str, Any],
+        field_corrections: Dict[str, Any],
+        warnings: List[str],
+        corrections: List[str],
+    ) -> None:
+        """Validate and correct the tools field."""
+        if "tools" not in corrected:
+            return
+
+        tools = corrected["tools"]
+        corrected_tools, tool_corrections = self._correct_tools(tools)
+        if tool_corrections:
+            corrected["tools"] = corrected_tools
+            field_corrections["tools"] = corrected_tools
+            corrections.extend(tool_corrections)
+
+        # Validate tool names
+        invalid_tools = []
+        for tool in corrected_tools:
+            if tool not in self.VALID_TOOLS:
+                # Try to correct the tool name
+                corrected_tool = self.TOOL_CORRECTIONS.get(tool.lower())
+                if corrected_tool:
+                    idx = corrected_tools.index(tool)
+                    corrected_tools[idx] = corrected_tool
+                    corrected["tools"] = corrected_tools
+                    field_corrections["tools"] = corrected_tools
+                    corrections.append(f"Corrected tool '{tool}' to '{corrected_tool}'")
+                else:
+                    invalid_tools.append(tool)
+
+        if invalid_tools:
+            warnings.append(f"Unknown tools: {', '.join(invalid_tools)}")
+
+    def _validate_version_fields(
+        self,
+        corrected: Dict[str, Any],
+        field_corrections: Dict[str, Any],
+        errors: List[str],
+        corrections: List[str],
+    ) -> None:
+        """Validate and correct version fields."""
         version_fields = ["version", "base_version"]
         for field in version_fields:
-            if field in corrected:
-                version = corrected[field]
-                if not isinstance(version, str):
-                    errors.append(
-                        f"Field '{field}' must be a string, got {type(version).__name__}"
-                    )
-                elif not re.match(r"^\d+\.\d+\.\d+$", version):
-                    # Try to fix common version issues
-                    if re.match(r"^\d+\.\d+$", version):
-                        fixed_version = f"{version}.0"
-                        corrected[field] = fixed_version
-                        field_corrections[field] = fixed_version
-                        corrections.append(
-                            f"Fixed {field} from '{version}' to '{fixed_version}'"
-                        )
-                    elif re.match(r"^v?\d+\.\d+\.\d+$", version):
-                        fixed_version = version.lstrip("v")
-                        corrected[field] = fixed_version
-                        field_corrections[field] = fixed_version
-                        corrections.append(
-                            f"Fixed {field} from '{version}' to '{fixed_version}'"
-                        )
-                    else:
-                        errors.append(f"Invalid {field} format: {version}")
+            if field not in corrected:
+                continue
 
-        # Validate description
-        if "description" in corrected:
-            desc = corrected["description"]
-            if not isinstance(desc, str):
+            version = corrected[field]
+            if not isinstance(version, str):
                 errors.append(
-                    f"Field 'description' must be a string, got {type(desc).__name__}"
-                )
-            elif len(desc) < 10:
-                warnings.append(
-                    f"Description too short ({len(desc)} chars, minimum 10)"
-                )
-            elif len(desc) > 200:
-                warnings.append(
-                    f"Description too long ({len(desc)} chars, maximum 200)"
+                    f"Field '{field}' must be a string, got {type(version).__name__}"
                 )
+                continue
 
-        # Validate optional fields
-        if "category" in corrected:
-            valid_categories = [
-                "engineering",
-                "research",
-                "quality",
-                "operations",
-                "specialized",
-            ]
-            if corrected["category"] not in valid_categories:
-                warnings.append(f"Invalid category: {corrected['category']}")
-
-        if "resource_tier" in corrected:
-            valid_tiers = ["basic", "standard", "intensive", "lightweight"]
-            if corrected["resource_tier"] not in valid_tiers:
-                warnings.append(f"Invalid resource_tier: {corrected['resource_tier']}")
-
-        # Validate color field
-        if "color" in corrected:
-            color = corrected["color"]
-            if not isinstance(color, str):
-                errors.append(
-                    f"Field 'color' must be a string, got {type(color).__name__}"
-                )
-            # Color validation could be expanded to check for valid color names/hex codes
+            if re.match(r"^\d+\.\d+\.\d+$", version):
+                continue  # Valid format
 
-        # Validate author field
-        if "author" in corrected:
-            author = corrected["author"]
-            if not isinstance(author, str):
-                errors.append(
-                    f"Field 'author' must be a string, got {type(author).__name__}"
+            # Try to fix common version issues
+            if re.match(r"^\d+\.\d+$", version):
+                fixed_version = f"{version}.0"
+                corrected[field] = fixed_version
+                field_corrections[field] = fixed_version
+                corrections.append(
+                    f"Fixed {field} from '{version}' to '{fixed_version}'"
                 )
-            elif len(author) > 100:
-                warnings.append(
-                    f"Author field too long ({len(author)} chars, maximum 100)"
+            elif re.match(r"^v?\d+\.\d+\.\d+$", version):
+                fixed_version = version.lstrip("v")
+                corrected[field] = fixed_version
+                field_corrections[field] = fixed_version
+                corrections.append(
+                    f"Fixed {field} from '{version}' to '{fixed_version}'"
                 )
-
-        # Validate tags field (supports both list and comma-separated string)
-        if "tags" in corrected:
-            tags = corrected["tags"]
-            if isinstance(tags, str):
-                # Convert comma-separated string to list for validation
-                tag_list = [tag.strip() for tag in tags.split(",") if tag.strip()]
-            elif isinstance(tags, list):
-                tag_list = tags
             else:
-                errors.append(
-                    f"Field 'tags' must be a list or comma-separated string, got {type(tags).__name__}"
+                errors.append(f"Invalid {field} format: {version}")
+
+    def _validate_description_field(
+        self, corrected: Dict[str, Any], errors: List[str], warnings: List[str]
+    ) -> None:
+        """Validate the description field."""
+        if "description" not in corrected:
+            return
+
+        desc = corrected["description"]
+        if not isinstance(desc, str):
+            errors.append(
+                f"Field 'description' must be a string, got {type(desc).__name__}"
+            )
+        elif len(desc) < 10:
+            warnings.append(f"Description too short ({len(desc)} chars, minimum 10)")
+        elif len(desc) > 200:
+            warnings.append(f"Description too long ({len(desc)} chars, maximum 200)")
+
+    def _validate_category_field(
+        self, corrected: Dict[str, Any], warnings: List[str]
+    ) -> None:
+        """Validate the category field."""
+        if "category" not in corrected:
+            return
+
+        valid_categories = [
+            "engineering",
+            "research",
+            "quality",
+            "operations",
+            "specialized",
+        ]
+        if corrected["category"] not in valid_categories:
+            warnings.append(f"Invalid category: {corrected['category']}")
+
+    def _validate_resource_tier_field(
+        self, corrected: Dict[str, Any], warnings: List[str]
+    ) -> None:
+        """Validate the resource_tier field."""
+        if "resource_tier" not in corrected:
+            return
+
+        valid_tiers = ["basic", "standard", "intensive", "lightweight"]
+        if corrected["resource_tier"] not in valid_tiers:
+            warnings.append(f"Invalid resource_tier: {corrected['resource_tier']}")
+
+    def _validate_color_field(
+        self, corrected: Dict[str, Any], errors: List[str]
+    ) -> None:
+        """Validate the color field."""
+        if "color" not in corrected:
+            return
+
+        color = corrected["color"]
+        if not isinstance(color, str):
+            errors.append(f"Field 'color' must be a string, got {type(color).__name__}")
+
+    def _validate_author_field(
+        self, corrected: Dict[str, Any], errors: List[str], warnings: List[str]
+    ) -> None:
+        """Validate the author field."""
+        if "author" not in corrected:
+            return
+
+        author = corrected["author"]
+        if not isinstance(author, str):
+            errors.append(
+                f"Field 'author' must be a string, got {type(author).__name__}"
+            )
+        elif len(author) > 100:
+            warnings.append(f"Author field too long ({len(author)} chars, maximum 100)")
+
+    def _validate_tags_field(
+        self, corrected: Dict[str, Any], errors: List[str], warnings: List[str]
+    ) -> None:
+        """Validate the tags field."""
+        if "tags" not in corrected:
+            return
+
+        tags = corrected["tags"]
+        if isinstance(tags, str):
+            # Convert comma-separated string to list for validation
+            tag_list = [tag.strip() for tag in tags.split(",") if tag.strip()]
+        elif isinstance(tags, list):
+            tag_list = tags
+        else:
+            errors.append(
+                f"Field 'tags' must be a list or comma-separated string, got {type(tags).__name__}"
+            )
+            return
+
+        for tag in tag_list:
+            if not isinstance(tag, str):
+                errors.append(f"All tags must be strings, found {type(tag).__name__}")
+            elif not re.match(r"^[a-z][a-z0-9-]*$", tag):
+                warnings.append(
+                    f"Tag '{tag}' doesn't match recommended pattern (lowercase, alphanumeric with hyphens)"
                 )
-                tag_list = []
-
-            for tag in tag_list:
-                if not isinstance(tag, str):
-                    errors.append(
-                        f"All tags must be strings, found {type(tag).__name__}"
-                    )
-                elif not re.match(r"^[a-z][a-z0-9-]*$", tag):
-                    warnings.append(
-                        f"Tag '{tag}' doesn't match recommended pattern (lowercase, alphanumeric with hyphens)"
-                    )
-
-        # Validate numeric fields
+
+    def _validate_numeric_fields(
+        self, corrected: Dict[str, Any], errors: List[str], warnings: List[str]
+    ) -> None:
+        """Validate numeric fields (max_tokens, temperature)."""
         for field_name, (min_val, max_val) in [
             ("max_tokens", (1000, 200000)),
             ("temperature", (0, 1)),
         ]:
-            if field_name in corrected:
-                value = corrected[field_name]
-                if field_name == "temperature" and not isinstance(value, (int, float)):
-                    errors.append(
-                        f"Field '{field_name}' must be a number, got {type(value).__name__}"
-                    )
-                elif field_name == "max_tokens" and not isinstance(value, int):
-                    errors.append(
-                        f"Field '{field_name}' must be an integer, got {type(value).__name__}"
-                    )
-                elif isinstance(value, (int, float)) and not (
-                    min_val <= value <= max_val
-                ):
-                    warnings.append(
-                        f"Field '{field_name}' value {value} outside recommended range [{min_val}, {max_val}]"
-                    )
+            if field_name not in corrected:
+                continue
 
-        # Determine if valid
-        is_valid = len(errors) == 0
-
-        return ValidationResult(
-            is_valid=is_valid,
-            errors=errors,
-            warnings=warnings,
-            corrections=corrections,
-            corrected_frontmatter=corrected if corrections else None,
-            field_corrections=field_corrections if field_corrections else None,
-        )
+            value = corrected[field_name]
+            if field_name == "temperature" and not isinstance(value, (int, float)):
+                errors.append(
+                    f"Field '{field_name}' must be a number, got {type(value).__name__}"
+                )
+            elif field_name == "max_tokens" and not isinstance(value, int):
+                errors.append(
+                    f"Field '{field_name}' must be an integer, got {type(value).__name__}"
+                )
+            elif isinstance(value, (int, float)) and not (min_val <= value <= max_val):
+                warnings.append(
+                    f"Field '{field_name}' value {value} outside recommended range [{min_val}, {max_val}]"
+                )
 
     def _normalize_model(self, model: str) -> str:
         """
-        Normalize model name to standard tier (opus, sonnet, haiku).
+        Normalize model name to standard tier using ModelTier enum.
 
         Args:
             model: Original model name
@@ -423,27 +474,7 @@ class FrontmatterValidator:
         Returns:
             Normalized model tier name
         """
-        # Direct mapping check
-        if model in self.MODEL_MAPPINGS:
-            return self.MODEL_MAPPINGS[model]
-
-        # Already normalized
-        if model in self.VALID_MODELS:
-            return model
-
-        # Try case-insensitive match
-        model_lower = model.lower()
-        if model_lower in self.VALID_MODELS:
-            return model_lower
-
-        # Check if model contains tier name
-        for tier in self.VALID_MODELS:
-            if tier in model_lower:
-                return tier
-
-        # Default to sonnet if unrecognized
-        logger.warning(f"Unrecognized model '{model}', defaulting to 'sonnet'")
-        return "sonnet"
+        return ModelTier.normalize(model).value
 
     def _correct_tools(self, tools: Any) -> Tuple[List[str], List[str]]:
         """

claude_mpm/agents/templates/agentic-coder-optimizer.json

@@ -72,7 +72,7 @@
       ]
     }
   },
-  "instructions": "# Agentic Coder Optimizer\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Project optimization for agentic coders and Claude Code\n\n## Core Mission\n\nOptimize projects for Claude Code and other agentic coders by establishing clear, single-path project standards. Implement the \"ONE way to do ANYTHING\" principle with comprehensive documentation and discoverable workflows.\n\n## Core Responsibilities\n\n### 1. Project Documentation Structure\n- **CLAUDE.md**: Brief description + links to key documentation\n- **Documentation Hierarchy**:\n  - README.md (project overview and entry point)\n  - CLAUDE.md (agentic coder instructions)\n  - CODE.md (coding standards)\n  - DEVELOPER.md (developer guide)\n  - USER.md (user guide)\n  - OPS.md (operations guide)\n  - DEPLOY.md (deployment procedures)\n  - STRUCTURE.md (project structure)\n- **Link Validation**: Ensure all docs are properly linked and discoverable\n\n### 2. Build and Deployment Optimization\n- **Standardize Scripts**: Review and unify build/make/deploy scripts\n- **Single Path Establishment**:\n  - Building the project: `make build` or single command\n  - Running locally: `make dev` or `make start`\n  - Deploying to production: `make deploy`\n  - Publishing packages: `make publish`\n- **Clear Documentation**: Each process documented with examples\n\n### 3. Code Quality Tooling\n- **Unified Quality Commands**:\n  - Linting with auto-fix: `make lint-fix`\n  - Type checking: `make typecheck`\n  - Code formatting: `make format`\n  - All quality checks: `make quality`\n- **Pre-commit Integration**: Set up automated quality gates\n\n### 4. Version Management\n- **Semantic Versioning**: Implement proper semver\n- **Automated Build Numbers**: Set up build number tracking\n- **Version Workflow**: Clear process for version bumps\n- **Documentation**: Version management procedures\n\n### 5. Testing Framework\n- **Clear Structure**:\n  - Unit tests: `make test-unit`\n  - Integration tests: `make test-integration`\n  - End-to-end tests: `make test-e2e`\n  - All tests: `make test`\n- **Coverage Goals**: Establish and document targets\n- **Testing Requirements**: Clear guidelines and examples\n\n### 6. Developer Experience\n- **5-Minute Setup**: Ensure rapid onboarding\n- **Getting Started Guide**: Works immediately\n- **Contribution Guidelines**: Clear and actionable\n- **Development Environment**: Standardized tooling\n\n### 7. API Documentation Strategy\n\n#### OpenAPI/Swagger Decision Framework\n\n**Use OpenAPI/Swagger When:**\n- Multiple consumer teams need formal API contracts\n- SDK generation is required across multiple languages\n- Compliance requirements demand formal API specification\n- API gateway integration requires OpenAPI specs\n- Large, complex APIs benefit from formal structure\n\n**Consider Alternatives When:**\n- Full-stack TypeScript enables end-to-end type safety\n- Internal APIs with limited consumers\n- Rapid prototyping where specification overhead slows development\n- GraphQL better matches your data access patterns\n- Documentation experience is more important than technical specification\n\n**Hybrid Approach When:**\n- Public APIs need both technical specs and great developer experience\n- Migration scenarios from existing Swagger implementations\n- Team preferences vary across different API consumers\n\n**Current Best Practice:**\nThe most effective approach combines specification with enhanced developer experience:\n- **Generate, don't write**: Use code-first tools that auto-generate specs\n- **Layer documentation**: OpenAPI for contracts, enhanced platforms for developer experience\n- **Validate continuously**: Ensure specs stay synchronized with implementation\n- **Consider context**: Match tooling to team size, API complexity, and consumer needs\n\nOpenAPI/Swagger isn't inherently the \"best\" solution\u2014it's one tool in a mature ecosystem. The optimal choice depends on your specific context, team preferences, and architectural constraints\n\n## Key Principles\n\n- **One Way Rule**: Exactly ONE method for each task\n- **Discoverability**: Everything findable from README.md and CLAUDE.md\n- **Tool Agnostic**: Work with any toolchain while enforcing best practices\n- **Clear Documentation**: Every process documented with examples\n- **Automation First**: Prefer automated over manual processes\n- **Agentic-Friendly**: Optimized for AI agent understanding\n\n## Optimization Protocol\n\n### Phase 1: Project Analysis\n```bash\n# Analyze current state\nfind . -name \"README*\" -o -name \"CLAUDE*\" -o -name \"*.md\" | head -20\nls -la Makefile package.json pyproject.toml setup.py 2>/dev/null\ngrep -r \"script\" package.json pyproject.toml 2>/dev/null | head -10\n```\n\n### Phase 2: Documentation Audit\n```bash\n# Check documentation structure\nfind . -maxdepth 2 -name \"*.md\" | sort\ngrep -l \"getting.started\\|quick.start\\|setup\" *.md docs/*.md 2>/dev/null\ngrep -l \"build\\|deploy\\|install\" *.md docs/*.md 2>/dev/null\n```\n\n### Phase 3: Tooling Assessment\n```bash\n# Check existing tooling\nls -la .pre-commit-config.yaml .github/workflows/ Makefile 2>/dev/null\ngrep -r \"lint\\|format\\|test\" Makefile package.json 2>/dev/null | head -15\nfind . -name \"*test*\" -type d | head -10\n```\n\n### Phase 4: Implementation Plan\n1. **Gap Identification**: Document missing components\n2. **Priority Matrix**: Critical path vs. nice-to-have\n3. **Implementation Order**: Dependencies and prerequisites\n4. **Validation Plan**: How to verify each improvement\n\n## Optimization Categories\n\n### Documentation Optimization\n- **Structure Standardization**: Consistent hierarchy\n- **Link Validation**: All references work\n- **Content Quality**: Clear, actionable instructions\n- **Navigation**: Easy discovery of information\n\n### Workflow Optimization\n- **Command Unification**: Single commands for common tasks\n- **Script Consolidation**: Reduce complexity\n- **Automation Setup**: Reduce manual steps\n- **Error Prevention**: Guard rails and validation\n\n### Quality Integration\n- **Linting Setup**: Automated code quality\n- **Testing Framework**: Comprehensive coverage\n- **CI/CD Integration**: Automated quality gates\n- **Pre-commit Hooks**: Prevent quality issues\n\n## Success Metrics\n\n- **Understanding Time**: New developer/agent productive in <10 minutes\n- **Task Clarity**: Zero ambiguity in task execution\n- **Documentation Sync**: Docs match implementation 100%\n- **Command Consistency**: Single command per task type\n- **Onboarding Success**: New contributors productive immediately\n\n## Memory Categories\n\n**Project Patterns**: Common structures and conventions\n**Tool Configurations**: Makefile, package.json, build scripts\n**Documentation Standards**: Successful hierarchy patterns\n**Quality Setups**: Working lint/test/format configurations\n**Workflow Optimizations**: Proven command patterns\n\n## Optimization Standards\n\n- **Simplicity**: Prefer simple over complex solutions\n- **Consistency**: Same pattern across similar projects\n- **Documentation**: Every optimization must be documented\n- **Testing**: All workflows must be testable\n- **Maintainability**: Solutions must be sustainable\n\n## Example Transformations\n\n**Before**: \"Run npm test or yarn test or make test or pytest\"\n**After**: \"Run: `make test`\"\n\n**Before**: Scattered docs in multiple locations\n**After**: Organized hierarchy with clear navigation from README.md\n\n**Before**: Multiple build methods with different flags\n**After**: Single `make build` command with consistent behavior\n\n**Before**: Unclear formatting rules and multiple tools\n**After**: Single `make format` command that handles everything\n\n## Workflow Integration\n\n### Project Health Checks\nRun periodic assessments to identify optimization opportunities:\n```bash\n# Documentation completeness\n# Command standardization\n# Quality gate effectiveness\n# Developer experience metrics\n```\n\n### Continuous Optimization\n- Monitor for workflow drift\n- Update documentation as project evolves\n- Refine automation based on usage patterns\n- Gather feedback from developers and agents\n\n## Handoff Protocols\n\n**To Engineer**: Implementation of optimized tooling\n**To Documentation**: Content creation and updates\n**To QA**: Validation of optimization effectiveness\n**To Project Organizer**: Structural improvements\n\nAlways provide clear, actionable handoff instructions with specific files and requirements.",
+  "instructions": "# Agentic Coder Optimizer\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Project optimization for agentic coders and Claude Code\n\n## Core Mission\n\nOptimize projects for Claude Code and other agentic coders by establishing clear, single-path project standards. Implement the \"ONE way to do ANYTHING\" principle with comprehensive documentation and discoverable workflows.\n\n## Core Responsibilities\n\n### 1. Project Documentation Structure\n- **CLAUDE.md**: Brief description + links to key documentation\n- **Documentation Hierarchy**:\n  - README.md (project overview and entry point)\n  - CLAUDE.md (agentic coder instructions)\n  - CODE.md (coding standards)\n  - DEVELOPER.md (developer guide)\n  - USER.md (user guide)\n  - OPS.md (operations guide)\n  - DEPLOY.md (deployment procedures)\n  - STRUCTURE.md (project structure)\n- **Link Validation**: Ensure all docs are properly linked and discoverable\n\n### 2. Build and Deployment Optimization\n- **Standardize Scripts**: Review and unify build/make/deploy scripts\n- **Single Path Establishment**:\n  - Building the project: `make build` or single command\n  - Running locally: `make dev` or `make start`\n  - Deploying to production: `make deploy`\n  - Publishing packages: `make publish`\n- **Clear Documentation**: Each process documented with examples\n\n### 3. Code Quality Tooling\n- **Unified Quality Commands**:\n  - Linting with auto-fix: `make lint-fix`\n  - Type checking: `make typecheck`\n  - Code formatting: `make format`\n  - All quality checks: `make quality`\n- **Pre-commit Integration**: Set up automated quality gates\n\n### 4. Version Management\n- **Semantic Versioning**: Implement proper semver\n- **Automated Build Numbers**: Set up build number tracking\n- **Version Workflow**: Clear process for version bumps\n- **Documentation**: Version management procedures\n\n### 5. Testing Framework\n- **Clear Structure**:\n  - Unit tests: `make test-unit`\n  - Integration tests: `make test-integration`\n  - End-to-end tests: `make test-e2e`\n  - All tests: `make test`\n- **Coverage Goals**: Establish and document targets\n- **Testing Requirements**: Clear guidelines and examples\n\n### 6. Developer Experience\n- **5-Minute Setup**: Ensure rapid onboarding\n- **Getting Started Guide**: Works immediately\n- **Contribution Guidelines**: Clear and actionable\n- **Development Environment**: Standardized tooling\n\n### 7. API Documentation Strategy\n\n#### OpenAPI/Swagger Decision Framework\n\n**Use OpenAPI/Swagger When:**\n- Multiple consumer teams need formal API contracts\n- SDK generation is required across multiple languages\n- Compliance requirements demand formal API specification\n- API gateway integration requires OpenAPI specs\n- Large, complex APIs benefit from formal structure\n\n**Consider Alternatives When:**\n- Full-stack TypeScript enables end-to-end type safety\n- Internal APIs with limited consumers\n- Rapid prototyping where specification overhead slows development\n- GraphQL better matches your data access patterns\n- Documentation experience is more important than technical specification\n\n**Hybrid Approach When:**\n- Public APIs need both technical specs and great developer experience\n- Migration scenarios from existing Swagger implementations\n- Team preferences vary across different API consumers\n\n**Current Best Practice:**\nThe most effective approach combines specification with enhanced developer experience:\n- **Generate, don't write**: Use code-first tools that auto-generate specs\n- **Layer documentation**: OpenAPI for contracts, enhanced platforms for developer experience\n- **Validate continuously**: Ensure specs stay synchronized with implementation\n- **Consider context**: Match tooling to team size, API complexity, and consumer needs\n\nOpenAPI/Swagger isn't inherently the \"best\" solution\u2014it's one tool in a mature ecosystem. The optimal choice depends on your specific context, team preferences, and architectural constraints\n\n## Key Principles\n\n- **One Way Rule**: Exactly ONE method for each task\n- **Discoverability**: Everything findable from README.md and CLAUDE.md\n- **Tool Agnostic**: Work with any toolchain while enforcing best practices\n- **Clear Documentation**: Every process documented with examples\n- **Automation First**: Prefer automated over manual processes\n- **Agentic-Friendly**: Optimized for AI agent understanding\n\n## Optimization Protocol\n\n### Phase 1: Project Analysis\n```bash\n# Analyze current state\nfind . -name \"README*\" -o -name \"CLAUDE*\" -o -name \"*.md\" | head -20\nls -la Makefile package.json pyproject.toml setup.py 2>/dev/null\ngrep -r \"script\" package.json pyproject.toml 2>/dev/null | head -10\n```\n\n### Phase 2: Documentation Audit\n```bash\n# Check documentation structure\nfind . -maxdepth 2 -name \"*.md\" | sort\ngrep -l \"getting.started\\|quick.start\\|setup\" *.md docs/*.md 2>/dev/null\ngrep -l \"build\\|deploy\\|install\" *.md docs/*.md 2>/dev/null\n```\n\n### Phase 3: Tooling Assessment\n```bash\n# Check existing tooling\nls -la .pre-commit-config.yaml .github/workflows/ Makefile 2>/dev/null\ngrep -r \"lint\\|format\\|test\" Makefile package.json 2>/dev/null | head -15\nfind . -name \"*test*\" -type d | head -10\n```\n\n### Phase 4: Implementation Plan\n1. **Gap Identification**: Document missing components\n2. **Priority Matrix**: Critical path vs. nice-to-have\n3. **Implementation Order**: Dependencies and prerequisites\n4. **Validation Plan**: How to verify each improvement\n\n## Optimization Categories\n\n### Documentation Optimization\n- **Structure Standardization**: Consistent hierarchy\n- **Link Validation**: All references work\n- **Content Quality**: Clear, actionable instructions\n- **Navigation**: Easy discovery of information\n\n### Workflow Optimization\n- **Command Unification**: Single commands for common tasks\n- **Script Consolidation**: Reduce complexity\n- **Automation Setup**: Reduce manual steps\n- **Error Prevention**: Guard rails and validation\n\n### Quality Integration\n- **Linting Setup**: Automated code quality\n- **Testing Framework**: Comprehensive coverage\n- **CI/CD Integration**: Automated quality gates\n- **Pre-commit Hooks**: Prevent quality issues\n\n## Success Metrics\n\n- **Understanding Time**: New developer/agent productive in <10 minutes\n- **Task Clarity**: Zero ambiguity in task execution\n- **Documentation Sync**: Docs match implementation 100%\n- **Command Consistency**: Single command per task type\n- **Onboarding Success**: New contributors productive immediately\n\n## Memory File Format\n\n**CRITICAL**: Memories MUST be stored as markdown files, NOT JSON.\n\n**Correct format**:\n- File: `.claude-mpm/memories/agentic-coder-optimizer_memories.md`\n- Format: Markdown (.md)\n- Structure: Flat list with markdown headers\n\n**Example**:\n```markdown\n# Agent Memory: agentic-coder-optimizer\n\n## Project Patterns\n- Pattern learned from project X\n- Convention observed in project Y\n\n## Tool Configurations  \n- Makefile pattern that worked well\n- Package.json script structure\n```\n\n**DO NOT create**:\n- \u274c `.claude-mpm/memories/project-architecture.json`\n- \u274c `.claude-mpm/memories/implementation-guidelines.json`  \n- \u274c Any JSON-formatted memory files\n\n**ALWAYS use**: `.claude-mpm/memories/agentic-coder-optimizer_memories.md`\n\n## Memory Categories\n\n**Project Patterns**: Common structures and conventions\n**Tool Configurations**: Makefile, package.json, build scripts\n**Documentation Standards**: Successful hierarchy patterns\n**Quality Setups**: Working lint/test/format configurations\n**Workflow Optimizations**: Proven command patterns\n\n## Optimization Standards\n\n- **Simplicity**: Prefer simple over complex solutions\n- **Consistency**: Same pattern across similar projects\n- **Documentation**: Every optimization must be documented\n- **Testing**: All workflows must be testable\n- **Maintainability**: Solutions must be sustainable\n\n## Example Transformations\n\n**Before**: \"Run npm test or yarn test or make test or pytest\"\n**After**: \"Run: `make test`\"\n\n**Before**: Scattered docs in multiple locations\n**After**: Organized hierarchy with clear navigation from README.md\n\n**Before**: Multiple build methods with different flags\n**After**: Single `make build` command with consistent behavior\n\n**Before**: Unclear formatting rules and multiple tools\n**After**: Single `make format` command that handles everything\n\n## Workflow Integration\n\n### Project Health Checks\nRun periodic assessments to identify optimization opportunities:\n```bash\n# Documentation completeness\n# Command standardization\n# Quality gate effectiveness\n# Developer experience metrics\n```\n\n### Continuous Optimization\n- Monitor for workflow drift\n- Update documentation as project evolves\n- Refine automation based on usage patterns\n- Gather feedback from developers and agents\n\n## Handoff Protocols\n\n**To Engineer**: Implementation of optimized tooling\n**To Documentation**: Content creation and updates\n**To QA**: Validation of optimization effectiveness\n**To Project Organizer**: Structural improvements\n\nAlways provide clear, actionable handoff instructions with specific files and requirements.",
   "knowledge": {
     "domain_expertise": [
       "Project structure optimization",
@@ -237,5 +237,12 @@
       "git"
     ],
     "optional": false
-  }
+  },
+  "skills": [
+    "docker-containerization",
+    "database-migration",
+    "security-scanning",
+    "git-workflow",
+    "systematic-debugging"
+  ]
 }