Tasks

Reference for AIOX task system and executable workflows

Overview

AIOX tasks are executable workflow definitions that agents follow to complete work. Tasks are structured markdown files in .aiox-core/development/tasks/ that define step-by-step procedures, validation criteria, and execution modes.

Location · string

.aiox-core/development/tasks/

Format · string

Markdown with YAML frontmatter

Execution · string

Tasks are executable workflows, not reference documentation

Task Structure

Tasks follow a standardized format:

# Task: {Task Name}

**Task ID:** {task-id}
**Version:** {version}
**Purpose:** {one-line purpose}
**Orchestrator:** {@agent-id}
**Mode:** {execution-mode}
**Quality Standard:** {quality-level}

---

## Overview

{Task description and context}

---

## Execution Modes

{Available execution modes: yolo, interactive, preflight}

---

## Task Definition (AIOX Task Format V1.0)

```yaml
task: taskName()
responsável: {Agent Name}
responsavel_type: Agente
atomic_layer: {Atom|Molecule|Organism}

**Entrada:**
- campo: {field_name}
  tipo: {type}
  origem: {source}
  obrigatório: {true|false}
  validação: {validation-rule}

**Saída:**
- campo: {field_name}
  tipo: {type}
  destino: {destination}
  persistido: {true|false}

---

Steps

Phase 1: Phase Name

Step 1: Step Name

Step description

Input:

• input-item

Process:

1. action
2. action

Output:

• output-item

Validation:

• validation-criterion

---

Quality Gates

Quality checkpoints and validation criteria

---

Error Handling

Error scenarios and recovery procedures

## Task Metadata

<ParamField path="Task ID" type="string" required>
  Unique task identifier (kebab-case)
  
  Example: `dev-develop-story`, `create-agent`, `qa-review-story`
</ParamField>

<ParamField path="Version" type="string" required>
  Task version (semantic versioning)
  
  Example: `1.0`, `2.0`, `3.0`
</ParamField>

<ParamField path="Purpose" type="string" required>
  One-line task purpose statement
  
  Example: `"Execute story development with selectable automation modes"`
</ParamField>

<ParamField path="Orchestrator" type="string" required>
  Primary agent responsible for task execution
  
  Example: `@dev`, `@architect`, `@qa`
</ParamField>

<ParamField path="Mode" type="string">
  Default execution mode
  
  Values: `interactive`, `yolo`, `preflight`
</ParamField>

<ParamField path="Quality Standard" type="string">
  Expected quality level for outputs
  
  Example: `"Production-ready"`, `"AIOX Level (300+ lines)"`
</ParamField>

## Task Categories

### Development Tasks

<ResponseField name="dev-develop-story.md" type="task">
  **Purpose:** Execute story development with selectable automation modes
  
  **Modes:**
  - `interactive` - Balanced, educational (5-10 prompts)
  - `yolo` - Fast, autonomous (0-1 prompts)
  - `preflight` - Comprehensive upfront planning
  
  **Phases:**
  1. Story validation
  2. Task execution
  3. Testing
  4. Quality gates
  5. Completion
  
  **Usage:** `*develop {story-id} [mode]`
</ResponseField>

<ResponseField name="plan-execute-subtask.md" type="task">
  **Purpose:** Execute single subtask using 13-step Coder Agent workflow
  
  **13 Steps:**
  1. Read subtask definition
  2. Analyze requirements
  3. Plan implementation
  4. Execute code changes
  5. Self-critique (mandatory)
  6. Fix issues
  7. Run tests
  8. Update documentation
  9. Commit changes
  10. Verify subtask
  11. Update tracking
  12. Log completion
  13. Prepare handoff
  
  **Usage:** `*execute-subtask {subtask-id}`
</ResponseField>

<ResponseField name="create-service.md" type="task">
  **Purpose:** Create new service from Handlebars template
  
  **Service Types:**
  - `api-integration` - External API client
  - `utility` - Utility service
  - `agent-tool` - MCP tool integration
  
  **Generates:**
  - Service implementation file
  - Interface/types file
  - Configuration file
  - Test suite
  - Documentation
  
  **Usage:** `*create-service {type} {name}`
</ResponseField>

### Quality Assurance Tasks

<ResponseField name="qa-review-story.md" type="task">
  **Purpose:** Comprehensive story quality review
  
  **Review Areas:**
  - Code quality
  - Test coverage
  - Documentation completeness
  - Acceptance criteria validation
  - Performance assessment
  - Security review
  
  **Outputs:**
  - Quality report
  - Issue list (if any)
  - Recommendations
  - Approval/rejection decision
</ResponseField>

<ResponseField name="qa-generate-tests.md" type="task">
  **Purpose:** Generate comprehensive test suite
  
  **Test Types:**
  - Unit tests (React Testing Library)
  - Integration tests
  - E2E tests
  - Visual regression tests
  - Accessibility tests (jest-axe)
  
  **Coverage Target:** ≥85% (statements/functions/branches)
</ResponseField>

<ResponseField name="qa-fix-issues.md" type="task">
  **Purpose:** Fix QA issues from fix request document
  
  **8-Phase Workflow:**
  1. Parse QA_FIX_REQUEST.md
  2. Prioritize issues
  3. Fix critical issues
  4. Fix high-priority issues
  5. Fix medium-priority issues
  6. Re-run tests
  7. Update documentation
  8. Request re-review
</ResponseField>

### Architecture Tasks

<ResponseField name="architect-analyze-impact.md" type="task">
  **Purpose:** Analyze architectural impact of proposed changes
  
  **Analysis Dimensions:**
  - Performance impact
  - Security implications
  - Scalability concerns
  - Integration complexity
  - Maintenance burden
  - Cost implications
  
  **Outputs:**
  - Impact analysis report
  - Risk assessment
  - Recommendations
  - Mitigation strategies
</ResponseField>

### Agent Creation Tasks

<ResponseField name="create-agent.md" type="task">
  **Purpose:** Create domain-specific agent through research and elicitation
  
  **Version:** 3.0 (includes operational infrastructure)
  
  **Phases:**
  0. IDS Registry Check (advisory)
  1. Research - Deep research on specialist/domain
  2. Extraction - Extract framework from research
  3. Creation - Generate agent using template
  4. Validation - Run quality gate SC_AGT_001
  5. Operational Infrastructure - Generate command_loader, tasks, templates
  6. Operational Validation - Validate maturity level
  
  **Quality Standard:** AIOX Level (300+ lines, voice DNA, output examples)
  
  **Usage:** `*create-agent {domain} [specialist]`
</ResponseField>

### Database Tasks

<ResponseField name="db-schema-audit.md" type="task">
  **Purpose:** Comprehensive database schema validation and optimization
  
  **Audits:**
  - Schema design patterns
  - Index optimization
  - RLS (Row-Level Security) policies
  - Performance hotpaths
  - Migration integrity
  
  **Outputs:**
  - Audit report
  - Optimization recommendations
  - Migration scripts (if needed)
</ResponseField>

<ResponseField name="db-apply-migration.md" type="task">
  **Purpose:** Apply database migration with rollback safety
  
  **Safety Checks:**
  - Backup verification
  - Dry-run execution
  - Impact assessment
  - Rollback plan
  - Post-migration validation
</ResponseField>

## Task Execution Modes

<ParamField path="interactive" type="mode" default="true">
  **Balanced, Educational** (5-10 prompts)
  
  - Explicit decision checkpoints
  - Educational explanations
  - User confirmation for key decisions
  - Best for: Learning, complex decisions
</ParamField>

<ParamField path="yolo" type="mode">
  **Fast, Autonomous** (0-1 prompts)
  
  - Autonomous decision making
  - Minimal user interaction
  - Detailed logging of all decisions
  - Best for: Simple, deterministic tasks
</ParamField>

<ParamField path="preflight" type="mode">
  **Comprehensive Planning**
  
  - Upfront analysis phase
  - Identify all ambiguities before execution
  - Zero-ambiguity execution
  - Best for: Ambiguous requirements, critical work
</ParamField>

## Task Format Specification

### AIOX Task Format V1.0

<ParamField path="task" type="string" required>
  Task function signature
  
  Example: `devDevelopStory()`, `createAgent(domain, specialist)`
</ParamField>

<ParamField path="responsável" type="string" required>
  Agent responsible for execution
  
  Example: `"Dex (Builder)"`, `"Aria (Visionary)"`
</ParamField>

<ParamField path="responsavel_type" type="string" required>
  Responsibility type
  
  Value: `"Agente"` (always)
</ParamField>

<ParamField path="atomic_layer" type="string" required>
  Atomic design layer classification
  
  Values: `Atom`, `Molecule`, `Organism`
  
  - **Atom** - Single-purpose, minimal dependencies
  - **Molecule** - Combines multiple atoms
  - **Organism** - Complex, multi-phase workflows
</ParamField>

### Input/Output Schema

<ParamField path="Entrada" type="array" required>
  Task input parameters
  
  <Expandable title="input schema">
    <ResponseField name="campo" type="string" required>
      Field name
    </ResponseField>
    
    <ResponseField name="tipo" type="string" required>
      Data type: `string`, `object`, `array`, `boolean`, `number`
    </ResponseField>
    
    <ResponseField name="origem" type="string" required>
      Input source: `User Input`, `System`, `File`, `API`
    </ResponseField>
    
    <ResponseField name="obrigatório" type="boolean" required>
      Whether field is required
    </ResponseField>
    
    <ResponseField name="validação" type="string">
      Validation rules
      
      Example: `"Must be registered task"`, `"yolo|interactive|preflight"`
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="Saída" type="array" required>
  Task output schema
  
  <Expandable title="output schema">
    <ResponseField name="campo" type="string" required>
      Output field name
    </ResponseField>
    
    <ResponseField name="tipo" type="string" required>
      Data type
    </ResponseField>
    
    <ResponseField name="destino" type="string" required>
      Output destination: `Memory`, `File`, `API`, `Database`
    </ResponseField>
    
    <ResponseField name="persistido" type="boolean" required>
      Whether output is persisted to disk
    </ResponseField>
  </Expandable>
</ParamField>

## Task Phases

Large tasks are organized into **phases** with clear checkpoints:

```markdown
## Phase 1: Context Gathering

### Step 1.1: Load Story
**Process:**
1. Read story file from `docs/stories/{story-id}.md`
2. Validate story status is not `draft`
3. Extract acceptance criteria

**Validation:**
- [ ] Story file exists
- [ ] Story is not in draft mode
- [ ] Acceptance criteria are clear

**Checkpoint:** Story validated, proceed to Phase 2

---

## Phase 2: Implementation

{...}

Quality Gates

Tasks include quality gates that must pass:

Quality Gate Format · structure

## Quality Gate: {gate-name}

**Must Pass Before:** {next-phase}

### Criteria
- [ ] {criterion-1}
- [ ] {criterion-2}
- [ ] {criterion-3}

### Validation Method
{how-to-validate}

### On Failure
{recovery-action}

Error Handling

Tasks define error scenarios and recovery:

Error Handling Pattern · structure

## Error Scenarios

### Error: {error-name}

**Trigger:** {when-occurs}

**Detection:**
- {how-to-detect}

**Recovery:**
1. {recovery-step-1}
2. {recovery-step-2}

**Escalation:**
If recovery fails: {escalation-action}

Task Dependencies

Tasks can depend on other tasks, checklists, and scripts:

# From agent definition
dependencies:
  tasks:
    - dev-develop-story.md      # Main development task
    - plan-execute-subtask.md   # Subtask execution
    - verify-subtask.md         # Verification
  checklists:
    - story-dod-checklist.md    # Definition of Done
    - self-critique-checklist.md
  scripts:
    - build-orchestrator.js
    - recovery-tracker.js

Task Workflow Patterns

Sequential Execution

## Execution Order

1. Phase 1 → Validate inputs
2. Phase 2 → Execute primary workflow
3. Phase 3 → Run quality gates
4. Phase 4 → Generate outputs
5. Phase 5 → Update tracking

Parallel Execution

## Wave Analysis (WIS-4)

Tasks can be executed in **waves** (parallel batches):

**Wave 1:** (No dependencies)
- Task A
- Task B
- Task C

**Wave 2:** (Depends on Wave 1)
- Task D (depends on A, B)
- Task E (depends on A)

**Wave 3:** (Depends on Wave 2)
- Task F (depends on D, E)

Recovery Workflows

## Recovery System (Epic 5)

### Attempt Tracking
1. Register attempt in `recovery/attempts.json`
2. Execute task
3. On success: Mark attempt successful
4. On failure: Increment failure count
5. If failures ≥ 3: Trigger stuck detection

### Rollback
1. Detect stuck condition
2. Load last good checkpoint
3. Prompt user: Continue or try different approach?
4. If rollback: `git checkout {checkpoint}`
5. Update approach documentation

Best Practices

Task Design

• Keep tasks focused and atomic
• Define clear input/output contracts
• Include validation at each step
• Provide error handling for all scenarios
• Support multiple execution modes
• Document quality standards

Phase Organization

• Group related steps into phases
• Include checkpoints between phases
• Define clear exit criteria for each phase
• Allow for phase rollback if needed
• Keep phases self-contained

Validation

• Validate inputs before execution
• Include quality gates at key points
• Test both success and failure paths
• Document expected vs. actual outcomes
• Provide clear validation criteria

Documentation

• Explain why, not just what
• Include examples for complex steps
• Document assumptions clearly
• Reference related tasks and checklists
• Keep version history

Task Execution Flow

Related Documentation

• Agent Commands
• Templates
• Checklists
• Task Development Guide

---

Reference: .aiox-core/development/tasks/