Skip to main content

​
Overview

AIOX agents expose commands that users invoke with the * prefix. Commands are defined in agent YAML configuration and map to task files that contain executable workflows.
​
Command Prefix
string
required
All agent commands use the * prefixExample: *develop, *help, *create-service
​
Command Resolution
string
Commands map to task files in .aiox-core/development/tasks/Example: *develop → dev-develop-story.md

​
Command Structure

Commands are defined in the agent’s YAML configuration: 
commands:
  - name: develop
    visibility: [full, quick, key]
    description: 'Implement story tasks (modes: yolo, interactive, preflight)'
  
  - name: create-service
    visibility: [full, quick]
    description: 'Create new service from template'

​
Command Schema

​
name
string
required
Command name (without * prefix)Example: "help", "develop", "create-agent"
​
visibility
array
required
Visibility levels determine where command appears
​
description
string
required
Brief command descriptionShould be concise (under 80 characters) and action-oriented.

​
Common Agent Commands

​
Universal Commands

All agents support these core commands:
​
*help
command
Show all available commands with descriptionsVisibility: [full, quick, key]
​
*guide
command
Show comprehensive usage guide for this agentVisibility: [full]
​
*exit
command
Exit current agent mode and return to base stateVisibility: [full, quick, key]

​
Dev Agent Commands

​
*develop
command
Implement story tasks with selectable execution modesUsage:
*develop {story-id}           # Interactive mode (default)
*develop {story-id} yolo      # Autonomous mode
*develop {story-id} preflight # Planning mode
Modes:
  • interactive - Educational, explicit checkpoints (5-10 prompts)
  • yolo - Autonomous, minimal interaction (0-1 prompts)
  • preflight - Comprehensive upfront planning
Visibility: [full, quick, key]
​
*build
command
Complete autonomous build pipelinePipeline:
  1. Create worktree
  2. Generate implementation plan
  3. Execute subtasks
  4. Run verification
  5. Merge to main
Usage: *build {story-id}Visibility: [full, quick, key]
​
*execute-subtask
command
Execute single subtask using 13-step Coder Agent workflowWorkflow Steps:
  1. Read subtask definition
  2. Analyze requirements
  3. Plan implementation
  4. Execute code changes
  5. Self-critique (mandatory)
  6. Run tests
  7. Update documentation
Visibility: [full, quick]
​
*create-service
command
Generate new service from Handlebars templateService Types:
  • api-integration - External API client
  • utility - Utility service
  • agent-tool - Agent tool integration
Visibility: [full, quick]
​
*apply-qa-fixes
command
Apply QA feedback and fix reported issuesReads from QA_FIX_REQUEST.md and implements fixes.Visibility: [quick, key]

​
Architect Agent Commands

​
*analyze-impact
command
Analyze architectural impact of proposed changesAnalysis Dimensions:
  • Performance impact
  • Security implications
  • Scalability concerns
  • Integration complexity
Visibility: [full, quick, key]
​
*create-architecture
command
Design system architecture from requirementsOutputs:
  • Architecture diagrams
  • Technology stack decisions
  • ADRs (Architecture Decision Records)
Visibility: [full, quick]

​
QA Agent Commands

​
*review-story
command
Comprehensive story quality reviewReview Areas:
  • Code quality
  • Test coverage
  • Documentation completeness
  • Acceptance criteria validation
Visibility: [full, quick, key]
​
*generate-tests
command
Generate test suite for implementationTest Types:
  • Unit tests
  • Integration tests
  • E2E tests
  • Visual regression tests
Visibility: [full, quick]
​
*create-fix-request
command
Create structured fix request for dev agentGenerates QA_FIX_REQUEST.md with categorized issues.Visibility: [full, quick]

​
Command Execution Modes

Many commands support execution modes to balance automation vs. control:
​
interactive
mode
default:"true"
Balanced, Educational (5-10 prompts)
  • Explicit decision checkpoints
  • Educational explanations
  • Best for: Learning, complex decisions
​
yolo
mode
Fast, Autonomous (0-1 prompts)
  • Autonomous decision making
  • Minimal user interaction
  • Best for: Simple, deterministic tasks
​
preflight
mode
Comprehensive Planning
  • Upfront analysis phase
  • Identify all ambiguities
  • Zero-ambiguity execution
  • Best for: Ambiguous requirements, critical work

​
Command Resolution

Commands resolve to task files using these patterns:
​
Direct Mapping
string
Command name matches task file nameExample: *develop → dev-develop-story.md
​
Prefixed Mapping
string
Command includes agent prefixExample: *qa-review → qa-review-story.md
​
Fuzzy Matching
string
Natural language requests match to commandsExample:
  • “draft a story” → *create → create-next-story.md
  • “make a new PRD” → *create-doc + prd-tmpl.md

​
Command Parameters

Commands accept parameters in various formats:

​
Positional Parameters

*develop {story-id} {mode}
*create-service {service-type} {service-name}

​
Named Parameters

*gotchas --category="build" --severity="high"
*worktree-list --status="active"

​
Flag Parameters

*build-status --all
*rollback --hard
*waves --visual

​
Command Chaining

Some commands support workflow chains for multi-step operations: 
# From workflow-chains.yaml
dev:
  develop:
    next:
      - apply-qa-fixes  # After dev completes
      - handoff-to: qa  # Hand off to QA agent

qa:
  review-story:
    next:
      - create-fix-request  # If issues found
      - handoff-to: dev     # Return to dev

​
Command Dependencies

Commands declare dependencies in agent YAML: 
dependencies:
  tasks:
    - dev-develop-story.md      # *develop command
    - create-service.md         # *create-service command
    - qa-fix-issues.md          # *fix-qa-issues command
  
  checklists:
    - story-dod-checklist.md    # Used by *develop
    - self-critique-checklist.md
  
  scripts:
    - build-orchestrator.js     # Used by *build
    - recovery-tracker.js

​
Permission Modes

Agents operate in different permission modes that affect command execution:
​
Ask Mode
mode
default:"true"
[⚠️ Ask] - Confirm before destructive operationsAgent asks permission for:
  • File writes/deletions
  • Git commits
  • External API calls
​
Auto Mode
mode
[🟢 Auto] - Autonomous execution with loggingAgent proceeds automatically, logs all decisions.
​
Explore Mode
mode
[🔍 Explore] - Read-only explorationAgent can read files, analyze code, but cannot modify.
Toggle modes with *yolo command (cycles through modes).

​
Best Practices

  • Use clear, action-oriented names
  • Keep descriptions under 80 characters
  • Assign appropriate visibility levels
  • Support both interactive and autonomous modes
  • Provide parameter validation
  • Start with *help to discover commands
  • Use *guide for comprehensive documentation
  • Default to interactive mode when learning
  • Use yolo mode for repetitive tasks
  • Use preflight mode for critical work
  • Validate parameters before execution
  • Provide clear error messages
  • Support graceful degradation
  • Log all failures for debugging
  • Offer recovery options
Reference: Agent YAML commands section

Build docs developers (and LLMs) love

Get started for freeTalk to us