{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "version": "1.3.0",
  "title": "Claude MPM Agent Schema",
  "description": "Schema definition for Claude MPM agent templates. This schema enforces the structure and validation rules for all agent configurations in the Claude MPM system.",
  "type": "object",
  "required": [
    "schema_version",
    "agent_id",
    "agent_version",
    "agent_type",
    "metadata",
    "capabilities",
    "instructions"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Schema version for the agent template format. This ensures compatibility between the agent template and the schema validator. Must be updated when breaking changes are made to the schema.",
      "examples": ["1.0.0", "1.2.0", "1.3.0"]
    },
    "agent_id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]*$",
      "description": "Unique agent identifier used for agent discovery and loading. This ID must be unique across all agents in the system and follows kebab-case or snake_case naming convention.",
      "examples": ["research-agent", "engineer-agent", "qa-agent", "security-agent", "research_agent", "engineer_agent"]
    },
    "agent_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Semantic version of the agent template itself (not the schema). Increment major for breaking changes, minor for new features, patch for bug fixes.",
      "examples": ["1.0.0", "2.1.3"]
    },
    "agent_type": {
      "type": "string",
      "description": "Type of agent that determines its primary function and default capabilities. This categorization helps in agent discovery and capability matching.",
      "enum": [
        "base",
        "engineer",
        "qa",
        "documentation",
        "research",
        "security",
        "ops",
        "data_engineer",
        "version_control",
        "system",
        "refactoring",
        "memory_manager"
      ]
    },
    "metadata": {
      "type": "object",
      "required": [
        "name",
        "description",
        "tags"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 3,
          "maxLength": 50,
          "description": "Human-readable agent name displayed in UI and logs. Should be concise but descriptive."
        },
        "description": {
          "type": "string",
          "minLength": 10,
          "maxLength": 250,
          "description": "Brief description of agent purpose and capabilities. Used in agent selection and documentation."
        },
        "category": {
          "type": "string",
          "enum": ["engineering", "research", "quality", "operations", "specialized", "system", "project-management", "infrastructure"],
          "description": "Agent category for organization"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
          },
          "minItems": 1,
          "maxItems": 10,
          "uniqueItems": true,
          "description": "Tags for agent discovery and categorization. Used by the agent registry for searching and filtering."
        },
        "author": {
          "type": "string",
          "description": "Agent template author"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Creation timestamp"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Last update timestamp"
        },
        "color": {
          "type": "string",
          "enum": ["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan", "indigo", "gray", "black", "white"],
          "description": "Agent color for visual identification in Claude Code interface. Helps distinguish agents at a glance."
        },
        "version": {
          "type": "string",
          "pattern": "^\\d+\\.\\d+\\.\\d+$",
          "description": "Agent metadata version for tracking changes"
        },
        "status": {
          "type": "string",
          "enum": ["stable", "experimental", "deprecated", "development"],
          "description": "Current status of the agent template"
        }
      }
    },
    "template_version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Template version tracking independent of agent version. Used for tracking template improvements and optimizations.",
      "examples": ["1.0.0", "1.4.0", "2.2.0"]
    },
    "template_changelog": {
      "type": "array",
      "description": "Template version history tracking changes and improvements",
      "items": {
        "type": "object",
        "required": ["version", "date", "description"],
        "properties": {
          "version": {
            "type": "string",
            "pattern": "^\\d+\\.\\d+\\.\\d+$",
            "description": "Template version for this changelog entry"
          },
          "date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Date of the template version release in YYYY-MM-DD format"
          },
          "description": {
            "type": "string",
            "description": "Description of changes in this template version"
          }
        }
      }
    },
    "dependencies": {
      "type": "object",
      "description": "External dependencies required for this agent to function properly",
      "properties": {
        "python": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Python packages required (pip installable) with optional version specifiers",
          "examples": [["tree-sitter>=0.21.0", "pandas>=2.0.0"]]
        },
        "python_optional": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optional Python packages that enhance agent functionality but are not required for core operations",
          "examples": [["locust>=2.15.0", "selenium>=4.0.0"]]
        },
        "system": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "System-level dependencies (e.g., commands that should be available in PATH)",
          "examples": [["ripgrep", "git", "docker"]]
        },
        "optional": {
          "type": "boolean",
          "default": false,
          "description": "Whether these dependencies are optional (agent can function without them)"
        }
      }
    },
    "capabilities": {
      "type": "object",
      "required": [
        "model",
        "resource_tier"
      ],
      "properties": {
        "model": {
          "type": "string",
          "enum": [
            "opus",
            "sonnet",
            "haiku"
          ],
          "description": "Claude model tier to use for this agent. Choose based on task complexity and performance requirements: opus (most capable), sonnet (balanced), haiku (fastest)."
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "Read",
              "Write",
              "Edit",
              "MultiEdit",
              "Grep",
              "Glob",
              "LS",
              "Bash",
              "WebSearch",
              "WebFetch",
              "NotebookRead",
              "NotebookEdit",
              "TodoWrite",
              "ExitPlanMode",
              "git",
              "docker",
              "kubectl",
              "terraform",
              "aws",
              "gcloud",
              "azure",
              "mcp__claude-mpm-gateway__document_summarizer",
              "mcp__claude-mpm-gateway__ticket",
              "mcp__mcp-vector-search__search_code",
              "mcp__mcp-vector-search__search_similar",
              "mcp__mcp-vector-search__search_context",
              "mcp__mcp-vector-search__get_project_status",
              "mcp__mcp-vector-search__index_project"
            ]
          },
          "uniqueItems": true,
          "description": "Available tools for the agent. Tools determine what operations the agent can perform."
        },
        "resource_tier": {
          "type": "string",
          "enum": [
            "basic",
            "standard",
            "intensive",
            "lightweight",
            "high"
          ],
          "description": "Resource allocation tier that determines memory, CPU, and timeout limits. See definitions section for specific limits."
        },
        "max_tokens": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 200000,
          "default": 8192,
          "description": "Maximum tokens for response generation. Higher values allow longer responses but increase cost and latency."
        },
        "temperature": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.7,
          "description": "Model temperature setting controlling response randomness. Lower values for consistency, higher for creativity."
        },
        "timeout": {
          "type": "integer",
          "minimum": 30,
          "maximum": 3600,
          "default": 300,
          "description": "Operation timeout in seconds. Should align with resource_tier settings."
        },
        "memory_limit": {
          "type": "integer",
          "minimum": 512,
          "maximum": 8192,
          "description": "Memory limit in MB (for resource tier)"
        },
        "cpu_limit": {
          "type": "integer",
          "minimum": 10,
          "maximum": 100,
          "description": "CPU limit percentage (for resource tier)"
        },
        "network_access": {
          "type": "boolean",
          "default": false,
          "description": "Whether agent needs network access"
        },
        "file_access": {
          "type": "object",
          "properties": {
            "read_paths": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Allowed read paths"
            },
            "write_paths": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Allowed write paths"
            }
          }
        },
        "allowed_tools": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Glob patterns for allowed file paths. Restricts which files the agent can access (e.g., 'tests/**' for test files only)."
        },
        "disallowed_tools": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Tool names to explicitly disallow, overriding the tools array. Use for security restrictions (e.g., 'Bash' to prevent shell access)."
        },
        "limits": {
          "type": "object",
          "description": "Explicit resource limits for the agent",
          "properties": {
            "memory_limit": {
              "type": "integer",
              "minimum": 512,
              "maximum": 8192,
              "description": "Memory limit in MB"
            },
            "cpu_limit": {
              "type": "integer",
              "minimum": 10,
              "maximum": 100,
              "description": "CPU limit percentage"
            },
            "max_file_size": {
              "type": "integer",
              "minimum": 1024,
              "description": "Maximum file size in bytes that can be processed"
            },
            "max_files_per_session": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of files that can be accessed per session"
            }
          }
        },
        "tool_choice": {
          "type": "string",
          "enum": ["auto", "required", "none"],
          "default": "auto",
          "description": "Tool usage strategy for the agent"
        }
      }
    },
    "instructions": {
      "type": "string",
      "minLength": 10,
      "maxLength": 8000,
      "description": "Agent system instructions that define behavior, approach, and constraints. This becomes the agent's system prompt."
    },
    "knowledge": {
      "type": "object",
      "description": "Agent-specific knowledge and context",
      "properties": {
        "domain_expertise": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Areas of expertise"
        },
        "best_practices": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Best practices the agent follows"
        },
        "constraints": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Operating constraints"
        },
        "examples": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "scenario": {"type": "string"},
              "approach": {"type": "string"}
            }
          },
          "description": "Example scenarios and approaches"
        }
      }
    },
    "interactions": {
      "type": "object",
      "description": "Agent interaction patterns and protocols",
      "properties": {
        "input_format": {
          "type": "object",
          "properties": {
            "required_fields": {
              "type": "array",
              "items": {"type": "string"}
            },
            "optional_fields": {
              "type": "array",
              "items": {"type": "string"}
            },
            "supported_operations": {
              "type": "array",
              "items": {"type": "string"},
              "description": "List of supported operations for this agent"
            }
          }
        },
        "output_format": {
          "type": "object",
          "properties": {
            "structure": {
              "type": "string",
              "enum": ["markdown", "json", "structured", "free-form"]
            },
            "includes": {
              "type": "array",
              "items": {"type": "string"}
            },
            "example": {
              "type": "string",
              "description": "Example output format for the agent"
            }
          }
        },
        "handoff_agents": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Agents this agent can hand off to"
        },
        "triggers": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "string",
                "description": "Simple trigger condition"
              },
              {
                "type": "object",
                "properties": {
                  "condition": {"type": "string"},
                  "action": {"type": "string"}
                },
                "description": "Complex trigger with condition and action"
              }
            ]
          },
          "description": "Conditions that trigger specific actions or agent activation"
        },
        "protocols": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Communication protocols supported by this agent"
        },
        "response_format": {
          "type": "object",
          "description": "Detailed response format specifications",
          "properties": {
            "type": {
              "type": "string",
              "enum": ["markdown", "json", "structured", "mixed"]
            },
            "template": {"type": "string"},
            "required_sections": {
              "type": "array",
              "items": {"type": "string"}
            }
          }
        }
      }
    },
    "testing": {
      "type": "object",
      "description": "Testing configuration for the agent",
      "properties": {
        "test_cases": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["input", "expected_behavior"],
            "properties": {
              "name": {"type": "string"},
              "input": {"type": "string"},
              "expected_behavior": {"type": "string"},
              "validation_criteria": {
                "type": "array",
                "items": {"type": "string"}
              }
            }
          }
        },
        "performance_benchmarks": {
          "type": "object",
          "properties": {
            "response_time": {"type": "integer"},
            "token_usage": {"type": "integer"},
            "success_rate": {"type": "number"},
            "validation_accuracy": {"type": "number"}
          }
        },
        "integration_tests": {
          "type": "array",
          "items": {"type": "string"},
          "description": "List of integration test scenarios"
        }
      }
    },
    "memory_routing": {
      "type": "object",
      "description": "Memory system routing configuration for agent",
      "properties": {
        "description": {
          "type": "string",
          "description": "Description of what memories this agent stores"
        },
        "categories": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Memory categories this agent contributes to"
        },
        "keywords": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Keywords for memory routing and retrieval"
        },
        "retention_policy": {
          "type": "string",
          "enum": ["permanent", "session", "temporary"],
          "description": "Memory retention policy for this agent"
        }
      }
    },
    "hooks": {
      "type": "object",
      "description": "Hook configurations for extensibility",
      "properties": {
        "pre_execution": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "enabled": {"type": "boolean"}
            }
          }
        },
        "post_execution": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "enabled": {"type": "boolean"}
            }
          }
        }
      }
    }
  },
  "additionalProperties": true,
  "definitions": {
    "model_mappings": {
      "description": "Mappings for model normalization from full names to tiers",
      "mappings": {
        "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",
        "claude-3-opus-20240229": "opus",
        "claude-opus-4-20250514": "opus",
        "claude-4-opus-20250514": "opus",
        "claude-3-haiku-20240307": "haiku",
        "claude-3-5-haiku-20241022": "haiku"
      }
    },
    "resource_tier_limits": {
      "intensive": {
        "memory_limit": {"min": 4096, "max": 8192},
        "cpu_limit": {"min": 60, "max": 100},
        "timeout": {"min": 600, "max": 3600}
      },
      "standard": {
        "memory_limit": {"min": 2048, "max": 4096},
        "cpu_limit": {"min": 30, "max": 60},
        "timeout": {"min": 300, "max": 1200}
      },
      "lightweight": {
        "memory_limit": {"min": 512, "max": 2048},
        "cpu_limit": {"min": 10, "max": 30},
        "timeout": {"min": 30, "max": 600}
      }
    }
  }
}
