Agent Definition Files

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.

string

.aiox-core/development/agents/*.md

string

Markdown with YAML frontmatter

string

.md (Markdown)

File Structure

Agent files follow a strict structure with YAML configuration block:

# {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)

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

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

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:

array

/dev, /architect, /qa
/@dev, /@architect, /@qa
/dev.md, /architect.md

array

@dev, @architect, @qa

string

/skills → Select aiox-{agent-id} from local skills

Best Practices

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

Command Structure

Use visibility levels appropriately (key < quick < full)
Provide clear, concise descriptions
Group related commands together
Use consistent naming patterns (create-*, qa-*)

Dependencies

List all required files explicitly
Organize by category (tasks, checklists, templates)
Use relative paths from .aiox-core/development/
Document purpose of each dependency

Persona Configuration

Match tone to agent archetype
Use consistent vocabulary
Define clear core principles
Specify boundaries and collaboration patterns

IDE Sync Integration

Agent definitions are automatically synced to IDE-specific formats:

string

.claude/commands/AIOX/agents/{agent-id}.md (full-markdown-yaml)

string

.codex/agents/{agent-id}.md (full-markdown-yaml)

string

.gemini/rules/AIOX/agents/{agent-id}.md (full-markdown-yaml)

string

.cursor/rules/agents/{agent-id} (condensed-rules)

Sync via:

npm run sync:ide          # Sync all IDEs
npm run sync:ide:claude   # Sync Claude Code only
npm run sync:ide:check    # Validate sync drift

Reference: .aiox-core/development/agents/

Configuration

Agent System

Templates & Tasks

Agent Definition Files

Overview

File Structure

Architect Agent (Visionary)

Command Examples

Dependency Examples

Agent Activation Shortcuts

Best Practices

IDE Sync Integration

​Overview

​File Structure

​Architect Agent (Visionary)

​Command Examples

​Dependency Examples

​Agent Activation Shortcuts

​Best Practices

​IDE Sync Integration

​Related Documentation

Overview

File Structure

Architect Agent (Visionary)

Command Examples

Dependency Examples

Agent Activation Shortcuts

Best Practices

IDE Sync Integration

Related Documentation