{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://codingbuddy.dev/schemas/agent.schema.json",
  "title": "Codingbuddy Agent Definition",
  "description": "Schema for AI agent definition files in .ai-rules/agents/",
  "type": "object",
  "required": ["name", "description", "role", "context_files"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Display name of the agent",
      "minLength": 1,
      "examples": ["Frontend Developer", "Code Reviewer", "Security Specialist"]
    },
    "description": {
      "type": "string",
      "description": "Brief description of the agent's purpose and expertise",
      "minLength": 10
    },
    "model": {
      "type": "object",
      "description": "Preferred AI model configuration",
      "properties": {
        "preferred": {
          "type": "string",
          "description": "Preferred model identifier (e.g., claude-sonnet-4-20250514)"
        },
        "reason": {
          "type": "string",
          "description": "Reason for model selection"
        }
      }
    },
    "role": {
      "type": "object",
      "description": "Agent's role definition including title, expertise, and responsibilities",
      "required": ["title"],
      "properties": {
        "title": {
          "type": "string",
          "description": "Official role title",
          "minLength": 1
        },
        "type": {
          "type": "string",
          "enum": ["primary", "specialist", "utility"],
          "description": "Agent type: 'primary' uses top-level activation for PLAN/ACT workflow, 'specialist' uses modes for domain-specific guidance, 'utility' is for mode agents (PLAN/ACT/EVAL/AUTO). RECOMMENDED: Always specify for new agents to ensure proper workflow integration."
        },
        "expertise": {
          "type": "array",
          "description": "List of expertise areas",
          "items": { "type": "string" },
          "minItems": 1
        },
        "responsibilities": {
          "type": "array",
          "description": "List of responsibilities",
          "items": { "type": "string" }
        },
        "tech_stack_reference": {
          "type": "string",
          "description": "Reference to tech stack documentation"
        }
      },
      "additionalProperties": true
    },
    "context_files": {
      "type": "array",
      "description": "List of context files to load for this agent",
      "items": {
        "type": "string",
        "pattern": "^\\.ai-rules/.*"
      },
      "minItems": 1,
      "examples": [[".ai-rules/rules/core.md", ".ai-rules/rules/project.md"]]
    },
    "activation": {
      "type": "object",
      "description": "Activation configuration for developer/reviewer agents",
      "properties": {
        "trigger": {
          "type": "string",
          "description": "Condition that triggers this agent"
        },
        "rule": {
          "type": "string",
          "description": "Strict rule for activation"
        },
        "mandatory_checklist": {
          "type": "object",
          "description": "Checklist items that must be followed",
          "additionalProperties": true
        },
        "verification_guide": {
          "type": "object",
          "description": "Guide for verifying checklist items",
          "additionalProperties": { "type": "string" }
        },
        "execution_order": {
          "type": "object",
          "description": "Order of execution for different modes",
          "additionalProperties": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "workflow_integration": {
          "type": "object",
          "description": "How this agent integrates with workflow",
          "properties": {
            "trigger_conditions": {
              "type": "array",
              "description": "Semantic conditions that trigger agent activation",
              "items": { "type": "string" }
            },
            "file_pattern_triggers": {
              "type": "array",
              "description": "Glob patterns for files that trigger agent activation (e.g., '**/*.llm.ts', '**/prompts/**')",
              "items": { "type": "string" }
            },
            "activation_rule": {
              "type": "string",
              "description": "Rule describing when this agent must be activated"
            },
            "output_format": {
              "type": "string",
              "description": "Expected output format for this agent"
            }
          }
        },
        "planning_framework": {
          "type": "object",
          "description": "Framework for planning mode"
        },
        "implementation_framework": {
          "type": "object",
          "description": "Framework for implementation mode"
        }
      },
      "additionalProperties": true
    },
    "modes": {
      "type": "object",
      "description": "Mode-specific configuration for specialist agents",
      "properties": {
        "planning": {
          "type": "object",
          "description": "Planning mode configuration"
        },
        "implementation": {
          "type": "object",
          "description": "Implementation mode configuration"
        },
        "evaluation": {
          "type": "object",
          "description": "Evaluation mode configuration"
        }
      },
      "additionalProperties": true
    },
    "workflow": {
      "type": "object",
      "description": "Workflow configuration",
      "additionalProperties": true
    },
    "development_philosophy": {
      "type": "object",
      "description": "Development philosophy and approach",
      "additionalProperties": true
    },
    "code_quality_checklist": {
      "type": "array",
      "description": "Code quality checklist items",
      "items": { "type": "string" }
    },
    "tdd_cycle": {
      "type": "object",
      "description": "TDD cycle configuration",
      "additionalProperties": true
    },
    "ai_monitoring": {
      "type": "object",
      "description": "AI behavior monitoring configuration",
      "additionalProperties": true
    },
    "commit_rules": {
      "type": "object",
      "description": "Commit rules and discipline",
      "additionalProperties": true
    },
    "design_system": {
      "type": "object",
      "description": "Design system configuration",
      "additionalProperties": true
    },
    "communication": {
      "type": "object",
      "description": "Communication preferences",
      "properties": {
        "language": {
          "type": "string",
          "description": "Response language preference"
        },
        "approach": {
          "type": "array",
          "items": { "type": "string" }
        },
        "reference_style": {
          "type": "string"
        },
        "emphasis": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "file_naming": {
      "type": "object",
      "description": "File naming conventions",
      "additionalProperties": true
    },
    "reference": {
      "type": "object",
      "description": "Reference links and documentation",
      "additionalProperties": true
    },
    "shared_framework": {
      "type": "object",
      "description": "Shared framework configuration for specialist agents",
      "additionalProperties": true
    },
    "persona": {
      "type": "object",
      "description": "Agent persona configuration",
      "additionalProperties": true
    },
    "evaluation_framework": {
      "type": "object",
      "description": "Evaluation framework for reviewer agents",
      "additionalProperties": true
    },
    "evaluation_output_format": {
      "type": "object",
      "description": "Output format for evaluations",
      "additionalProperties": true
    },
    "evaluation_checklist": {
      "type": "object",
      "description": "Evaluation checklist",
      "additionalProperties": true
    },
    "improvement_prioritization": {
      "type": "object",
      "description": "Improvement prioritization rules",
      "additionalProperties": true
    },
    "workflow_integration": {
      "type": "object",
      "description": "Workflow integration configuration",
      "additionalProperties": true
    },
    "research_requirements": {
      "type": "object",
      "description": "Research requirements for evidence-based recommendations",
      "additionalProperties": true
    },
    "quality_gates": {
      "type": "object",
      "description": "Quality gate definitions",
      "additionalProperties": true
    },
    "infrastructure": {
      "type": "object",
      "description": "Infrastructure configuration (DevOps)",
      "additionalProperties": true
    },
    "best_practices": {
      "type": "object",
      "description": "Best practices guidelines",
      "additionalProperties": true
    },
    "checklist": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": { "type": "string" }
        }
      ],
      "description": "General checklist (can be object or array)"
    },
    "visual": {
      "type": "object",
      "description": "Visual identity for the agent character system",
      "required": ["eye", "eyeFallback", "colorAnsi", "group"],
      "properties": {
        "eye": {
          "type": "string",
          "description": "Unicode symbol representing the agent's eye/icon",
          "minLength": 1
        },
        "eyeFallback": {
          "type": "string",
          "description": "ASCII fallback character for terminals without Unicode support",
          "minLength": 1,
          "maxLength": 1
        },
        "colorAnsi": {
          "type": "string",
          "enum": ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "bright"],
          "description": "ANSI color name for terminal rendering"
        },
        "group": {
          "type": "string",
          "enum": [
            "workflow",
            "architecture",
            "quality",
            "security",
            "frontend",
            "backend",
            "integration",
            "specialist"
          ],
          "description": "Domain group for visual categorization"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": true
}