AIOX Task Format Specification V1.0

Date: 2025-11-13
Version: 1.0.0
Status: Standard
Author: Brad Frost Cognitive Clone

Purpose

This document defines the UNIVERSAL format for AIOX Tasks, ensuring consistency, scalability, and reusability across workflows, executors, and teams.

Task Format Overview

Every AIOX Task MUST follow this structure:

#### Step X: [Task Name]

task: taskIdentifier()
responsável: [Role or Service Name]
responsavel_type: Agente | Worker | Humano | Clone
atomic_layer: [Atom | Molecule | Organism | Template | Page | Config | Strategy | Content | Media | Layout | Analysis]

**Entrada:**
- campo: [name]
  tipo: [type]
  origem: [source step]
  obrigatório: [true|false]
  padrão: [default value] (optional)

**Saída:**
- campo: [name]
  tipo: [type]
  destino: [destination step(s)]
  persistido: [true|false]

**Checklist:**
  pre-conditions:
    - [ ] [condition description]
      tipo: pre-condition
      blocker: [true|false]
      validação: [validation logic or test path]
  
  post-conditions:
    - [ ] [condition description]
      tipo: post-condition
      blocker: [true|false]
      validação: [validation logic or test path]
  
  acceptance-criteria:
    - [ ] [acceptance description]
      tipo: acceptance
      blocker: [false]
      story: [STORY-XXX]
      manual_check: [true|false]

**Template:** (optional)
- path: [relative path to template file]
- type: [input|output|prompt|ui|script]
- version: [X.Y.Z]
- variables: [array of variable names]

**Tools:** (optional)
- [tool_name]:
    version: [X.Y.Z]
    used_for: [description]
    shared_with: [array of step IDs]

**Scripts:** (optional)
- [script_path]:
    description: [what it does]
    language: [javascript|python|bash|etc]

**Performance:**
- duration_expected: [X]ms
- cost_estimated: $[Y] (for AI executors)
- cacheable: [true|false]
- cache_key: [cache identifier] (if cacheable)
- parallelizable: [true|false]
- parallel_with: [array of step IDs] (if parallelizable)
- skippable_when: [array of conditions]

**Error Handling:**
- strategy: [retry|fallback|abort]
- fallback: [description or default value] (if strategy=fallback)
- retry:
    max_attempts: [N]
    backoff: [linear|exponential]
    backoff_ms: [initial backoff in milliseconds]
- abort_workflow: [true|false]
- notification: [log|email|slack|etc]

**Metadata:**
- story: [STORY-XXX]
- version: [X.Y.Z]
- dependencies: [array of step IDs]
- breaking_changes: [array of changes from previous version]
- author: [name]
- created_at: [YYYY-MM-DD]
- updated_at: [YYYY-MM-DD]

Field Definitions

Required Fields

1. `task`

Type: string (function name)
Required: ✅ Yes
Format: camelCase() with parentheses

Purpose: Unique identifier for the task function.

Validation:

Must be unique across workflow
Must be valid JavaScript function name
Must end with ()

Examples:

task: loadFormatConfig()
task: analyzeBrief()
task: designCTAComponent()

2. `responsável`

Type: string
Required: ✅ Yes
Format: Free text (role or service name)

Purpose: Human-readable name of the responsible entity.

Examples:

responsável: Creative Director
responsável: format-loader.js
responsável: OpenRouter Vision Model
responsável: Brad Frost Clone

3. `responsavel_type`

Type: enum
Required: ✅ Yes
Values: Agente | Worker | Humano | Clone

Purpose: Defines the executor type for orchestration, cost tracking, and error handling.

Validation:

Must be one of the 4 allowed values
Determines execution environment

Decision Tree: See EXECUTOR-DECISION-TREE.md

Examples:

responsavel_type: Agente  # AI-powered execution
responsavel_type: Worker  # Script-based execution
responsavel_type: Humano  # Manual human execution
responsavel_type: Clone   # Mind emulation with heuristics

4. `atomic_layer`

Type: enum
Required: ✅ Yes (for design-related tasks), ⚠️ Optional (for config/strategy)
Values:

Atomic Design: Atom | Molecule | Organism | Template | Page
Other Layers: Config | Strategy | Content | Media | Layout | Analysis

Purpose: Maps task to Atomic Design layer for architecture validation.

Validation:

Design tasks MUST specify Atomic Design layer
Non-design tasks SHOULD specify functional layer

Examples:

atomic_layer: Atom       # Step 7a: Design CTA (single component)
atomic_layer: Molecule   # Step 8a: Compose Text Group (title + body + cta)
atomic_layer: Organism   # Step 8c: Content Area (complete section)
atomic_layer: Template   # Step 13: Render HTML (structure)
atomic_layer: Page       # Step 14: Export PNG (final instance)
atomic_layer: Config     # Step 1: Load Format Config
atomic_layer: Strategy   # Step 3: Analyze Brief

5. `Entrada` (Inputs)

Type: array of objects
Required: ✅ Yes (can be empty array if no inputs)

Purpose: Defines all inputs required by the task, with types, sources, and constraints.

Structure:

**Entrada:**
- campo: [field name]
  tipo: [type definition]
  origem: [source step or config]
  obrigatório: [true|false]
  padrão: [default value] (optional)
  validação: [validation rule] (optional)

Field Details:

Sub-field	Type	Required	Description
`campo`	string	✅ Yes	Field name (camelCase)
`tipo`	string	✅ Yes	Type definition (see Type System below)
`origem`	string	✅ Yes	Source step ID or "config" or "user input"
`obrigatório`	boolean	✅ Yes	Whether field is required
`padrão`	any	⚠️ Optional	Default value if not provided
`validação`	string	⚠️ Optional	Validation rule or JSON Schema reference

Examples:

**Entrada:**
- campo: adCopy
  tipo: object { title: string, body: string, cta: string }
  origem: Step 5 (craftCopy)
  obrigatório: true
  validação: |
    title.length >= 1 && title.length <= 100
    body.length >= 1 && body.length <= 500
    cta.length >= 1 && cta.length <= 30

- campo: brand
  tipo: object (Brand schema)
  origem: Step 2 (loadBrand)
  obrigatório: true

- campo: ready_copy
  tipo: object { title?, body?, cta? } | null
  origem: User Input (config)
  obrigatório: false
  padrão: null

6. `Saída` (Outputs)

Type: array of objects
Required: ✅ Yes (can be empty array if no outputs)

Purpose: Defines all outputs produced by the task, with types, destinations, and persistence.

Structure:

**Saída:**
- campo: [field name]
  tipo: [type definition]
  destino: [destination step(s) or state]
  persistido: [true|false]
  cache_key: [key] (if cacheable)

Field Details:

Sub-field	Type	Required	Description
`campo`	string	✅ Yes	Field name (camelCase)
`tipo`	string	✅ Yes	Type definition
`destino`	string or array	✅ Yes	Destination step(s) or "state" or "output"
`persistido`	boolean	✅ Yes	Whether saved to ad-spec.json or DB
`cache_key`	string	⚠️ Optional	Cache key if output is cacheable

Examples:

**Saída:**
- campo: formatConfig
  tipo: object { formatId, canvas, safeZones, contentArea }
  destino: [Step 8, Step 10, Step 11, Step 12, Step 13, Step 14]
  persistido: false  # Kept in memory only

- campo: adAnalysis
  tipo: object { goal, targetAudience, urgencyLevel, emotionalTriggers }
  destino: state (ad-spec.json)
  persistido: true

- campo: designTokens
  tipo: object { spacing, typography, colors, radius, shadows }
  destino: Step 13 (renderHTML)
  persistido: false
  cache_key: format_${formatConfig.formatId}_${formatConfig.orientation}

Optional Fields

7. `Checklist`

Type: object with arrays
Required: ⚠️ Recommended

Purpose: Defines validations (pre-conditions, post-conditions, acceptance criteria) for automated and manual testing.

Structure:

**Checklist:**
  pre-conditions:
    - [ ] [description]
      tipo: pre-condition
      blocker: [true|false]
      validação: [logic or test path]
      error_message: [message if fails]
  
  post-conditions:
    - [ ] [description]
      tipo: post-condition
      blocker: [true|false]
      validação: [logic or test path]
      rollback: [true|false]
  
  acceptance-criteria:
    - [ ] [description]
      tipo: acceptance
      blocker: false
      story: [STORY-XXX]
      manual_check: [true|false]
      test: [test file path]

Checklist Types:

Pre-conditions (Run BEFORE task)
- Validate inputs exist and are valid
- Check dependencies are met
- Verify environment is ready
- Blocking: Task aborts if pre-condition fails
Post-conditions (Run AFTER task)
- Validate outputs match schema
- Check business rules
- Verify no side effects
- Blocking: Task rolls back if post-condition fails
Acceptance Criteria (Run AFTER workflow)
- Validate Story requirements
- Can be manual (human review)
- Can be automated (integration tests)
- Non-blocking: Log failure, continue workflow

Examples:

**Checklist:**
  pre-conditions:
    - [ ] brand.typography exists and is valid
      tipo: pre-condition
      blocker: true
      validação: |
        if (!brand.typography || !brand.typography.primaryFont) {
          throw new Error("Brand typography not loaded");
        }
      error_message: "Brand typography missing or invalid"
    
    - [ ] adCopy.title is not empty
      tipo: pre-condition
      blocker: true
      validação: "expect(adCopy.title).toBeTruthy()"
      error_message: "Copy title is required"
  
  post-conditions:
    - [ ] typography.title.htmlContent is valid HTML
      tipo: post-condition
      blocker: true
      validação: |
        const isValid = await validateHTML(typography.title.htmlContent);
        if (!isValid) throw new Error("Invalid HTML");
      rollback: false
    
    - [ ] All required transformations applied
      tipo: post-condition
      blocker: true
      validação: |
        expect(typography.title.transformations).toBeInstanceOf(Array);
        expect(typography.title.transformations.length).toBeGreaterThan(0);
      rollback: false
  
  acceptance-criteria:
    - [ ] Typography matches brand voice (bold, uppercase for urgent CTAs)
      tipo: acceptance
      blocker: false
      story: STORY-006
      manual_check: false
      test: "tests/typography-brand-voice.test.js"
    
    - [ ] Transformations are visually appealing
      tipo: acceptance
      blocker: false
      story: STORY-006
      manual_check: true

8. `Template`

Type: object
Required: ⚠️ Optional (but recommended for Agente executors)

Purpose: References template files that define input/output schemas, prompts, or UI forms.

Structure:

**Template:**
- path: [relative path]
  type: [input|output|prompt|ui|script]
  version: [X.Y.Z]
  variables: [array of variable names used in template]
  schema: [JSON Schema reference] (optional)

Template Types:

Type	Purpose	Example
`input`	Validates input schema	`templates/input-schemas/analyze-brief.json`
`output`	Validates output schema	`templates/output-schemas/analyze-brief.json`
`prompt`	AI agent prompt structure	`Squads/.../analyze-ad-brief.md`
`ui`	Human interface form	`templates/ui-forms/manual-approval.html`
`script`	Worker script template	`templates/scripts/image-processor.sh`

Examples:

# Agente executor with prompt template
**Template:**
- path: Squads/instagram-content-creator/tasks/ads/analyze-ad-brief.md
  type: prompt
  version: 2.1.0
  variables: [brief_text, brand_id, campaign_goal, ready_copy]
  schema: Squads/instagram-content-creator/schemas/analyze-brief-output.json

# Worker executor with script template
**Template:**
- path: scripts/utils/format-loader.js
  type: script
  version: 1.0.0
  variables: [format_id, orientation]
  
# Humano executor with UI form
**Template:**
- path: templates/ui-forms/manual-review-ad-quality.html
  type: ui
  version: 1.0.0
  variables: [ad_preview_url, quality_criteria]

9. `Tools`

Type: object
Required: ⚠️ Recommended (to document reusability)

Purpose: Catalogs reusable tools/functions used by the task, enabling:

Reusability tracking (which tasks share tools)
Versioning (tool updates affect which tasks)
Cost tracking (tool API costs)

Structure:

**Tools:**
- [tool_name]:
    version: [X.Y.Z]
    used_for: [description]
    shared_with: [array of step IDs or "global"]
    cost: $[Y] per call (optional)
    cacheable: [true|false] (optional)

Examples:

**Tools:**
- callAgent:
    version: 1.0.0
    used_for: AIOX agent caller with retry logic
    shared_with: [Step 3, Step 4, Step 5, Step 6, Step 7, Step 8, Step 9, Step 11]
    cost: varies by agent
    
- validateHTML:
    version: 2.1.0
    used_for: HTML validation using htmlhint
    shared_with: [Step 6, Step 13]
    
- detectFaces:
    version: 1.0.0
    used_for: Face detection via OpenRouter Gemini 2.5 Flash
    shared_with: [Step 10]
    cost: $0.002 per image
    
- validateContrast:
    version: 1.0.0
    used_for: WCAG AA color contrast validation
    shared_with: [Step 2, Step 7]

10. `Scripts`

Type: object
Required: ⚠️ Optional (for Worker executors primarily)

Purpose: References custom scripts executed by the task.

Structure:

**Scripts:**
- [script_path]:
    description: [what it does]
    language: [javascript|python|bash|etc]
    version: [X.Y.Z] (optional)

Examples:

**Scripts:**
- scripts/utils/format-loader.js:
    description: Loads format configuration from JSON file
    language: javascript
    version: 1.0.0
    
- scripts/utils/face-detection.js:
    description: Wrapper for OpenRouter face detection API
    language: javascript
    version: 1.2.0
    
- scripts/export/puppeteer-renderer.js:
    description: Renders HTML to PNG using Puppeteer
    language: javascript
    version: 2.0.0

11. `Performance`

Type: object
Required: ⚠️ Recommended (for optimization)

Purpose: Documents expected performance metrics and optimization opportunities.

Structure:

**Performance:**
- duration_expected: [X]ms
- cost_estimated: $[Y] (for AI)
- cacheable: [true|false]
- cache_key: [identifier] (if cacheable)
- parallelizable: [true|false]
- parallel_with: [array of step IDs]
- skippable_when: [array of conditions]

Examples:

# AI task (expensive, slow, not cacheable)
**Performance:**
- duration_expected: 3500ms
- cost_estimated: $0.0015
- cacheable: false
- parallelizable: false

# Config load (fast, cacheable)
**Performance:**
- duration_expected: 100ms
- cost_estimated: $0
- cacheable: true
- cache_key: format_${format_id}_${orientation}
- parallelizable: false

# Image selection (can run in parallel with template selection)
**Performance:**
- duration_expected: 2500ms
- cost_estimated: $0.001
- cacheable: false
- parallelizable: true
- parallel_with: [Step 4]

# Brief analysis (skippable in ready_copy mode)
**Performance:**
- duration_expected: 4000ms
- cost_estimated: $0.0025
- cacheable: false
- parallelizable: false
- skippable_when: [ready_copy=true]

12. `Error Handling`

Type: object
Required: ⚠️ Recommended (for robustness)

Purpose: Defines error handling strategy for resilience.

Structure:

**Error Handling:**
- strategy: [retry|fallback|abort]
- fallback: [description or value] (if strategy=fallback)
- retry:
    max_attempts: [N]
    backoff: [linear|exponential]
    backoff_ms: [initial delay]
- abort_workflow: [true|false]
- notification: [log|email|slack|etc]

Strategies:

Strategy	When to Use	Example
`retry`	Transient errors (API timeout, rate limit)	AI agent call failed with 429
`fallback`	Recoverable errors (AI failed, use default)	Template selection → fallback to default
`abort`	Critical errors (invalid brand_id, missing template)	Brand not found → abort workflow

Examples:

# AI task with retry + fallback
**Error Handling:**
- strategy: fallback
- fallback: |
    If AI fails, use config.ready_copy as analysis.
    If ready_copy not available, use default analysis:
      { goal: "conversion", urgencyLevel: "medium", targetAudience: "general" }
- retry:
    max_attempts: 3
    backoff: exponential
    backoff_ms: 1000
- abort_workflow: false
- notification: log

# Config load (critical - abort on failure)
**Error Handling:**
- strategy: abort
- retry:
    max_attempts: 2
    backoff: linear
    backoff_ms: 500
- abort_workflow: true
- notification: email + slack

13. `Metadata`

Type: object
Required: ⚠️ Recommended (for traceability)

Purpose: Links task to Stories, versions, and dependencies for project management.

Structure:

**Metadata:**
- story: [STORY-XXX]
- version: [X.Y.Z]
- dependencies: [array of step IDs]
- breaking_changes: [array of changes]
- author: [name]
- created_at: [YYYY-MM-DD]
- updated_at: [YYYY-MM-DD]

Examples:

**Metadata:**
- story: STORY-010.1
- version: 2.1.0
- dependencies: [Step 10]
- breaking_changes:
    - Output format changed: added computedSpacing object
    - Removed nested fallback (SMELL 1 fix)
- author: Brad Frost Clone
- created_at: 2025-11-10
- updated_at: 2025-11-13

Type System

Basic Types

string        # Text
number        # Number (integer or float)
boolean       # true or false
null          # Null value
any           # Any type (avoid when possible)

Complex Types

array         # Array of items
array<string> # Array of strings
array<number> # Array of numbers

object        # Generic object
object { key: type, key: type }  # Object with defined keys

Optional Types

string | null           # String or null
object { key?: type }   # Object with optional key (? suffix)

Custom Types (Reference Schemas)

Brand                  # References schemas/Brand.json
FormatConfig           # References schemas/FormatConfig.json
AdAnalysis             # References schemas/AdAnalysis.json

Examples:

- campo: adCopy
  tipo: object { title: string, body: string, cta: string }

- campo: faces
  tipo: array<object { top: number, left: number, bottom: number, right: number }>

- campo: ready_copy
  tipo: object { title?: string, body?: string, cta?: string } | null

- campo: brand
  tipo: Brand  # References schemas/Brand.json

Validation Rules

Required Field Validation

function validateTask(task) {
  const required = ['task', 'responsável', 'responsavel_type', 'atomic_layer', 'Entrada', 'Saída'];
  
  for (const field of required) {
    if (!task[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }
  
  // Validate executor type
  const validExecutors = ['Agente', 'Worker', 'Humano', 'Clone'];
  if (!validExecutors.includes(task.responsavel_type)) {
    throw new Error(`Invalid responsavel_type: ${task.responsavel_type}`);
  }
  
  // Validate atomic layer
  const validLayers = ['Atom', 'Molecule', 'Organism', 'Template', 'Page', 'Config', 'Strategy', 'Content', 'Media', 'Layout', 'Analysis'];
  if (!validLayers.includes(task.atomic_layer)) {
    throw new Error(`Invalid atomic_layer: ${task.atomic_layer}`);
  }
  
  return true;
}

Input/Output Validation

function validateInputOutput(io, type) {
  const required = ['campo', 'tipo', 'origem', 'obrigatório'];
  
  for (const item of io) {
    for (const field of required) {
      if (!item[field] && field !== 'origem') {  // origem not required for output
        throw new Error(`${type} missing required field: ${field}`);
      }
    }
  }
  
  return true;
}

Examples by Executor Type

Agente (AI-Powered)

#### Step 3: Analyze Brief

task: analyzeBrief()
responsável: Ad Strategist
responsavel_type: Agente
atomic_layer: Strategy

**Entrada:**
- campo: brief_text
  tipo: string
  origem: User Input (config)
  obrigatório: true
  validação: "length >= 50"

- campo: brand
  tipo: Brand
  origem: Step 2 (loadBrand)
  obrigatório: true

- campo: ready_copy
  tipo: object { title?, body?, cta? } | null
  origem: User Input (config)
  obrigatório: false
  padrão: null

**Saída:**
- campo: adAnalysis
  tipo: object { goal, targetAudience, urgencyLevel, emotionalTriggers, keyMessage }
  destino: state (ad-spec.json)
  persistido: true

**Checklist:**
  pre-conditions:
    - [ ] brief_text has minimum 50 characters
      tipo: pre-condition
      blocker: true
      validação: "expect(brief_text.length).toBeGreaterThanOrEqual(50)"
  
  post-conditions:
    - [ ] adAnalysis contains all required fields
      tipo: post-condition
      blocker: true
      validação: |
        expect(adAnalysis.goal).toBeTruthy();
        expect(adAnalysis.urgencyLevel).toMatch(/high|medium|low/);
  
  acceptance-criteria:
    - [ ] Analysis aligns with brand voice
      tipo: acceptance
      blocker: false
      story: STORY-003
      manual_check: false
      test: "tests/brief-analysis-brand-alignment.test.js"

**Template:**
- path: Squads/instagram-content-creator/tasks/ads/analyze-ad-brief.md
  type: prompt
  version: 2.1.0
  variables: [brief_text, brand_id, campaign_goal, ready_copy]

**Tools:**
- callAgent:
    version: 1.0.0
    used_for: Execute AI agent with retry
    shared_with: [Step 4, Step 5, Step 6, Step 7, Step 8, Step 9, Step 11]

**Scripts:**
- N/A

**Performance:**
- duration_expected: 4000ms
- cost_estimated: $0.0025
- cacheable: false
- parallelizable: false
- skippable_when: [ready_copy=true]

**Error Handling:**
- strategy: fallback
- fallback: |
    Use config.ready_copy as analysis if available.
    Otherwise, use default analysis: { goal: "conversion", urgencyLevel: "medium", targetAudience: "general" }
- retry:
    max_attempts: 3
    backoff: exponential
    backoff_ms: 1000
- abort_workflow: false
- notification: log

**Metadata:**
- story: STORY-003
- version: 2.0.0
- dependencies: [Step 2]
- breaking_changes: []
- author: Creative Team
- created_at: 2025-10-01
- updated_at: 2025-11-10

Worker (Script-Based)

#### Step 1: Load Format Configuration

task: loadFormatConfig()
responsável: format-loader.js
responsavel_type: Worker
atomic_layer: Config

**Entrada:**
- campo: format_id
  tipo: string
  origem: User Input (config)
  obrigatório: true
  validação: "format_id in ['instagram-stories', 'instagram-reels', 'instagram-feed-square', 'instagram-feed-portrait']"

- campo: orientation
  tipo: string
  origem: User Input (config)
  obrigatório: false
  padrão: "portrait"
  validação: "orientation in ['portrait', 'landscape']"

**Saída:**
- campo: formatConfig
  tipo: FormatConfig
  destino: [Step 8, Step 10, Step 11, Step 12, Step 13, Step 14]
  persistido: false

**Checklist:**
  pre-conditions:
    - [ ] format_id is valid
      tipo: pre-condition
      blocker: true
      validação: |
        const validFormats = ['instagram-stories', 'instagram-reels', 'instagram-feed-square', 'instagram-feed-portrait'];
        if (!validFormats.includes(format_id)) {
          throw new Error(`Invalid format_id: ${format_id}`);
        }
  
  post-conditions:
    - [ ] formatConfig.safeZones are defined
      tipo: post-condition
      blocker: true
      validação: |
        expect(formatConfig.safeZones).toBeDefined();
        expect(formatConfig.safeZones.top).toBeGreaterThan(0);
    
    - [ ] formatConfig.contentArea.height calculated correctly
      tipo: post-condition
      blocker: true
      validação: |
        const expectedHeight = formatConfig.canvas.height - formatConfig.safeZones.top - formatConfig.safeZones.bottom;
        expect(formatConfig.contentArea.height).toBe(expectedHeight);

**Template:**
- path: config/ad-formats.json
  type: input
  version: 1.0.0
  variables: [format_id, orientation]
  schema: schemas/FormatConfig.json

**Tools:**
- N/A

**Scripts:**
- scripts/utils/format-loader.js:
    description: Reads format JSON and calculates content area
    language: javascript
    version: 1.0.0

**Performance:**
- duration_expected: 50ms
- cost_estimated: $0
- cacheable: true
- cache_key: format_${format_id}_${orientation}
- parallelizable: true
- parallel_with: [Step 2]
- skippable_when: []

**Error Handling:**
- strategy: abort
- retry:
    max_attempts: 2
    backoff: linear
    backoff_ms: 100
- abort_workflow: true
- notification: log + email

**Metadata:**
- story: DECISION-02
- version: 1.0.0
- dependencies: []
- breaking_changes: []
- author: Brad Frost Clone
- created_at: 2025-11-10
- updated_at: 2025-11-10

Humano (Manual Review)

#### Step 15: Quality Review (Optional)

task: reviewAdQuality()
responsável: Quality Assurance Team
responsavel_type: Humano
atomic_layer: Page

**Entrada:**
- campo: final_ad_png
  tipo: string (file path)
  origem: Step 14 (exportPNG)
  obrigatório: true

- campo: ad_spec
  tipo: object (complete ad specification)
  origem: state (ad-spec.json)
  obrigatório: true

- campo: quality_criteria
  tipo: array<string>
  origem: config
  obrigatório: true
  padrão: ["brand_alignment", "text_legibility", "visual_appeal", "no_face_coverage"]

**Saída:**
- campo: quality_review
  tipo: object { approved: boolean, score: number, feedback: string, reviewer: string }
  destino: state (ad-spec.json)
  persistido: true

**Checklist:**
  pre-conditions:
    - [ ] final_ad_png file exists
      tipo: pre-condition
      blocker: true
      validação: |
        const fs = require('fs');
        if (!fs.existsSync(final_ad_png)) {
          throw new Error(`Ad PNG not found: ${final_ad_png}`);
        }
  
  acceptance-criteria:
    - [ ] Ad meets all quality criteria
      tipo: acceptance
      blocker: false
      story: STORY-QA
      manual_check: true
    
    - [ ] Reviewer provided detailed feedback
      tipo: acceptance
      blocker: false
      story: STORY-QA
      manual_check: true

**Template:**
- path: templates/ui-forms/quality-review-form.html
  type: ui
  version: 1.0.0
  variables: [final_ad_png, ad_spec, quality_criteria]

**Tools:**
- N/A

**Scripts:**
- N/A

**Performance:**
- duration_expected: 180000ms  # 3 minutes (manual review)
- cost_estimated: $5  # Human labor cost
- cacheable: false
- parallelizable: false
- skippable_when: [skip_qa=true, batch_mode=true]

**Error Handling:**
- strategy: fallback
- fallback: Auto-approve if reviewer doesn't respond within 10 minutes
- retry:
    max_attempts: 1
    backoff: linear
    backoff_ms: 600000  # 10 minutes
- abort_workflow: false
- notification: slack

**Metadata:**
- story: STORY-QA
- version: 1.0.0
- dependencies: [Step 14]
- breaking_changes: []
- author: QA Team
- created_at: 2025-11-13
- updated_at: 2025-11-13

Clone (Mind Emulation)

#### Step 7c: Validate Components (Brad Frost Clone)

task: validateComponentsAtomicDesign()
responsável: Brad Frost Clone
responsavel_type: Clone
atomic_layer: Atom

**Entrada:**
- campo: ctaComponent
  tipo: object { text, style, colors }
  origem: Step 7a (designCTAComponent)
  obrigatório: true

- campo: badgeComponent
  tipo: object { text, style, colors } | null
  origem: Step 7b (designBadgeComponent)
  obrigatório: false

**Saída:**
- campo: validation_result
  tipo: object { valid: boolean, violations: array<object { rule, severity, message }> }
  destino: state (ad-spec.json)
  persistido: true

**Checklist:**
  pre-conditions:
    - [ ] ctaComponent exists
      tipo: pre-condition
      blocker: true
      validação: "expect(ctaComponent).toBeDefined()"
  
  post-conditions:
    - [ ] No Atomic Design violations detected
      tipo: post-condition
      blocker: true
      validação: |
        if (!validation_result.valid) {
          const criticalViolations = validation_result.violations.filter(v => v.severity === 'critical');
          if (criticalViolations.length > 0) {
            throw new Error(`Atomic Design violations: ${criticalViolations.map(v => v.message).join(', ')}`);
          }
        }
    
    - [ ] All components are context-agnostic (no positioning)
      tipo: post-condition
      blocker: true
      validação: |
        if (ctaComponent.position || ctaComponent.size) {
          throw new Error("CTA component has positioning data (DECISION-03 violation)");
        }
        if (badgeComponent && (badgeComponent.position || badgeComponent.size)) {
          throw new Error("Badge component has positioning data (DECISION-03 violation)");
        }
  
  acceptance-criteria:
    - [ ] Components follow Brad Frost's Atomic Design principles
      tipo: acceptance
      blocker: false
      story: DECISION-03
      manual_check: false

**Clone Configuration:**
- heuristics: clones/brad_frost/heuristics.yaml
- axioms: clones/brad_frost/axioms.yaml
- ai_fallback: true

**Tools:**
- callAgent:
    version: 1.0.0
    used_for: AI validation when heuristics are inconclusive
    shared_with: [Step 3, Step 4, Step 5, Step 6, Step 7, Step 8, Step 9, Step 11]

- validateHeuristics:
    version: 1.0.0
    used_for: Apply Brad Frost's design heuristics
    shared_with: [Step 7c only]

- validateAxioms:
    version: 1.0.0
    used_for: Validate against Atomic Design axioms
    shared_with: [Step 7c only]

**Scripts:**
- clones/brad_frost/validate-atomic-design.js:
    description: Atomic Design validation with heuristics + axioms
    language: javascript
    version: 1.0.0

**Performance:**
- duration_expected: 1500ms
- cost_estimated: $0.001  # Mostly heuristics, minimal AI
- cacheable: false
- parallelizable: false
- skippable_when: [skip_validation=true]

**Error Handling:**
- strategy: abort
- fallback: N/A (validation must pass)
- retry:
    max_attempts: 1
    backoff: linear
    backoff_ms: 0
- abort_workflow: true
- notification: log + slack

**Metadata:**
- story: DECISION-03
- version: 1.0.0
- dependencies: [Step 7a, Step 7b]
- breaking_changes: []
- author: Brad Frost Clone
- created_at: 2025-11-13
- updated_at: 2025-11-13

Validation Checklist

Use this checklist to validate any AIOX Task:

Required Fields

task is defined and unique
responsável is defined
responsavel_type is one of: Agente, Worker, Humano, Clone
atomic_layer is defined (or explicitly marked N/A)
Entrada is defined (array, can be empty)
Saída is defined (array, can be empty)

Input/Output Quality

All inputs have: campo, tipo, origem, obrigatório
All outputs have: campo, tipo, destino, persistido
Types are well-defined (not just "object" or "any")
Sources/destinations reference valid steps

Checklist Quality

Pre-conditions validate inputs
Post-conditions validate outputs
Acceptance criteria link to Stories
Blocking conditions are appropriate
Validation logic is executable

Templates & Tools

Template referenced (if applicable)
Tools cataloged (if applicable)
Scripts listed (if applicable)
All references are valid paths

Performance & Error Handling

Duration expected is realistic
Cost estimated (for AI)
Cacheability considered
Parallelization opportunities identified
Error handling strategy defined
Retry logic appropriate

Metadata

Story linked (if applicable)
Version defined
Dependencies listed
Breaking changes documented

Migration Guide (v2.0 → v3.0)

Step 1: Add Missing Required Fields

# BEFORE (v2.0 - incomplete)
#### Step 3: Analyze Brief

task: analyzeBrief()
responsável: Ad Strategist

**Entrada:**
**Saída:**

# AFTER (v3.0 - complete)
#### Step 3: Analyze Brief

task: analyzeBrief()
responsável: Ad Strategist
responsavel_type: Agente  # ← ADDED
atomic_layer: Strategy    # ← ADDED

**Entrada:**
- campo: brief_text
  tipo: string
  origem: User Input (config)
  obrigatório: true

**Saída:**
- campo: adAnalysis
  tipo: object { ... }
  destino: state (ad-spec.json)
  persistido: true

Step 2: Structure Checklists

# BEFORE (v2.0 - inline validations)
**Validações:**
- ✅ brief_text has minimum 50 characters
- ✅ adAnalysis contains required fields

# AFTER (v3.0 - structured checklist)
**Checklist:**
  pre-conditions:
    - [ ] brief_text has minimum 50 characters
      tipo: pre-condition
      blocker: true
      validação: "expect(brief_text.length).toBeGreaterThanOrEqual(50)"
  
  post-conditions:
    - [ ] adAnalysis contains all required fields
      tipo: post-condition
      blocker: true
      validação: |
        expect(adAnalysis.goal).toBeTruthy();
        expect(adAnalysis.urgencyLevel).toMatch(/high|medium|low/);

Step 3: Add Performance Metrics

# BEFORE (v2.0 - no metrics)
(no performance section)

# AFTER (v3.0 - with metrics)
**Performance:**
- duration_expected: 4000ms
- cost_estimated: $0.0025
- cacheable: false
- parallelizable: false
- skippable_when: [ready_copy=true]

Step 4: Add Error Handling

# BEFORE (v2.0 - implicit)
(no error handling section)

# AFTER (v3.0 - explicit)
**Error Handling:**
- strategy: fallback
- fallback: Use default analysis
- retry:
    max_attempts: 3
    backoff: exponential
    backoff_ms: 1000
- abort_workflow: false
- notification: log

Version History

Version	Date	Author	Changes
1.0.0	2025-11-13	Brad Frost Clone	Initial specification

END OF TASK FORMAT SPECIFICATION

Related Documents:

EXECUTOR-DECISION-TREE.md - How to choose executor type
TEMPLATE-SYSTEM-GUIDE.md - Template design patterns
TOOLS-AND-SCRIPTS-CATALOG.md - Available tools reference

FilesExpand file tree

TASK-FORMAT-SPECIFICATION-V1.md

Latest commit

History

TASK-FORMAT-SPECIFICATION-V1.md

File metadata and controls

AIOX Task Format Specification V1.0

Purpose

Task Format Overview

Field Definitions

Required Fields

1. task

2. responsável

3. responsavel_type

4. atomic_layer

5. Entrada (Inputs)

6. Saída (Outputs)

Optional Fields

7. Checklist

8. Template

9. Tools

10. Scripts

11. Performance

12. Error Handling

13. Metadata

Type System

Basic Types

Complex Types

Optional Types

Custom Types (Reference Schemas)

Validation Rules

Required Field Validation

Input/Output Validation

Examples by Executor Type

Agente (AI-Powered)

Worker (Script-Based)

Humano (Manual Review)

Clone (Mind Emulation)

Validation Checklist

Required Fields

Input/Output Quality

Checklist Quality

Templates & Tools

Performance & Error Handling

Metadata

Migration Guide (v2.0 → v3.0)

Step 1: Add Missing Required Fields

Step 2: Structure Checklists

Step 3: Add Performance Metrics

Step 4: Add Error Handling

Version History

1. `task`

2. `responsável`

3. `responsavel_type`

4. `atomic_layer`

5. `Entrada` (Inputs)

6. `Saída` (Outputs)

7. `Checklist`

8. `Template`

9. `Tools`

10. `Scripts`

11. `Performance`

12. `Error Handling`

13. `Metadata`