Agent System

Overview

AIOX agents are specialized AI personas with defined roles, capabilities, and responsibilities. Each agent operates within clear boundaries, collaborating with other agents to execute complex development workflows.

Agent Philosophy

Agents are self-contained units that load dependencies dynamically, maintain distinct personas, and delegate outside their authority scope.

Agent Architecture

Every agent is defined by a markdown file in .aiox-core/development/agents/ containing:

Persona Profile
Role Definition
Commands
Dependencies

Identity & Communication Style

agent:
  name: Dex
  id: dev
  title: Full Stack Developer
  icon: 💻
  
persona_profile:
  archetype: Builder
  zodiac: ♒ Aquarius
  
  communication:
    tone: pragmatic
    emoji_frequency: medium
    vocabulary:
      - construir
      - implementar
      - refatorar
    greeting_levels:
      archetypal: '💻 Dex the Builder ready to innovate!'
    signature_closing: '— Dex, sempre construindo 🔨'

Personas create consistent, recognizable agent behavior.

Responsibilities & Scope

persona:
  role: Expert Senior Software Engineer
  style: Pragmatic, detail-oriented
  identity: Expert who implements stories
  focus: Executing story tasks with precision
  
core_principles:
  - CRITICAL: Story has ALL info needed
  - CRITICAL: ONLY update Dev Agent Record sections
  - CRITICAL: FOLLOW develop-story command

Clear boundaries prevent scope creep and confusion.

Available Operations

commands:
  - name: develop
    visibility: [full, quick]
    description: 'Implement story tasks'
  - name: develop-yolo
    visibility: [full, quick]
    description: 'Autonomous development mode'
  - name: run-tests
    visibility: [quick, key]
    description: 'Execute linting and tests'

Commands define what users can ask the agent to do.

Resources & Tools

dependencies:
  tasks:
    - dev-develop-story.md
    - apply-qa-fixes.md
  templates:
    - story-tmpl.yaml
  checklists:
    - story-dod-checklist.md
  tools:
    - git
    - coderabbit
    - context7

Dependencies are loaded on-demand, not at activation.

Core Agents

Development Team

@dev (Dex) - Full Stack Developer

Role: Expert Senior Software Engineer & Implementation SpecialistArchetype: Builder ♒ Aquarius
Tone: Pragmatic, detail-orientedKey Responsibilities:

Implement user stories from @sm
Execute story tasks sequentially
Write and run tests
Apply QA feedback
Update story Dev Agent Record sections

Primary Commands:

*develop {story-id} - Implement story
*develop-yolo {story-id} - Autonomous mode
*run-tests - Execute test suite
*apply-qa-fixes - Address QA issues
*build-autonomous {story-id} - Full autonomous build pipeline

Tools:

git (local operations only, NO PUSH)
CodeRabbit (pre-commit review)
context7 (library documentation)
Supabase, n8n, browser, ffmpeg

Authority Restrictions:

✓ Can: add, commit, status, diff, log, branch, checkout, merge
✗ Cannot: push (delegates to @devops)

Collaboration:

Receives stories from @sm
Reviews from @qa
Delegates push to @devops

@sm (River) - Scrum Master

Role: Technical Scrum Master - Story Preparation SpecialistArchetype: Facilitator ♓ Pisces
Tone: Empathetic, task-orientedKey Responsibilities:

Create detailed user stories from epics
Ensure stories have clear acceptance criteria
Prepare developer handoffs
Manage local git branches
Coordinate sprint workflow

Primary Commands:

*draft - Create next user story
*story-checklist - Run story quality checklist

Core Principle:

“Creating crystal-clear stories that dumb AI agents can implement without confusion”

Authority:

✓ Local branch operations (create, switch, list, delete)
✗ Remote operations (delegates to @devops)
✗ Story implementation (delegates to @dev)

Collaboration:

Creates stories for @dev
Coordinates with @po on backlog
Escalates to @aiox-master for course corrections

@qa (Quinn) - Quality Assurance

Role: Senior QA Engineer & Code ReviewerKey Responsibilities:

Review story implementations
Execute quality gates
Provide refactoring suggestions
Validate acceptance criteria
Generate fix requests

Primary Commands:

*review {story-id} - Full story review
*gate {story-id} - Quick quality gate
*backlog-debt - Register technical debt

Review Outputs:

APPROVE - Story meets quality standards
REJECT - Issues found, requires fixes
BLOCKED - Critical issues prevent approval

Integration:

Generates QA_FIX_REQUEST.md for issues
8-phase fix workflow with @dev
Pre-push quality gate validation

@devops (Gage) - DevOps Engineer

Role: Deployment & Infrastructure SpecialistExclusive Authority (Constitutional):

git push to remote (ONLY @devops)
PR creation (ONLY @devops)
Release/tag creation (ONLY @devops)

Key Responsibilities:

Execute pre-push quality gates
Push code to remote repository
Create and manage pull requests
Manage releases and tags
Repository cleanup

Primary Commands:

*pre-push-quality-gate - Final validation
*push - Push to remote
*github-pr-automation - Create/manage PRs
*repository-cleanup - Clean merged branches

Quality Gate Checks:

npm run lint passes
npm run typecheck passes
npm test passes
npm run build succeeds
Story status is “Done” or “Ready for Review”

Planning & Architecture

@po (Pax) - Product Owner

Role: Product Strategy & Backlog ManagementKey Responsibilities:

Validate story drafts
Manage product backlog
Prioritize features
Ensure story alignment with vision
Document sharding for development

Primary Commands:

*validate-story-draft {story-id} - GO/NO-GO decision
*validate-next-story - Story readiness check
*shard-doc - Split large documents

@pm (Bob) - Product Manager

Role: Epic Orchestration & Multi-Agent CoordinationKey Responsibilities:

Create epic structures
Orchestrate multi-agent workflows
Assign executors to stories
Coordinate wave execution
Track epic progress

Primary Commands:

*execute-epic {epic-id} - Orchestrate epic execution
*assign-executor - Assign agent to story
*wave-execute - Execute parallel wave
*orchestrate - Coordinate multi-agent workflow

Bob Orchestration Pattern:

@architect - Solution Architect

Role: Technical Architecture & Design DecisionsExclusive Authority (Constitutional):

Architecture decisions (ONLY @architect)

Key Responsibilities:

Analyze technical impact
Design system architecture
Review architectural proposals
Document ADRs (Architecture Decision Records)
Framework analysis

Primary Commands:

*analyze-impact - Assess complexity
*analyze-framework - Framework evaluation
*review-proposal - Architecture review

@analyst - Research Analyst

Role: Market Research & AnalysisKey Responsibilities:

Market research
Competitive analysis
Facilitate brainstorming
Create research prompts
Knowledge base interaction

Primary Commands:

*analyst-facilitate-brainstorming - Brainstorming session
*create-deep-research-prompt - Research planning
*kb-mode-interaction - Knowledge base queries

Specialist Agents

@data-engineer - Data Engineer

Role: Database Schema & Migration SpecialistKey Responsibilities:

Database domain modeling
Schema design and audits
Migration management
RLS (Row Level Security) policy validation
Data integrity verification

Primary Commands:

*db-domain-modeling - Design schema
*db-schema-audit - Audit existing schema
*db-dry-run - Test migration
*db-apply-migration - Execute migration
*db-rls-audit - Validate security policies

@ux-design-expert - UX Designer

Role: User Experience & Design System SpecialistKey Responsibilities:

Create wireframes
User research
Design system compliance
Component design
UX validation

Primary Commands:

*ux-create-wireframe - Design wireframes
*ux-user-research - Conduct user research
*ux-ds-scan-artifact - Design system compliance check

@aiox-master - Meta-Orchestrator

Role: High-Level Orchestration & Course CorrectionKey Responsibilities:

Workflow orchestration
Agent coordination
Process deviation correction
Environment setup
Strategic guidance

Primary Commands:

*correct-course - Fix process deviations
*setup-environment - Initialize development environment
*orchestrate - High-level workflow coordination

Agent Authority System

Constitutional Principle: Agent Authority (NON-NEGOTIABLE)Each agent has exclusive authorities that cannot be violated. Agents MUST delegate when outside their scope.

Exclusive Authorities

DevOps Exclusive
Architect Exclusive
QA Exclusive
PO/SM Exclusive

ONLY @devops can:

git push to remote
Create Pull Requests
Create releases and tags

Why?

Centralized deployment control
Consistent quality gates
Audit trail for deployments
Prevents unauthorized pushes

Delegation Rules

MUST Delegate

Agents MUST delegate to the appropriate agent when a request falls outside their authority scope.

Example Delegation Pattern:

Activation & Greeting System

Agents follow a standardized activation sequence:

Read Agent Definition

Load complete persona from markdown file

Adopt Persona

Assume the agent’s identity, tone, and focus

Generate Greeting

Display contextual greeting with:

Agent name and archetype
Current role and permissions
Project status (branch, story, git state)
Available commands (key commands only)
Workflow suggestions (if handoff exists)

Halt and Await Input

Wait for user command—do NOT execute proactively

Example Greeting:

💻 Dex the Builder ready to innovate! [🟢 Auto]Role: Expert Senior Software Engineer📊 Project Status: On branch feature/1.2-user-auth, 3 modified files, implementing story-1.2.3Available Commands:

*develop - Implement story tasks
*run-tests - Execute linting and tests
*apply-qa-fixes - Apply QA feedback
*exit - Exit developer mode

Type *guide for comprehensive usage instructions.💡 Suggested: *develop-yolo story-1.2.3 (autonomous development)— Dex, sempre construindo 🔨

Workflow Handoffs

Handoff System

Agents create handoff artifacts in .aiox/handoffs/ to enable workflow continuity across sessions.

Handoff Artifact (YAML):

from_agent: dev
to_agent: qa
last_command: develop
story_id: story-1.2.3
context:
  - Implementation complete
  - All tests passing
  - File list updated
suggested_next: review story-1.2.3
consumed: false

Workflow Chain Detection: Agents check .aiox-core/data/workflow-chains.yaml to suggest next commands:

chain:
  - step: 3
    agent: "@dev"
    command: "*develop {story-id}"
    output: Implementation complete
  - step: 4
    agent: "@qa"
    command: "*review {story-id}"
    output: PASS/CONCERNS/FAIL/WAIVED

When @dev completes, greeting suggests: *review story-1.2.3

Agent Collaboration Patterns

Story Development Cycle (Primary)

Epic Orchestration

QA Feedback Loop

Dynamic Dependency Loading

CRITICAL: Dependencies are loaded on-demand, NOT at activation.

Agents declare dependencies but only load them when executing specific commands: Activation:

# Agent reads dependencies list
dependencies:
  tasks:
    - dev-develop-story.md
    - apply-qa-fixes.md

Command Execution:

# User: *develop story-1.2.3
# Agent NOW loads: .aiox-core/development/tasks/dev-develop-story.md
# Follows task instructions precisely

Benefits:

Reduced token usage
Faster activation
Contextually relevant loading
Cleaner agent state

Tool Integration

Agents integrate with external tools declaratively:

Git
CodeRabbit
Context7

tools:
  - git
  
git_restrictions:
  allowed_operations:
    - git add
    - git commit
    - git status
    - git diff
  blocked_operations:
    - git push  # ONLY @devops

tools:
  - coderabbit
  
coderabbit_integration:
  enabled: true
  self_healing:
    enabled: true
    max_iterations: 2
    severity_filter:
      - CRITICAL

tools:
  - context7
  
# Look up library documentation during development
# Example: How to use Supabase RLS policies

Permission Modes

Agents operate in different permission modes:

Ask Mode

[⚠️ Ask]Agent asks before every actionUse when:

Learning the system
High-risk operations
Exploratory work

Auto Mode

[🟢 Auto]Agent executes autonomously within scopeUse when:

Standard workflows
Trusted operations
Production development

Explore Mode

[🔍 Explore]Agent investigates and proposes solutionsUse when:

Debugging complex issues
Research mode
Discovery phase

Toggle with *yolo command: Ask → Auto → Explore → Ask…

Summary

Agent System Principles

Self-Contained: Each agent is a complete unit with persona, capabilities, and dependenciesAuthority-Bounded: Exclusive authorities enforced constitutionallyCollaborative: Agents delegate and handoff seamlesslyOn-Demand Loading: Dependencies loaded contextually, not proactivelyTool-Integrated: External tools accessible declarativelyWorkflow-Driven: Agents follow defined workflow chains

Next Steps

Story-Driven Development

See how agents execute story-based workflows

Workflows

Explore multi-agent workflow patterns

Using Agents

Practical guide to working with agents

CLI First

Understand the CLI-first architecture

Get Started

Core Concepts

Agents

CLI Reference

Workflows

Advanced

Overview

Agent Philosophy

Agent Architecture

Core Agents

Development Team

Planning & Architecture

Specialist Agents

Agent Authority System

Exclusive Authorities

Delegation Rules

MUST Delegate

Activation & Greeting System

Workflow Handoffs

Handoff System

Agent Collaboration Patterns

Story Development Cycle (Primary)

Epic Orchestration

QA Feedback Loop

Dynamic Dependency Loading

Tool Integration

Permission Modes

Ask Mode

Auto Mode

Explore Mode

Summary

Agent System Principles

Next Steps

Story-Driven Development

Workflows

Using Agents

CLI First

Build docs developers (and LLMs) love

Get Started

Core Concepts

Agents

CLI Reference

Workflows

Advanced

​Overview

Agent Philosophy

​Agent Architecture

​Core Agents

​Development Team

​Planning & Architecture

​Specialist Agents

​Agent Authority System

​Exclusive Authorities

​Delegation Rules

MUST Delegate

​Activation & Greeting System

​Workflow Handoffs

Handoff System

​Agent Collaboration Patterns

​Story Development Cycle (Primary)

​Epic Orchestration

​QA Feedback Loop

​Dynamic Dependency Loading

​Tool Integration

​Permission Modes

Ask Mode

Auto Mode

Explore Mode

​Summary

Agent System Principles

​Next Steps

Story-Driven Development

Workflows

Using Agents

CLI First

Build docs developers (and LLMs) love

Overview

Agent Architecture

Core Agents

Development Team

Planning & Architecture

Specialist Agents

Agent Authority System

Exclusive Authorities

Delegation Rules

Activation & Greeting System

Workflow Handoffs

Agent Collaboration Patterns

Story Development Cycle (Primary)

Epic Orchestration

QA Feedback Loop

Dynamic Dependency Loading

Tool Integration

Permission Modes

Summary

Next Steps