# BMAD Agent Configuration Schema
# This schema defines the structure for BMAD agent configuration files
# Agents can either reference an external persona or embed the persona directly

type: object
required:
  - agent
  - dependencies

properties:
  agent:
    type: object
    description: Core agent configuration and metadata
    required:
      - name
      - id
      - title
      - description
      - customize
    properties:
      name:
        type: string
        description: Human-friendly character name of the agent
        pattern: "^[A-Z][a-z]+$"
        examples:
          - "John"
          - "Mary"
          - "Sarah"
          - "James"
          - "Quinn"
          - "Sally"
          - "Winston"
          - "Bob"
          - "BMad"
      
      id:
        type: string
        description: Unique identifier for the agent (lowercase, hyphenated)
        pattern: "^[a-z][a-z0-9-]*$"
        examples:
          - "pm"
          - "analyst"
          - "architect"
          - "po"
          - "sm"
          - "dev"
          - "qa"
          - "ux-expert"
          - "bmad"
      
      title:
        type: string
        description: Professional title or role
        minLength: 5
        maxLength: 50
        examples:
          - "Product Manager"
          - "Business Analyst"
          - "Architect"
          - "Product Owner"
          - "Scrum Master"
          - "Full Stack Developer"
          - "QA Engineer"
          - "UX Expert"
      
      description:
        type: string
        description: Main goal and purpose of the agent
        minLength: 20
        maxLength: 300
      
      persona:
        oneOf:
          - type: string
            description: Reference to external persona file
            pattern: "^bmad-core/personas/[a-z][a-z0-9-]*\\.md$"
          - type: "null"
            description: Null when using embedded persona
      
      customize:
        type: string
        description: Customization instructions or embedded persona definition
        default: ""
      
      startup:
        type: array
        description: Startup instructions for the agent (required when persona is null)
        items:
          type: string
          minLength: 20

  dependencies:
    type: object
    description: Resources required by this agent
    required:
      - tasks
      - templates
      - checklists
      - data
      - utils
    properties:
      tasks:
        type: array
        description: List of task files from bmad-core/tasks/
        items:
          type: string
          pattern: "^[a-z][a-z0-9-]*$"
        uniqueItems: true
      
      templates:
        type: array
        description: List of template files from bmad-core/templates/
        items:
          type: string
          pattern: "^[a-z][a-z0-9-]*-tmpl$"
        uniqueItems: true
      
      checklists:
        type: array
        description: List of checklist files from bmad-core/checklists/
        items:
          type: string
          pattern: "^[a-z][a-z0-9-]*-checklist$"
        uniqueItems: true
      
      data:
        type: array
        description: List of data files from bmad-core/data/
        items:
          type: string
          pattern: "^[a-z][a-z0-9-]*$"
        uniqueItems: true
      
      utils:
        type: array
        description: List of utility files from bmad-core/utils/
        items:
          type: string
          pattern: "^[a-z][a-z0-9-]*$"
        uniqueItems: true

# No additional properties allowed
additionalProperties: false

# Validation rules
allOf:
  # When persona is null, customize must contain embedded persona and startup must be provided
  - if:
      properties:
        agent:
          properties:
            persona:
              type: "null"
    then:
      properties:
        agent:
          required:
            - startup
          properties:
            customize:
              minLength: 200
              description: "Must contain comprehensive persona definition when persona is null"
            startup:
              minItems: 1
              description: "Startup instructions required for embedded personas"
  
  # When persona is provided, startup is optional
  - if:
      properties:
        agent:
          properties:
            persona:
              type: string
    then:
      properties:
        agent:
          properties:
            customize:
              maxLength: 500
              description: "Keep customizations brief when using external persona"

# Examples showing valid agent configurations
examples:
  # Agent with external persona
  external_persona_agent:
    agent:
      name: "John"
      id: "pm"
      title: "Product Manager"
      description: "Creates Product Requirements Documents (PRDs) and conducts product research to define product strategy"
      persona: "bmad-core/personas/pm.md"
      customize: ""
      startup:
        - "Let the User Know what Tasks you can perform in a numbered list for user selection."
        - "Execute the Full Tasks as Selected."
    dependencies:
      tasks:
        - "create-doc-from-template"
        - "advanced-elicitation"
        - "shard-doc"
      templates:
        - "prd-tmpl"
        - "project-brief-tmpl"
      checklists:
        - "pm-checklist"
      data:
        - "bmad-kb"
      utils:
        - "template-format"

  # Agent with embedded persona
  embedded_persona_agent:
    agent:
      name: "Elena"
      id: "data-analyst"
      title: "Data Analyst"
      description: "Analyzes data patterns, creates visualizations, and provides insights for data-driven decision making"
      persona: null
      customize: >-
        Elena is a meticulous Data Analyst with expertise in statistical analysis, data visualization, 
        and pattern recognition. She approaches problems with scientific rigor, always seeking evidence 
        in the data before drawing conclusions. Her style is precise, methodical, and focused on 
        delivering actionable insights. She excels at transforming complex data into clear narratives 
        that stakeholders can understand and act upon. Core principles include: data integrity above all, 
        correlation doesn't imply causation, visualizations should tell a story, and always validate 
        findings with multiple data sources.
      startup:
        - "Let the User Know what Tasks you can perform in a numbered list for user selection."
        - "Focus on data-driven insights and evidence-based recommendations."
        - "Always ask for data sources and context before beginning analysis."
    dependencies:
      tasks:
        - "analyze-data"
        - "create-visualization"
        - "statistical-analysis"
      templates:
        - "data-report-tmpl"
        - "dashboard-tmpl"
      checklists:
        - "data-quality-checklist"
      data:
        - "statistical-methods"
      utils:
        - "data-tools"