Tasks

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:

action
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

Phase 1 → Validate inputs
Phase 2 → Execute primary workflow
Phase 3 → Run quality gates
Phase 4 → Generate outputs
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
Register attempt in `recovery/attempts.json`
Execute task
On success: Mark attempt successful
On failure: Increment failure count
If failures ≥ 3: Trigger stuck detection

### Rollback
Detect stuck condition
Load last good checkpoint
Prompt user: Continue or try different approach?
If rollback: `git checkout {checkpoint}`
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

Reference: .aiox-core/development/tasks/

Configuration

Agent System

Templates & Tasks

Overview

Task Structure

Steps

Phase 1: Phase Name

Step 1: Step Name

Quality Gates

Error Handling

Quality Gates

Error Handling

Task Dependencies

Task Workflow Patterns

Sequential Execution

Parallel Execution

Recovery Workflows

Best Practices

Task Execution Flow

Build docs developers (and LLMs) love

Configuration

Agent System

Templates & Tasks

​Overview

​Task Structure

​Steps

​Phase 1: Phase Name

​Step 1: Step Name

​Quality Gates

​Error Handling

​Quality Gates

​Error Handling

​Task Dependencies

​Task Workflow Patterns

​Sequential Execution

​Parallel Execution

​Recovery Workflows

​Best Practices

​Task Execution Flow

​Related Documentation

Build docs developers (and LLMs) love

Overview

Task Structure

Steps

Phase 1: Phase Name

Step 1: Step Name

Quality Gates

Error Handling

Quality Gates

Error Handling

Task Dependencies

Task Workflow Patterns

Sequential Execution

Parallel Execution

Recovery Workflows

Best Practices

Task Execution Flow

Related Documentation