> ## 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 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.

<ParamField path="Command Prefix" type="string" required>
  All agent commands use the `*` prefix

  Example: `*develop`, `*help`, `*create-service`
</ParamField>

<ParamField path="Command Resolution" type="string">
  Commands map to task files in `.aiox-core/development/tasks/`

  Example: `*develop` → `dev-develop-story.md`
</ParamField>

## Command Structure

Commands are defined in the agent's YAML configuration:

```yaml theme={null}
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

<ParamField path="name" type="string" required>
  Command name (without `*` prefix)

  Example: `"help"`, `"develop"`, `"create-agent"`
</ParamField>

<ParamField path="visibility" type="array" required>
  Visibility levels determine where command appears

  <Expandable title="visibility levels">
    <ResponseField name="key" type="string">
      **Most Important** - Shown in agent greeting and quick reference

      Use for: Primary agent workflows (e.g., `*develop`, `*review`)
    </ResponseField>

    <ResponseField name="quick" type="string">
      **Frequently Used** - Shown in quick reference and `*help`

      Use for: Common operations (e.g., `*run-tests`, `*apply-qa-fixes`)
    </ResponseField>

    <ResponseField name="full" type="string">
      **All Commands** - Shown only in `*help`

      Use for: Advanced/utility commands (e.g., `*clear-cache`, `*session-info`)
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="description" type="string" required>
  Brief command description

  Should be concise (under 80 characters) and action-oriented.
</ParamField>

## Common Agent Commands

### Universal Commands

All agents support these core commands:

<ResponseField name="*help" type="command">
  Show all available commands with descriptions

  **Visibility:** `[full, quick, key]`
</ResponseField>

<ResponseField name="*guide" type="command">
  Show comprehensive usage guide for this agent

  **Visibility:** `[full]`
</ResponseField>

<ResponseField name="*exit" type="command">
  Exit current agent mode and return to base state

  **Visibility:** `[full, quick, key]`
</ResponseField>

### Dev Agent Commands

<ResponseField name="*develop" type="command">
  Implement story tasks with selectable execution modes

  **Usage:**

  ```bash theme={null}
  *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]`
</ResponseField>

<ResponseField name="*build" type="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]`
</ResponseField>

<ResponseField name="*execute-subtask" type="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]`
</ResponseField>

<ResponseField name="*create-service" type="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]`
</ResponseField>

<ResponseField name="*apply-qa-fixes" type="command">
  Apply QA feedback and fix reported issues

  Reads from `QA_FIX_REQUEST.md` and implements fixes.

  **Visibility:** `[quick, key]`
</ResponseField>

### Architect Agent Commands

<ResponseField name="*analyze-impact" type="command">
  Analyze architectural impact of proposed changes

  **Analysis Dimensions:**

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

  **Visibility:** `[full, quick, key]`
</ResponseField>

<ResponseField name="*create-architecture" type="command">
  Design system architecture from requirements

  **Outputs:**

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

  **Visibility:** `[full, quick]`
</ResponseField>

### QA Agent Commands

<ResponseField name="*review-story" type="command">
  Comprehensive story quality review

  **Review Areas:**

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

  **Visibility:** `[full, quick, key]`
</ResponseField>

<ResponseField name="*generate-tests" type="command">
  Generate test suite for implementation

  **Test Types:**

  * Unit tests
  * Integration tests
  * E2E tests
  * Visual regression tests

  **Visibility:** `[full, quick]`
</ResponseField>

<ResponseField name="*create-fix-request" type="command">
  Create structured fix request for dev agent

  Generates `QA_FIX_REQUEST.md` with categorized issues.

  **Visibility:** `[full, quick]`
</ResponseField>

## Command Execution Modes

Many commands support **execution modes** to balance automation vs. control:

<ParamField path="interactive" type="mode" default="true">
  **Balanced, Educational** (5-10 prompts)

  * Explicit decision checkpoints
  * Educational explanations
  * Best for: Learning, complex decisions
</ParamField>

<ParamField path="yolo" type="mode">
  **Fast, Autonomous** (0-1 prompts)

  * Autonomous decision making
  * Minimal user interaction
  * Best for: Simple, deterministic tasks
</ParamField>

<ParamField path="preflight" type="mode">
  **Comprehensive Planning**

  * Upfront analysis phase
  * Identify all ambiguities
  * Zero-ambiguity execution
  * Best for: Ambiguous requirements, critical work
</ParamField>

## Command Resolution

Commands resolve to task files using these patterns:

<ResponseField name="Direct Mapping" type="string">
  Command name matches task file name

  Example: `*develop` → `dev-develop-story.md`
</ResponseField>

<ResponseField name="Prefixed Mapping" type="string">
  Command includes agent prefix

  Example: `*qa-review` → `qa-review-story.md`
</ResponseField>

<ResponseField name="Fuzzy Matching" type="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`
</ResponseField>

## Command Parameters

Commands accept parameters in various formats:

### Positional Parameters

```bash theme={null}
*develop {story-id} {mode}
*create-service {service-type} {service-name}
```

### Named Parameters

```bash theme={null}
*gotchas --category="build" --severity="high"
*worktree-list --status="active"
```

### Flag Parameters

```bash theme={null}
*build-status --all
*rollback --hard
*waves --visual
```

## Command Chaining

Some commands support **workflow chains** for multi-step operations:

```yaml theme={null}
# 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:

```yaml theme={null}
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:

<ParamField path="Ask Mode" type="mode" default="true">
  **\[⚠️ Ask]** - Confirm before destructive operations

  Agent asks permission for:

  * File writes/deletions
  * Git commits
  * External API calls
</ParamField>

<ParamField path="Auto Mode" type="mode">
  **\[🟢 Auto]** - Autonomous execution with logging

  Agent proceeds automatically, logs all decisions.
</ParamField>

<ParamField path="Explore Mode" type="mode">
  **\[🔍 Explore]** - Read-only exploration

  Agent can read files, analyze code, but cannot modify.
</ParamField>

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

## Best Practices

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Error Handling">
    * Validate parameters before execution
    * Provide clear error messages
    * Support graceful degradation
    * Log all failures for debugging
    * Offer recovery options
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Agent Definition Files](/api/agent-definition)
* [Tasks Reference](/api/tasks)
* [Agent Memory System](/api/agent-memory)
* [Workflow Chains](/guides/workflow-chains)

***

*Reference: Agent YAML `commands` section*