Skip to content

agent-selection-guide.md

Latest commit

 

History

History
289 lines (225 loc) · 8.82 KB

agent-selection-guide.md

File metadata and controls

289 lines (225 loc) · 8.82 KB
Raw

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

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