> ## 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 System > Understanding AIOX agents: personas, capabilities, and collaboration patterns ## 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. 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: **Identity & Communication Style** ```yaml theme={null} 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** ```yaml theme={null} 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** ```yaml theme={null} 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** ```yaml theme={null} 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 **Role**: Expert Senior Software Engineer & Implementation Specialist **Archetype**: Builder ♒ Aquarius\ **Tone**: Pragmatic, detail-oriented **Key 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 **Role**: Technical Scrum Master - Story Preparation Specialist **Archetype**: Facilitator ♓ Pisces\ **Tone**: Empathetic, task-oriented **Key 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 **Role**: Senior QA Engineer & Code Reviewer **Key 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 **Role**: Deployment & Infrastructure Specialist **Exclusive 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 **Role**: Product Strategy & Backlog Management **Key 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 **Role**: Epic Orchestration & Multi-Agent Coordination **Key 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:** ```mermaid theme={null} graph LR A[@pm Bob] --> B[@po Validate] B --> C[@dev Implement] C --> D[@qa Review] D --> E[@devops Deploy] ``` **Role**: Technical Architecture & Design Decisions **Exclusive 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 **Role**: Market Research & Analysis **Key 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 **Role**: Database Schema & Migration Specialist **Key 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 **Role**: User Experience & Design System Specialist **Key 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 **Role**: High-Level Orchestration & Course Correction **Key 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 **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 **ONLY @architect can:** * Make architecture decisions * Approve architectural changes * Document ADRs **Why?** * Technical consistency * Design coherence * Knowledge centralization **ONLY @qa can:** * Issue quality verdicts * Approve/reject stories * Define quality standards **Why?** * Independent quality assessment * Consistent standards * Objective review **ONLY @po/@sm can:** * Create stories * Validate story drafts * Manage backlog **Why?** * Product vision alignment * Requirement clarity * Priority management ### Delegation Rules Agents MUST delegate to the appropriate agent when a request falls outside their authority scope. **Example Delegation Pattern:** ```mermaid theme={null} graph LR A[@dev implements] --> B{Ready to push?} B -->|Yes| C[Delegate to @devops] C --> D[@devops push] E[@sm drafts story] --> F{Architecture needed?} F -->|Yes| G[Delegate to @architect] G --> H[@architect analyze-impact] ``` ## Activation & Greeting System Agents follow a standardized activation sequence: Load complete persona from markdown file Assume the agent's identity, tone, and focus 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) 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.3 **Available 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 Agents create handoff artifacts in `.aiox/handoffs/` to enable workflow continuity across sessions. **Handoff Artifact (YAML):** ```yaml theme={null} 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: ```yaml theme={null} 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) ```mermaid theme={null} graph TD A[@sm draft] --> B[@po validate-story-draft] B -->|Approved| C[@dev develop] B -->|Needs Changes| A C --> D[@qa review] D -->|PASS| E[@devops push] D -->|Needs Fixes| F[@dev apply-qa-fixes] F --> D style A fill:#1a73e8,color:#fff style B fill:#f9ab00,color:#fff style C fill:#34a853,color:#fff style D fill:#ea4335,color:#fff style E fill:#34a853,color:#fff ``` ### Epic Orchestration ```mermaid theme={null} graph TD A[@pm execute-epic] --> B[@pm assign-executor] B --> C[@dev build-autonomous] C --> D{Story Complete?} D -->|Yes| E[@pm continue epic] D -->|No| F[@dev build-resume] F --> C E --> B style A fill:#1a73e8,color:#fff style C fill:#34a853,color:#fff style E fill:#f9ab00,color:#fff ``` ### QA Feedback Loop ```mermaid theme={null} graph TD A[@qa review] --> B{Verdict?} B -->|APPROVE| C[Complete] B -->|REJECT| D[@dev fix-qa-issues] B -->|BLOCKED| E[Escalate] D --> A style A fill:#f9ab00,color:#fff style C fill:#34a853,color:#fff style D fill:#1a73e8,color:#fff style E fill:#ea4335,color:#fff ``` ## Dynamic Dependency Loading **CRITICAL**: Dependencies are loaded **on-demand**, NOT at activation. Agents declare dependencies but only load them when executing specific commands: **Activation:** ```yaml theme={null} # Agent reads dependencies list dependencies: tasks: - dev-develop-story.md - apply-qa-fixes.md ``` **Command Execution:** ```bash theme={null} # 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: ```yaml theme={null} tools: - git git_restrictions: allowed_operations: - git add - git commit - git status - git diff blocked_operations: - git push # ONLY @devops ``` ```yaml theme={null} tools: - coderabbit coderabbit_integration: enabled: true self_healing: enabled: true max_iterations: 2 severity_filter: - CRITICAL ``` ```yaml theme={null} tools: - context7 # Look up library documentation during development # Example: How to use Supabase RLS policies ``` ## Permission Modes Agents operate in different permission modes: **\[⚠️ Ask]** Agent asks before every action **Use when:** * Learning the system * High-risk operations * Exploratory work **\[🟢 Auto]** Agent executes autonomously within scope **Use when:** * Standard workflows * Trusted operations * Production development **\[🔍 Explore]** Agent investigates and proposes solutions **Use when:** * Debugging complex issues * Research mode * Discovery phase Toggle with `*yolo` command: Ask → Auto → Explore → Ask... ## Summary **Self-Contained**: Each agent is a complete unit with persona, capabilities, and dependencies **Authority-Bounded**: Exclusive authorities enforced constitutionally **Collaborative**: Agents delegate and handoff seamlessly **On-Demand Loading**: Dependencies loaded contextually, not proactively **Tool-Integrated**: External tools accessible declaratively **Workflow-Driven**: Agents follow defined workflow chains ## Next Steps See how agents execute story-based workflows Explore multi-agent workflow patterns Practical guide to working with agents Understand the CLI-first architecture