Agent Commands

Reference for AIOX agent command system and execution patterns

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 * prefix

Example: *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

Show visibility levels

key · string

Most Important - Shown in agent greeting and quick reference

Use for: Primary agent workflows (e.g., *develop, *review)

quick · string

Frequently Used - Shown in quick reference and *help

Use for: Common operations (e.g., *run-tests, *apply-qa-fixes)

full · string

All Commands - Shown only in *help

Use for: Advanced/utility commands (e.g., *clear-cache, *session-info)

description · string · required

Brief command description

Should 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 descriptions

Visibility: [full, quick, key]

*guide · command

Show comprehensive usage guide for this agent

Visibility: [full]

*exit · command

Exit current agent mode and return to base state

Visibility: [full, quick, key]

Dev Agent Commands

*develop · command

Implement story tasks with selectable execution modes

Usage:

*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 pipeline

Pipeline:

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 workflow

Workflow 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 template

Service 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 issues

Reads from QA_FIX_REQUEST.md and implements fixes.

Visibility: [quick, key]

Architect Agent Commands

*analyze-impact · command

Analyze architectural impact of proposed changes

Analysis Dimensions:

• Performance impact
• Security implications
• Scalability concerns
• Integration complexity

Visibility: [full, quick, key]

*create-architecture · command

Design system architecture from requirements

Outputs:

• Architecture diagrams
• Technology stack decisions
• ADRs (Architecture Decision Records)

Visibility: [full, quick]

QA Agent Commands

*review-story · command

Comprehensive story quality review

Review Areas:

• Code quality
• Test coverage
• Documentation completeness
• Acceptance criteria validation

Visibility: [full, quick, key]

*generate-tests · command

Generate test suite for implementation

Test Types:

• Unit tests
• Integration tests
• E2E tests
• Visual regression tests

Visibility: [full, quick]

*create-fix-request · command

Create structured fix request for dev agent

Generates 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 name

Example: *develop → dev-develop-story.md

Prefixed Mapping · string

Command includes agent prefix

Example: *qa-review → qa-review-story.md

Fuzzy Matching · string

Natural language requests match to commands

Example:

• “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 operations

Agent asks permission for:

• File writes/deletions
• Git commits
• External API calls

Auto Mode · mode

[🟢 Auto] - Autonomous execution with logging

Agent proceeds automatically, logs all decisions.

Explore Mode · mode

[🔍 Explore] - Read-only exploration

Agent can read files, analyze code, but cannot modify.

Toggle modes with *yolo command (cycles through modes).

Best Practices

Command Design

• Use clear, action-oriented names
• Keep descriptions under 80 characters
• Assign appropriate visibility levels
• Support both interactive and autonomous modes
• Provide parameter validation

Command Usage

• 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

Error Handling

• Validate parameters before execution
• Provide clear error messages
• Support graceful degradation
• Log all failures for debugging
• Offer recovery options

Related Documentation

• Agent Definition Files
• Tasks Reference
• Agent Memory System
• Workflow Chains

---

Reference: Agent YAML commands section