> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Definition Files

> Complete reference for AIOX agent definition structure and YAML schema

## Overview

AIOX agents are defined in **markdown files with embedded YAML blocks**. Each agent combines persona configuration, command definitions, dependencies, and activation instructions in a single, self-contained file.

<ParamField path="Location" type="string">
  `.aiox-core/development/agents/*.md`
</ParamField>

<ParamField path="Format" type="string">
  Markdown with YAML frontmatter
</ParamField>

<ParamField path="Extension" type="string">
  `.md` (Markdown)
</ParamField>

## File Structure

Agent files follow a **strict structure** with YAML configuration block:

````markdown theme={null}
# {agent-id}

ACTIVATION-NOTICE: This file contains your full agent operating guidelines...

CRITICAL: Read the full YAML BLOCK that FOLLOWS...

## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED

```yaml
IDE-FILE-RESOLUTION:
  # Dependency resolution rules

REQUEST-RESOLUTION:
  # Command matching rules

activation-instructions:
  # Activation steps

agent:
  # Agent metadata

persona_profile:
  # Communication style

persona:
  # Role and behavior

commands:
  # Available commands

dependencies:
  # Required files
````

````

## Schema Reference

### Agent Metadata

<ParamField path="agent" type="object" required>
  Core agent identification and metadata
  
  <Expandable title="properties">
    <ResponseField name="name" type="string" required>
      Human-friendly agent name
      
      Example: `"Dex"`, `"Aria"`, `"Quinn"`
    </ResponseField>
    
    <ResponseField name="id" type="string" required>
      Unique agent identifier (slug format)
      
      Example: `"dev"`, `"architect"`, `"qa"`
    </ResponseField>
    
    <ResponseField name="title" type="string" required>
      Agent role title
      
      Example: `"Full Stack Developer"`, `"Architect"`
    </ResponseField>
    
    <ResponseField name="icon" type="string" required>
      Emoji icon representing the agent
      
      Example: `"💻"`, `"🏛️"`, `"🧪"`
    </ResponseField>
    
    <ResponseField name="whenToUse" type="string" required>
      Guidance on when to activate this agent
      
      Multi-line description of agent's primary use cases and delegation patterns.
    </ResponseField>
    
    <ResponseField name="customization" type="string">
      Custom behavior overrides (takes precedence over all other instructions)
    </ResponseField>
  </Expandable>
</ParamField>

### Persona Profile

<ParamField path="persona_profile" type="object" required>
  Agent communication style and personality
  
  <Expandable title="properties">
    <ResponseField name="archetype" type="string" required>
      Agent archetype: `"Builder"`, `"Visionary"`, `"Guardian"`, `"Analyst"`
    </ResponseField>
    
    <ResponseField name="zodiac" type="string">
      Zodiac sign for personality reference
      
      Example: `"♒ Aquarius"`, `"♐ Sagittarius"`
    </ResponseField>
    
    <ResponseField name="communication" type="object" required>
      Communication style configuration
      
      <Expandable title="communication properties">
        <ResponseField name="tone" type="string" required>
          Communication tone: `"pragmatic"`, `"conceptual"`, `"analytical"`
        </ResponseField>
        
        <ResponseField name="emoji_frequency" type="string" required>
          Emoji usage level: `"low"`, `"medium"`, `"high"`
        </ResponseField>
        
        <ResponseField name="vocabulary" type="array" required>
          List of preferred vocabulary words used by the agent (e.g., construir, implementar, refatorar)
        </ResponseField>

        <ResponseField name="greeting_levels" type="object" required>
          Agent greeting variations with minimal, named, and archetypal levels
        </ResponseField>
        
        <ResponseField name="signature_closing" type="string" required>
          Agent signature closing message
          
          Example: `"— Dex, sempre construindo 🔨"`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

### Persona Behavior

<ParamField path="persona" type="object" required>
  Agent role, behavior, and operating principles
  
  <Expandable title="properties">
    <ResponseField name="role" type="string" required>
      Agent's primary role
      
      Example: `"Expert Senior Software Engineer & Implementation Specialist"`
    </ResponseField>
    
    <ResponseField name="style" type="string" required>
      Working style description
      
      Example: `"Extremely concise, pragmatic, detail-oriented"`
    </ResponseField>
    
    <ResponseField name="identity" type="string" required>
      Core identity statement
    </ResponseField>
    
    <ResponseField name="focus" type="string" required>
      Primary focus areas
    </ResponseField>
    
    <ResponseField name="core_principles" type="array">
      List of operating principles
      
      Each item is a string principle like `"Story has ALL info needed"` or `"ONLY update Dev Agent Record sections"`
    </ResponseField>
    
    <ResponseField name="responsibility_boundaries" type="object">
      Delegation and collaboration patterns
      
      <Expandable title="responsibility_boundaries">
        <ResponseField name="primary_scope" type="array">
          Agent's primary responsibilities as array of strings
        </ResponseField>
        
        <ResponseField name="delegate_to_{agent}" type="object">
          When to delegate to other agents. Each delegation object contains `when` (array), `retain` (array), and `collaboration_pattern` (string) fields.
          
          Example delegation: `delegate_to_data_engineer` with `when: ["Database schema design", "Query optimization"]`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

### Activation Instructions

<ParamField path="activation-instructions" type="array" required>
  Step-by-step activation sequence
  
  Defines how the agent should activate, display greeting, and prepare for work. Each item is a string instruction like `"STEP 1: Read THIS ENTIRE FILE"` or `"STEP 5: HALT and await user input"`
</ParamField>

### Commands

<ParamField path="commands" type="array" required>
  Available agent commands
  
  <Expandable title="command schema">
    <ResponseField name="name" type="string" required>
      Command name (without `*` prefix)
      
      Example: `"help"`, `"develop"`, `"create-service"`
    </ResponseField>
    
    <ResponseField name="visibility" type="array" required>
      Visibility levels: `["full", "quick", "key"]`
      
      - `key` - Most important commands (shown in greeting)
      - `quick` - Frequently used commands
      - `full` - All commands (shown in `*help`)
    </ResponseField>
    
    <ResponseField name="description" type="string" required>
      Command description
    </ResponseField>
  </Expandable>
</ParamField>

### Dependencies

<ParamField path="dependencies" type="object" required>
  External files required by agent
  
  <Expandable title="dependency categories">
    <ResponseField name="checklists" type="array">
      Quality gate checklists
      
      Array of filenames like `["story-dod-checklist.md", "self-critique-checklist.md"]`
    </ResponseField>
    
    <ResponseField name="tasks" type="array">
      Executable task workflows
      
      Array of filenames like `["dev-develop-story.md", "create-service.md", "qa-fix-issues.md"]`
    </ResponseField>
    
    <ResponseField name="templates" type="array">
      File generation templates
      
      Array of filenames or directories like `["story-template.md", "service-template/"]`
    </ResponseField>
    
    <ResponseField name="scripts" type="array">
      JavaScript/Node.js scripts
      
      Array of filenames like `["recovery-tracker.js", "build-orchestrator.js"]`
    </ResponseField>
    
    <ResponseField name="tools" type="array">
      External tools and MCP servers
      
      Array of tool names like `["coderabbit", "git", "context7"]`
    </ResponseField>
  </Expandable>
</ParamField>

## File Resolution Rules

<ParamField path="IDE-FILE-RESOLUTION" type="array">
  Rules for resolving dependency file paths
  
  Dependencies map to `.aiox-core/development/{type}/{name}` where:
  - `type` = folder (tasks, templates, checklists, data, utils)
  - `name` = file name
  
  Example: `create-doc.md` → `.aiox-core/development/tasks/create-doc.md`
</ParamField>

<ParamField path="REQUEST-RESOLUTION" type="string">
  Rules for matching user requests to commands
  
  Example: `"draft story"` → `*create` → `create-next-story` task
</ParamField>

## Agent Examples

### Dev Agent (Builder)

```yaml
agent:
  name: Dex
  id: dev
  title: Full Stack Developer
  icon: 💻
  whenToUse: 'Use for code implementation, debugging, refactoring'

persona_profile:
  archetype: Builder
  communication:
    tone: pragmatic
    emoji_frequency: medium
    greeting_levels:
      archetypal: '💻 Dex the Builder ready to innovate!'

persona:
  role: Expert Senior Software Engineer
  style: Extremely concise, pragmatic, detail-oriented
  core_principles:
    - FOLLOW develop-story command
    - ONLY update Dev Agent Record sections
````

### Architect Agent (Visionary)

```yaml theme={null}
agent:
  name: Aria
  id: architect
  title: Architect
  icon: 🏛️
  whenToUse: 'Use for system architecture, API design, security'

persona_profile:
  archetype: Visionary
  communication:
    tone: conceptual
    emoji_frequency: low
    greeting_levels:
      archetypal: '🏛️ Aria the Visionary ready to envision!'

persona:
  role: Holistic System Architect
  style: Comprehensive, pragmatic, user-centric
  responsibility_boundaries:
    delegate_to_data_engineer:
      when:
        - Database schema design
        - Query optimization
```

## Command Examples

```yaml theme={null}
commands:
  - name: help
    visibility: [full, quick, key]
    description: 'Show all available commands'
  - name: develop
    visibility: [full, quick]
    description: 'Implement story tasks'
  - name: create-service
    visibility: [full]
    description: 'Generate new service from template'
```

## Dependency Examples

```yaml theme={null}
dependencies:
  checklists:
    - story-dod-checklist.md
    - self-critique-checklist.md
  tasks:
    - dev-develop-story.md
    - create-service.md
    - qa-fix-issues.md
  templates:
    - story-template.md
    - service-template/
  scripts:
    - recovery-tracker.js
    - build-orchestrator.js
  tools:
    - coderabbit
    - git
    - context7
```

## Agent Activation Shortcuts

Agents can be activated using multiple patterns:

<ResponseField name="Slash Commands" type="array">
  * `/dev`, `/architect`, `/qa`
  * `/@dev`, `/@architect`, `/@qa`
  * `/dev.md`, `/architect.md`
</ResponseField>

<ResponseField name="At-mentions" type="array">
  * `@dev`, `@architect`, `@qa`
</ResponseField>

<ResponseField name="Skill Activation" type="string">
  `/skills` → Select `aiox-{agent-id}` from local skills
</ResponseField>

## Best Practices

<AccordionGroup>
  <Accordion title="Agent Design">
    * Define clear responsibility boundaries
    * Specify delegation patterns to other agents
    * Keep commands focused and atomic
    * Document when to use vs. delegate
    * Include educational greeting levels
  </Accordion>

  <Accordion title="Command Structure">
    * Use visibility levels appropriately (`key` \< `quick` \< `full`)
    * Provide clear, concise descriptions
    * Group related commands together
    * Use consistent naming patterns (`create-*`, `qa-*`)
  </Accordion>

  <Accordion title="Dependencies">
    * List all required files explicitly
    * Organize by category (tasks, checklists, templates)
    * Use relative paths from `.aiox-core/development/`
    * Document purpose of each dependency
  </Accordion>

  <Accordion title="Persona Configuration">
    * Match tone to agent archetype
    * Use consistent vocabulary
    * Define clear core principles
    * Specify boundaries and collaboration patterns
  </Accordion>
</AccordionGroup>

## IDE Sync Integration

Agent definitions are **automatically synced** to IDE-specific formats:

<ResponseField name="Claude Code" type="string">
  `.claude/commands/AIOX/agents/{agent-id}.md` (full-markdown-yaml)
</ResponseField>

<ResponseField name="Codex" type="string">
  `.codex/agents/{agent-id}.md` (full-markdown-yaml)
</ResponseField>

<ResponseField name="Gemini" type="string">
  `.gemini/rules/AIOX/agents/{agent-id}.md` (full-markdown-yaml)
</ResponseField>

<ResponseField name="Cursor" type="string">
  `.cursor/rules/agents/{agent-id}` (condensed-rules)
</ResponseField>

Sync via:

```bash theme={null}
npm run sync:ide          # Sync all IDEs
npm run sync:ide:claude   # Sync Claude Code only
npm run sync:ide:check    # Validate sync drift
```

## Related Documentation

* [Agent Commands](/api/agent-commands)
* [Agent Memory](/api/agent-memory)
* [Tasks Reference](/api/tasks)
* [IDE Sync System](/guides/ide-sync)

***

*Reference: `.aiox-core/development/agents/`*