# AIOX Autonomous Development Engine (ADE) - Guia Completo

> **Versão:** 1.0.0
> **Data:** 2026-01-29
> **Status:** Production Ready ✅

---

## O que é o ADE?

O **AIOX Autonomous Development Engine (ADE)** é um sistema de desenvolvimento autônomo que transforma requisitos vagos em código funcional através de pipelines estruturados e agentes especializados.

### Características Principais

- **Spec Pipeline** - Transforma ideias em especificações executáveis
- **Execution Engine** - Executa subtasks com self-critique obrigatório
- **Recovery System** - Recupera de falhas automaticamente
- **QA Evolution** - Review estruturado em 10 fases
- **Memory Layer** - Aprende e documenta padrões

---

## Arquitetura

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           ADE Architecture                                   │
│                                                                              │
│  User Request ──► Spec Pipeline ──► Execution Engine ──► Working Code       │
│                                            │                                 │
│                                            ▼                                 │
│                                    Recovery System                           │
│                                            │                                 │
│                                            ▼                                 │
│                                    QA Evolution                              │
│                                            │                                 │
│                                            ▼                                 │
│                                    Memory Layer                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Os 7 Epics

### Epic 1: Worktree Manager

**Propósito:** Isolamento de branches via Git worktrees

**Comandos (@devops):**

- `*create-worktree {story}` - Criar worktree isolado
- `*list-worktrees` - Listar worktrees ativos
- `*merge-worktree {story}` - Fazer merge do worktree
- `*cleanup-worktrees` - Remover worktrees antigos

**Documentação:** [ADE-EPIC1-HANDOFF.md](../architecture/ADE-EPIC1-HANDOFF.md)

---

### Epic 2: Migration V2→V3

**Propósito:** Migração para formato autoClaude V3

**Comandos (@devops):**

- `*inventory-assets` - Inventário de assets V2
- `*analyze-paths` - Analisar dependências
- `*migrate-agent` - Migrar agente individual
- `*migrate-batch` - Migrar todos em batch

**Documentação:** [ADE-EPIC2-HANDOFF.md](../architecture/ADE-EPIC2-HANDOFF.md)

---

### Epic 3: Spec Pipeline

**Propósito:** Transformar requisitos em specs executáveis

**Fluxo:**

```
User Request → Gather → Assess → Research → Write → Critique → Spec Ready
```

**Comandos por Agente:**

| Agent      | Command                | Fase                   |
| ---------- | ---------------------- | ---------------------- |
| @pm        | `*gather-requirements` | Coletar requisitos     |
| @architect | `*assess-complexity`   | Avaliar complexidade   |
| @analyst   | `*research-deps`       | Pesquisar dependências |
| @pm        | `*write-spec`          | Escrever spec          |
| @qa        | `*critique-spec`       | Criticar e aprovar     |

**Documentação:** [ADE-EPIC3-HANDOFF.md](../architecture/ADE-EPIC3-HANDOFF.md)

---

### Epic 4: Execution Engine

**Propósito:** Executar specs em código funcional

**13 Steps do Coder:**

1. Load Context
2. Read Implementation Plan
3. Understand Current Subtask
4. Plan Approach
5. Write Code
   - 5.5 SELF-CRITIQUE (obrigatório)
6. Run Tests
   - 6.5 SELF-CRITIQUE (obrigatório)
7. Fix Issues
8. Run Linter
9. Fix Lint Issues
10. Verify Manually
11. Update Plan Status
12. Commit Changes
13. Signal Completion

**Comandos (@architect):**

- `*create-plan` - Criar plano de implementação
- `*create-context` - Gerar contexto do projeto

**Comandos (@dev):**

- `*execute-subtask` - Executar subtask

**Documentação:** [ADE-EPIC4-HANDOFF.md](../architecture/ADE-EPIC4-HANDOFF.md)

---

### Epic 5: Recovery System

**Propósito:** Recuperar de falhas em subtasks

**Fluxo:**

```
Subtask Fails → Track Attempt → Retry (<3) → Stuck Detection → Rollback → Escalate
```

**Comandos (@dev):**

- `*track-attempt` - Registrar tentativa
- `*rollback` - Voltar para estado anterior

**Documentação:** [ADE-EPIC5-HANDOFF.md](../architecture/ADE-EPIC5-HANDOFF.md)

---

### Epic 6: QA Evolution

**Propósito:** Review estruturado em 10 fases

**10 Fases:**

1. Setup & Context Loading
2. Code Quality Analysis
3. Test Coverage Review
4. Security Scan
5. Performance Check
6. Documentation Audit
7. Accessibility Review
8. Integration Points Check
9. Edge Cases & Error Handling
10. Final Summary & Decision

**Comandos (@qa):**

- `*review-build {story}` - Review completo
- `*request-fix {issue}` - Solicitar correção
- `*verify-fix {issue}` - Verificar correção

**Comandos (@dev):**

- `*apply-qa-fix` - Aplicar correção do QA

**Documentação:** [ADE-EPIC6-HANDOFF.md](../architecture/ADE-EPIC6-HANDOFF.md)

---

### Epic 7: Memory Layer

**Propósito:** Memória persistente de padrões e insights

**Tipos de Memória:**

- **Insights** - Descobertas durante desenvolvimento
- **Patterns** - Padrões de código extraídos
- **Gotchas** - Armadilhas conhecidas
- **Decisions** - Decisões arquiteturais

**Comandos (@dev):**

- `*capture-insights` - Capturar insights da sessão
- `*list-gotchas` - Listar gotchas conhecidas

**Comandos (@architect):**

- `*map-codebase` - Gerar mapa do codebase

**Comandos (@analyst):**

- `*extract-patterns` - Extrair padrões do código

**Documentação:** [ADE-EPIC7-HANDOFF.md](../architecture/ADE-EPIC7-HANDOFF.md)

---

## Quick Start

### 1. Criar Spec a partir de Requisito

```bash
# Ativar PM e coletar requisitos
@pm *gather-requirements

# Avaliar complexidade
@architect *assess-complexity

# Pesquisar dependências
@analyst *research-deps

# Escrever spec
@pm *write-spec

# Criticar e aprovar
@qa *critique-spec
```

### 2. Executar Spec Aprovada

```bash
# Criar plano de implementação
@architect *create-plan

# Criar contexto do projeto
@architect *create-context

# Executar subtasks (loop)
@dev *execute-subtask 1.1
@dev *execute-subtask 1.2
...
```

### 3. QA Review

```bash
# Review estruturado
@qa *review-build STORY-42

# Se há issues:
@qa *request-fix "Missing error handling"
@dev *apply-qa-fix
@qa *verify-fix
```

### 4. Capturar Aprendizado

```bash
# Capturar insights da sessão
@dev *capture-insights

# Documentar gotchas
@dev *list-gotchas
```

---

## Estrutura de Arquivos

```
.aiox-core/
├── development/
│   ├── agents/              # Definições de agentes V3
│   ├── tasks/               # Tasks executáveis
│   │   ├── spec-*.md        # Spec Pipeline tasks
│   │   ├── plan-*.md        # Execution Engine tasks
│   │   ├── qa-*.md          # QA Evolution tasks
│   │   └── capture-*.md     # Memory Layer tasks
│   └── workflows/
│       ├── spec-pipeline.yaml
│       ├── qa-loop.yaml
│       └── auto-worktree.yaml
│
├── infrastructure/
│   ├── scripts/
│   │   ├── worktree-manager.js     # Epic 1
│   │   ├── asset-inventory.js      # Epic 2
│   │   ├── migrate-agent.js        # Epic 2
│   │   ├── subtask-verifier.js     # Epic 4
│   │   ├── plan-tracker.js         # Epic 4
│   │   ├── recovery-tracker.js     # Epic 5
│   │   ├── rollback-manager.js     # Epic 5
│   │   ├── qa-loop-orchestrator.js # Epic 6
│   │   ├── codebase-mapper.js      # Epic 7
│   │   └── pattern-extractor.js    # Epic 7
│   └── schemas/
│       ├── agent-v3-schema.json
│       └── task-v3-schema.json
│
└── product/
    ├── templates/
    │   ├── spec-tmpl.md
    │   └── qa-report-tmpl.yaml
    └── checklists/
        └── self-critique-checklist.md
```

---

## autoClaude V3 Format

### Agent Definition

```yaml
autoClaude:
  version: '3.0'
  migratedAt: '2026-01-29T02:24:10.724Z'

  specPipeline:
    canGather: boolean # @pm
    canAssess: boolean # @architect
    canResearch: boolean # @analyst
    canWrite: boolean # @pm
    canCritique: boolean # @qa

  execution:
    canCreatePlan: boolean # @architect
    canCreateContext: boolean # @architect
    canExecute: boolean # @dev
    canVerify: boolean # @dev

  recovery:
    canTrackAttempts: boolean # @dev
    canRollback: boolean # @dev

  qa:
    canReview: boolean # @qa
    canRequestFix: boolean # @qa

  memory:
    canCaptureInsights: boolean # @dev
    canExtractPatterns: boolean # @analyst
    canDocumentGotchas: boolean # @dev
```

### Task Definition

```yaml
autoClaude:
  version: '3.0'
  pipelinePhase: spec-gather|spec-assess|exec-plan|exec-subtask|etc
  deterministic: boolean
  elicit: boolean
  composable: boolean

  verification:
    type: none|command|manual
    command: 'npm test'

  selfCritique:
    required: boolean
    checklistRef: 'self-critique-checklist.md'
```

---

## QA Gates

Cada Epic tem um QA Gate que deve passar antes de prosseguir:

```bash
@qa *gate epic-{N}-{name}
```

**Decisões:**

- **PASS** - Próximo epic liberado
- **CONCERNS** - Aprovado com follow-ups
- **FAIL** - Retorna para correções
- **WAIVED** - Bypass autorizado por @po

---

## Troubleshooting

### Subtask Falha Repetidamente

```bash
# Verificar histórico de tentativas
@dev *track-attempt --status

# Rollback para último estado bom
@dev *rollback --hard

# Tentar abordagem diferente
@dev *execute-subtask 2.1 --approach alternative
```

### Spec não Aprovada

```bash
# Ver feedback do critique
cat docs/stories/STORY-42/spec-critique.json

# Refinar spec
@pm *write-spec --iterate

# Re-submeter para critique
@qa *critique-spec
```

### Worktree Conflita

```bash
# Listar worktrees
@devops *list-worktrees

# Resolver conflitos
@devops *merge-worktree STORY-42 --resolve

# Cleanup
@devops *cleanup-worktrees
```

---

## Related Documentation

- [ADE Architect Handoff](../architecture/ADE-ARCHITECT-HANDOFF.md) - Overview geral
- [ADE Agent Changes](../architecture/ADE-AGENT-CHANGES.md) - Alterações em todos os agentes com matriz de capabilities
- [Epic 1 - Worktree Manager](../architecture/ADE-EPIC1-HANDOFF.md)
- [Epic 2 - Migration V2→V3](../architecture/ADE-EPIC2-HANDOFF.md)
- [Epic 3 - Spec Pipeline](../architecture/ADE-EPIC3-HANDOFF.md)
- [Epic 4 - Execution Engine](../architecture/ADE-EPIC4-HANDOFF.md)
- [Epic 5 - Recovery System](../architecture/ADE-EPIC5-HANDOFF.md)
- [Epic 6 - QA Evolution](../architecture/ADE-EPIC6-HANDOFF.md)
- [Epic 7 - Memory Layer](../architecture/ADE-EPIC7-HANDOFF.md)

---

_AIOX Autonomous Development Engine - Turning Ideas into Code Autonomously_