# IDE Agent Schema Definition
# This schema defines the structure for IDE agent configuration files (.ide.md)
# IDE agents are self-contained, conversational agents with commands and specialized capabilities

type: object
required:
  - role
  - file_references
  - persona
  - core_principles
  - critical_startup_operating_instructions
  - commands

properties:
  role:
    type: string
    description: "The title/role name of the IDE agent"
    pattern: "^.+ IDE Agent$"
    examples:
      - "Product Manager IDE Agent"
      - "Business Analyst IDE Agent"
      - "Full Stack Developer IDE Agent"
    
  file_references:
    type: object
    description: "File paths and references used by the agent"
    required:
      - taskroot
    properties:
      taskroot:
        type: string
        description: "Root directory for task files"
        const: "bmad-core/tasks/"
      templates:
        type: string
        description: "Directory containing template files"
        const: "bmad-core/templates/"
      checklists:
        type: string
        description: "Directory containing checklists"
        const: "bmad-core/checklists/"
      default-template:
        type: string
        description: "Default template used by the agent"
        pattern: "^bmad-core/templates/.+$"
    additionalProperties: true
    
  persona:
    type: object
    required:
      - name
      - role
      - identity
      - focus
      - style
    properties:
      name:
        type: string
        description: "The agent's character name"
        examples: ["John", "Mary", "Sarah", "James", "Quinn", "Sally", "Winston", "Bob", "BMad"]
      role:
        type: string
        description: "The agent's professional role"
      identity:
        type: string
        description: "Extended description of the agent's specialization and expertise"
        minLength: 20
      focus:
        type: string
        description: "Primary objectives and responsibilities"
        minLength: 20
      style:
        type: string
        description: "Communication style and approach characteristics"
        minLength: 20
        
  core_principles:
    type: array
    description: "Always-active principles that guide the agent's behavior"
    minItems: 3
    contains:
      type: object
      properties:
        principle:
          const: "Numbered Options Protocol"
        description:
          pattern: ".*numbered lists.*easy selection.*"
    items:
      type: object
      required:
        - principle
        - description
      properties:
        principle:
          type: string
          description: "Brief principle title"
          pattern: "^[A-Z].*"
        description:
          type: string
          description: "Detailed explanation of the principle"
          minLength: 10
          
  critical_startup_operating_instructions:
    type: array
    description: "Instructions executed when the agent starts"
    minItems: 1
    items:
      type: string
      description: "Individual startup instruction"
    allOf:
      - description: "First instruction must announce name/role and mention *help"
        contains:
          type: string
          pattern: ".*(announce|Announce).*(name|role).*\\*help.*"
      
  commands:
    type: array
    description: "Available commands the agent can execute"
    minItems: 2
    contains:
      type: object
      properties:
        command:
          const: "*help"
        description:
          pattern: ".*numbered list.*selection.*"
    items:
      type: object
      required:
        - command
        - description
      properties:
        command:
          type: string
          pattern: "^\\*[a-z][a-z0-9-]*( \\{[^}]+\\})?$"
          description: "Command syntax (must start with *)"
        description:
          type: string
          description: "What the command does"
          minLength: 10
        parameters:
          type: array
          description: "Optional parameters for the command"
          items:
            type: string
            pattern: "^[a-z][a-z0-9-]*$"

# Optional properties for agent-specific capabilities
additionalProperties: true

# Additional optional sections that may appear
definitions:
  optional_sections:
    expertise:
      type: object
      description: "Technical expertise areas (commonly used by architect agents)"
      additionalProperties:
        type: string
    
    workflow:
      type: array
      description: "Step-by-step workflow description"
      items:
        type: string
    
    task_execution_protocol:
      type: object
      description: "Detailed protocol for task execution (commonly used by dev agents)"
      additionalProperties: true
    
    agent_transformation_protocol:
      type: object
      description: "Protocol for transforming into other agents (used by BMAD orchestrator)"
      additionalProperties: true

# Validation rules
allOf:
  # Ensure common commands are properly formatted
  - if:
      properties:
        commands:
          contains:
            properties:
              command:
                const: "*chat-mode"
    then:
      properties:
        commands:
          contains:
            properties:
              description:
                pattern: ".*(conversational mode|advanced-elicitation).*"

  # Ensure create commands reference tasks
  - if:
      properties:
        commands:
          contains:
            properties:
              command:
                pattern: "^\\*create-"
    then:
      properties:
        commands:
          contains:
            properties:
              description:
                pattern: ".*(task|create-doc).*"

# Examples showing valid IDE agent configurations
examples:
  product_manager:
    role: "Product Manager IDE Agent"
    file_references:
      taskroot: "bmad-core/tasks/"
      templates: "bmad-core/templates/"
      default-template: "bmad-core/templates/prd-tmpl"
    persona:
      name: "John"
      role: "Product Manager"
      identity: "Product Manager specialized in document creation and product research"
      focus: "Creating Product Requirements Documents (PRDs) and other product documentation using templates"
      style: "Analytical, inquisitive, data-driven, user-focused, pragmatic"
    core_principles:
      - principle: "User-Focused Requirements"
        description: "All requirements must center on user needs and value"
      - principle: "Clear Success Metrics"
        description: "Define measurable outcomes for all features"
      - principle: "Numbered Options Protocol"
        description: "When presenting multiple options, use numbered lists for easy selection"
    critical_startup_operating_instructions:
      - "Announce your name and role, and let user know they can say *help at any time"
    commands:
      - command: "*help"
        description: "Show these available commands as a numbered list offering selection"
      - command: "*chat-mode"
        description: "Enter conversational mode with advanced-elicitation options"
      - command: "*create-doc {template-name}"
        description: "Run task create-doc with specified template"
        parameters: ["template-name"]