Agent Selection Guide

EN | PT | ES

Quick Reference for Choosing the Right Agent

Last Updated: 2026-01-29 (ADE v2.2.0)

Quick Decision Tree

Need research/analysis? → @analyst
   ↓
Need PRD/epic? → @pm
   ↓
Need architecture? → @architect
   ↓
Need database? → @data-engineer
   ↓
Need stories? → @sm
   ↓
Need implementation? → @dev
   ↓
Need testing/QA? → @qa
   ↓
Need deployment? → @devops

Agent Quick Reference

| Agent | Icon | Use For | NOT For | | ---------------------------- | ---- | ------------------------------------------------------------------------------------------- | ---------------------------------------- | | @analyst (Atlas) | 🔍 | Market research, competitive analysis, brainstorming, pattern extraction | PRD creation, architecture, stories | | @pm (Morgan) | 📋 | PRD, epics, product strategy, requirements gathering, spec writing | Research, architecture, detailed stories | | @architect (Aria) | 🏛️ | System architecture, API design, tech stack, complexity assessment, implementation planning | Research, PRD, database schema | | @data-engineer (Dara) | 📊 | Database schema, RLS, migrations, query optimization | App architecture, DB tech selection | | @sm (River) | 🌊 | User stories, sprint planning, backlog grooming | PRD, epics, research, implementation | | @dev (Dex) | 💻 | Story implementation, coding, testing, subtask execution, recovery | Story creation, deployment | | @qa (Quinn) | 🧪 | Code review, testing, quality assurance, spec critique, structured review | Implementation | | @po (Pax) | 🎯 | Backlog management, acceptance criteria, prioritization | Epic creation, architecture | | @ux-design-expert (Nova) | 🎨 | UI/UX design, wireframes, design systems | Implementation | | @devops (Gage) | ⚙️ | Git ops, PR creation, deployment, CI/CD, worktree management, migrations | Local Git, implementation | | @aiox-master (Orion) | 👑 | Framework development, multi-agent orchestration | Routine tasks (use specialized agents) |

🤖 ADE Commands by Agent (v2.2.0)

@devops (Gage) - Infrastructure & Operations

Worktree Management: | Command | Description | |---------|-------------| | *create-worktree {story} | Create isolated Git worktree for story development | | *list-worktrees | List all active worktrees with status | | *merge-worktree {story} | Merge completed worktree back to main | | *cleanup-worktrees | Remove stale/merged worktrees |

Migration Management: | Command | Description | |---------|-------------| | *inventory-assets | Generate migration inventory from V2 assets | | *analyze-paths | Analyze path dependencies and migration impact | | *migrate-agent | Migrate single agent from V2 to V3 format | | *migrate-batch | Batch migrate all agents with validation |

@pm (Morgan) - Product Management

Spec Pipeline: | Command | Description | |---------|-------------| | *gather-requirements | Elicit and document requirements from stakeholders | | *write-spec | Generate formal specification document from requirements |

@architect (Aria) - System Architecture

Spec Pipeline: | Command | Description | |---------|-------------| | *assess-complexity | Assess story complexity and estimate effort |

Execution Engine: | Command | Description | |---------|-------------| | *create-plan | Create implementation plan with phases and subtasks | | *create-context | Generate project and files context for story |

Memory Layer: | Command | Description | |---------|-------------| | *map-codebase | Generate codebase map (structure, services, patterns) |

@analyst (Atlas) - Research & Analysis

Spec Pipeline: | Command | Description | |---------|-------------| | *research-deps | Research dependencies and technical constraints |

Memory Layer: | Command | Description | |---------|-------------| | *extract-patterns | Extract and document code patterns from codebase |

@qa (Quinn) - Quality Assurance

Spec Pipeline: | Command | Description | |---------|-------------| | *critique-spec {story} | Review and critique specification for completeness |

QA Evolution (10-Phase Review): | Command | Description | |---------|-------------| | *review-build {story} | 10-phase structured QA review - outputs qa_report.md | | *request-fix {issue} | Request specific fix from @dev with context | | *verify-fix {issue} | Verify fix was properly implemented |

@dev (Dex) - Development

Execution Engine: | Command | Description | |---------|-------------| | *execute-subtask | Execute subtask following 13-step workflow with self-critique |

Recovery System: | Command | Description | |---------|-------------| | *track-attempt | Track implementation attempt (registers in recovery/attempts.json) | | *rollback | Rollback to last good state (--hard to skip confirmation) |

QA Loop: | Command | Description | |---------|-------------| | *apply-qa-fix | Apply fix requested by QA (reads qa_report.md for context) |

Memory Layer: | Command | Description | |---------|-------------| | *capture-insights | Capture session insights (discoveries, patterns, gotchas) | | *list-gotchas | List known gotchas from .aiox/gotchas.md |

Common Scenarios

"I want to build a new feature" (Traditional)

1. @analyst *brainstorm - Ideation
2. @pm *create-prd - Product requirements
3. @architect *create-architecture - Technical design
4. @data-engineer *create-schema - Database design
5. @sm *create-next-story - User stories
6. @dev *develop - Implementation
7. @qa *review - Quality check
8. @devops *create-pr - Deployment

"I want to build using ADE Spec Pipeline" (Autonomous)

1. @pm *gather-requirements - Collect and structure requirements
2. @architect *assess-complexity - Evaluate complexity
3. @analyst *research-deps - Research libraries/APIs
4. @pm *write-spec - Generate specification
5. @qa *critique-spec - Validate spec quality
   ↓
[Spec Approved]
   ↓
6. @architect *create-plan - Create implementation plan
7. @architect *create-context - Generate context files
8. @dev *execute-subtask 1.1 - Execute with 13 steps + self-critique
9. @qa *review-build - 10-phase QA review
   ↓
[If issues found]
   ↓
10. @qa *request-fix - Request fix
11. @dev *apply-qa-fix - Apply fix
12. @qa *verify-fix - Verify

"I'm stuck on implementation"

1. @dev *track-attempt - Log the failed attempt
2. @dev *rollback - Revert to last good state
3. @dev *list-gotchas - Check known pitfalls
4. @dev *execute-subtask --approach alternative - Try different approach

"I need to understand existing codebase"

1. @architect *map-codebase - Generate structure/services/patterns map
2. @analyst *extract-patterns - Document code patterns
3. @dev *capture-insights - Record discoveries

"I need parallel story development"

1. @devops *create-worktree STORY-42 - Isolate branch
2. @dev *execute-subtask - Work in isolation
3. @devops *merge-worktree STORY-42 - Merge when done
4. @devops *cleanup-worktrees - Clean stale branches

Delegation Patterns

Spec Pipeline Flow

@pm *gather-requirements
    ↓
@architect *assess-complexity
    ↓
@analyst *research-deps
    ↓
@pm *write-spec
    ↓
@qa *critique-spec

Execution Flow

@architect *create-plan
    ↓
@architect *create-context
    ↓
@dev *execute-subtask (loops)
    ↓
@qa *review-build

QA Loop

@qa *review-build
    ↓ (issues found)
@qa *request-fix
    ↓
@dev *apply-qa-fix
    ↓
@qa *verify-fix
    ↓ (loop until clean)

Recovery Flow

@dev fails subtask
    ↓
@dev *track-attempt
    ↓
Retries < 3? → @dev retry with variation
    ↓
@dev *rollback → try different approach

Full Documentation

• ADE Complete Guide - Full tutorial for Autonomous Development Engine
• Agent Responsibility Matrix - Complete boundary definitions

Version: 2.0 | ADE: v2.2.0 | Date: 2026-01-29