🔧 Plano de Integração: AIOS-core → Forge¶

Status: 📋 Aguardando Aprovação
Autor: Werner (CTO)
Data: 2026-02-17
Versão: 1.0

📋 Sumário Executivo¶

Este documento apresenta uma análise completa do framework AIOS-core (Synkra) e um plano de integração das melhores funcionalidades no Forge (APEX Dev Platform).

Recomendação: Portar funcionalidades específicas de infraestrutura, NÃO integrar o sistema completo.

Ganho esperado: +50-70% de eficiência no desenvolvimento autônomo.

🔍 Análise do AIOS-core¶

Visão Geral¶

Métrica	Valor
Repositório	github.com/SynkraAI/aios-core
Versão	4.2.11
Arquivos	2.104
Tamanho	38 MB
Linhas JS	~30.000+
Testes	293 arquivos
Agentes	12 especializados
Maturidade	~2 anos de evolução

Arquitetura¶

AIOS-core/
├── .aios-core/
│   ├── core/                    # Núcleo do sistema
│   │   ├── memory/              # Sistemas de memória
│   │   ├── orchestration/       # Orquestração de agentes
│   │   └── synapse/             # Context engine
│   ├── development/
│   │   ├── agents/              # 12 agentes especializados
│   │   ├── tasks/               # Tasks executáveis
│   │   └── workflows/           # Workflows estruturados
│   ├── infrastructure/
│   │   └── scripts/             # 50+ scripts de infraestrutura
│   └── product/
│       ├── templates/           # Templates de documentos
│       └── checklists/          # Checklists de qualidade
├── bin/                         # CLI tools
├── packages/                    # Módulos npm
└── tests/                       # 293 arquivos de teste

✅ Funcionalidades para Integrar no Forge¶

1. Recovery Tracker (Prioridade: CRÍTICA)¶

Arquivo fonte: .aios-core/infrastructure/scripts/recovery-tracker.js
Linhas de código: 693

O que faz¶

Sistema de rastreamento de tentativas de implementação que permite:

Registrar cada tentativa de implementação de uma subtask
Auto-incrementar número de tentativas
Rastrear: timestamp, abordagem, sucesso/falha, erro
Retry automático até 3x com abordagens diferentes
Rollback para estado anterior quando necessário

Funcionalidades Detalhadas¶

// Estrutura de dados por subtask
{
  subtaskId: "2.1",
  storyId: "STORY-42",
  attempts: [
    {
      number: 1,
      timestamp: "2026-02-17T10:00:00Z",
      approach: "Usando zustand com middleware",
      changes: ["src/store/index.ts"],
      success: false,
      error: "Type error: Property persist does not exist",
      duration: "5m"
    },
    {
      number: 2,
      timestamp: "2026-02-17T10:10:00Z",
      approach: "Usando zustand/middleware import direto",
      changes: ["src/store/index.ts"],
      success: true,
      duration: "3m"
    }
  ],
  currentAttempt: 2,
  status: "completed"
}

API Disponível¶

Método	Descrição
`startAttempt(subtaskId, {approach, changes})`	Inicia nova tentativa
`completeAttempt(subtaskId, {success, error})`	Finaliza tentativa
`abandonAttempt(subtaskId, reason)`	Abandona tentativa
`getAttempts(subtaskId)`	Lista histórico
`getSummary()`	Estatísticas gerais
`rollback(subtaskId)`	Volta ao estado anterior

CLI Incluída¶

# Iniciar tentativa
node recovery-tracker.js start STORY-42 2.1 --approach "Nova abordagem"

# Completar com sucesso
node recovery-tracker.js complete STORY-42 2.1 --success

# Completar com falha
node recovery-tracker.js complete STORY-42 2.1 --fail --error "Mensagem de erro"

# Ver histórico
node recovery-tracker.js history STORY-42 2.1

# Ver resumo
node recovery-tracker.js summary STORY-42

Ganho Esperado¶

Problema Atual	Com Recovery	Melhoria
Agente falha = recomeça do zero	Retry automático 3x	-70% retrabalho
Sem histórico de tentativas	Log completo	Debug facilitado
Sem rollback	Volta ao estado bom	-80% perda de trabalho

2. Gotchas Memory (Prioridade: ALTA)¶

Arquivo fonte: .aios-core/core/memory/gotchas-memory.js
Linhas de código: 800+

O que faz¶

Sistema de memória persistente para "armadilhas" conhecidas:

Auto-capture: 3x mesmo erro = gotcha automático
Manual: Adicionar gotchas via comando
Context injection: Injeta gotchas relevantes antes de tasks
Persistência: JSON + Markdown

Categorias Suportadas¶

Categoria	Exemplos de Triggers
`build`	webpack, vite, babel, tsc, npm run build
`test`	jest, vitest, playwright, coverage
`lint`	eslint, prettier, stylelint
`runtime`	TypeError, ReferenceError, crash
`integration`	api, cors, database, supabase
`security`	xss, csrf, injection, auth

Níveis de Severidade¶

Nível	Quando Usar
`critical`	Bloqueia desenvolvimento
`warning`	Causa problemas frequentes
`info`	Bom saber, não crítico

Estrutura de Gotcha¶

{
  id: "gotcha-abc123",
  title: "Supabase pooler precisa porta 6543",
  description: "Conexão direta na 5432 falha em produção",
  category: "integration",
  severity: "critical",
  workaround: "Usar postgresql://...@db.xxx.supabase.co:6543/postgres",
  relatedFiles: ["prisma/schema.prisma", ".env.production"],
  trigger: {
    errorPattern: "Connection refused",
    files: ["prisma/*"]
  },
  source: {
    type: "auto_detected",  // ou "manual"
    occurrences: 5,
    firstSeen: "2026-02-10T10:00:00Z",
    lastSeen: "2026-02-17T09:00:00Z"
  },
  resolved: false
}

Context Injection¶

Antes de executar uma task, o sistema:

Analisa a descrição da task
Identifica arquivos envolvidos
Busca gotchas relevantes
Injeta no prompt do agente

## Known Gotchas (Review Before Proceeding)

### [CRITICAL] Supabase pooler precisa porta 6543
Conexão direta na 5432 falha em produção

**Workaround:** Usar postgresql://...@db.xxx.supabase.co:6543/postgres
**Related Files:** prisma/schema.prisma, .env.production

Ganho Esperado¶

Problema Atual	Com Gotchas Memory	Melhoria
Mesmo erro 5x	Detectado na 3ª vez	-50% erros repetidos
Conhecimento perdido	Persistente	Memória institucional
Sem contexto	Injection automático	Prevenção proativa

3. Worktree Manager (Prioridade: MÉDIA)¶

Arquivo fonte: .aios-core/infrastructure/scripts/worktree-manager.js
Linhas de código: 584

O que faz¶

Gerenciamento de Git worktrees para isolamento de desenvolvimento paralelo:

Cada story/task em worktree separado
Zero conflitos entre agentes paralelos
Merge automatizado com detecção de conflitos
Cleanup de worktrees antigos (>30 dias)

API Disponível¶

Método	Descrição
`create(storyId)`	Cria worktree isolado
`remove(storyId, {force})`	Remove worktree
`list()`	Lista worktrees ativos
`get(storyId)`	Info de worktree específico
`exists(storyId)`	Verifica se existe
`detectConflicts(storyId)`	Dry-run merge
`mergeToBase(storyId, options)`	Merge com opções
`cleanupStale()`	Remove worktrees >30 dias

Opções de Merge¶

{
  staged: false,    // Merge sem commit (--no-commit)
  squash: false,    // Squash commits (--squash)
  cleanup: false,   // Remove worktree após merge
  message: "..."    // Mensagem customizada
}

Estrutura¶

projeto/
├── .aios/
│   ├── worktrees/
│   │   ├── STORY-42/     # Worktree isolado
│   │   ├── STORY-43/     # Outro worktree
│   │   └── STORY-44/     # Mais um
│   └── logs/
│       └── merges/       # Audit logs de merges
└── (main repo)

Ganho Esperado¶

Problema Atual	Com Worktrees	Melhoria
2 agentes = conflito	Isolamento total	Zero conflitos
Merge manual	Automático com detecção	-80% tempo de merge
Sem audit	Logs de merge	Rastreabilidade

Quando Implementar

Worktrees só são necessários quando houver paralelismo real (múltiplos agentes trabalhando simultaneamente). Para SellSync atual, pode esperar.

4. Self-Critique (Prioridade: ALTA)¶

Origem: Workflow do agente @dev no AIOS

O que é¶

Steps obrigatórios de auto-revisão durante execução:

5.  Write Code
5.5 SELF-CRITIQUE (obrigatório!)
    └── "O código que escrevi atende os requisitos?"
    └── "Há edge cases não tratados?"
    └── "Naming está claro?"
    └── "Há duplicação?"

6.  Run Tests
6.5 SELF-CRITIQUE (obrigatório!)
    └── "Os testes cobrem casos importantes?"
    └── "Há testes de erro?"
    └── "Cobertura está adequada?"

Implementação no Forge¶

Adicionar aos prompts dos agentes:

## SELF-CRITIQUE OBRIGATÓRIO

Antes de finalizar, PARE e responda:

### Sobre o código:
- [ ] Atende 100% dos requisitos especificados?
- [ ] Trata todos os edge cases identificados?
- [ ] Naming está claro e consistente?
- [ ] Não há duplicação de código?
- [ ] Não há console.log/print de debug?

### Sobre os testes:
- [ ] Cobertura >80%?
- [ ] Testes de erro/exceção?
- [ ] Testes de edge cases?
- [ ] Mocks apropriados?

Se algum item falhou, CORRIJA antes de entregar.

Ganho Esperado¶

Problema Atual	Com Self-Critique	Melhoria
Bugs descobertos no PR	Pegos antes	-40% bugs
Código incompleto	Auto-verificação	-30% retrabalho
Padrões inconsistentes	Checklist obrigatório	+50% consistência

5. Spec Validation (Prioridade: BAIXA)¶

Origem: Spec Pipeline do AIOS (Epic 3)

O que é¶

Validação estruturada de requisitos antes de codar:

Request → Gather → Assess → Research → Write → Critique → Code

Versão Simplificada para Forge¶

Não precisa das 5 fases completas. Versão light:

# Antes de spawnar agente de dev
spec_check:
  - clear_requirements: "Requisitos estão claros?"
  - acceptance_criteria: "Critérios de aceite definidos?"
  - dependencies: "Dependências conhecidas?"
  - files_affected: "Arquivos afetados mapeados?"

Ganho Esperado¶

Problema Atual	Com Spec Validation	Melhoria
Requisito ambíguo	Clarificado antes	-30% retrabalho
Escopo indefinido	Delimitado	-20% scope creep

Quando Implementar

Spec validation completo é overkill para tarefas simples. Implementar apenas quando features ficarem complexas.

📊 Matriz de Priorização¶

Feature	Impacto	Esforço	ROI	Prioridade
Recovery Tracker	🔴 Alto	🟡 Médio	⭐⭐⭐⭐⭐	P1
Self-Critique	🔴 Alto	🟢 Baixo	⭐⭐⭐⭐⭐	P1
Gotchas Memory	🟡 Médio	🟡 Médio	⭐⭐⭐⭐	P2
Worktree Manager	🟡 Médio	🔴 Alto	⭐⭐⭐	P3
Spec Validation	🟢 Baixo	🟡 Médio	⭐⭐	P4

🗓️ Plano de Implementação¶

Fase 1: Quick Wins (Semana 1)¶

Dia 1-2: Self-Critique¶

Tarefas:

[ ] Atualizar prompt do dev-frontend.md
[ ] Atualizar prompt do dev-backend.md
[ ] Atualizar prompt do dev-fullstack.md
[ ] Atualizar prompt do qa-engineer.md
[ ] Testar com task real

Entregável: Agentes com self-critique obrigatório

Dia 3-5: Recovery Tracker¶

Tarefas:

[ ] Copiar recovery-tracker.js para /apex/core/dev-platform/scripts/
[ ] Adaptar paths para estrutura Forge
[ ] Criar wrapper para integração com Moltbot
[ ] Documentar uso
[ ] Testar com task real

Entregável: Sistema de recovery funcionando

Fase 2: Memory Layer (Semana 2)¶

Dia 1-3: Gotchas Memory¶

Tarefas:

[ ] Copiar gotchas-memory.js para /apex/core/dev-platform/scripts/
[ ] Adaptar para salvar em /apex/core/dev-platform/data/
[ ] Criar integração com spawn de agentes
[ ] Adicionar gotchas conhecidos iniciais
[ ] Testar context injection

Entregável: Sistema de memória de erros funcionando

Dia 4-5: Integração¶

Tarefas:

[ ] Integrar recovery + gotchas no workflow
[ ] Atualizar spawn-dev.md com novos steps
[ ] Atualizar squad-config.yaml
[ ] Documentar workflow completo
[ ] Teste E2E

Entregável: Forge 2.0 integrado

Fase 3: Isolation (Futuro)¶

Condição de Início

Só iniciar quando houver necessidade real de paralelismo.

Tarefas:

[ ] Avaliar necessidade real
[ ] Portar worktree-manager.js
[ ] Adaptar para estrutura Forge
[ ] Integrar com CI/CD
[ ] Documentar

📁 Estrutura Final do Forge 2.0¶

/apex/core/dev-platform/
├── orchestrator/
│   ├── squad-config.yaml      # (existente)
│   ├── spawn-dev.md           # (atualizado)
│   └── detect-dev-task.md     # (existente)
├── agents/
│   ├── dev-frontend.md        # (atualizado com self-critique)
│   ├── dev-backend.md         # (atualizado)
│   ├── dev-fullstack.md       # (atualizado)
│   └── qa-engineer.md         # (atualizado)
├── scripts/                   # 🆕 NOVO
│   ├── recovery-tracker.js    # Portado do AIOS
│   ├── gotchas-memory.js      # Portado do AIOS
│   └── forge-integration.js   # Wrapper Moltbot
├── data/                      # 🆕 NOVO
│   ├── gotchas.json           # Memória de erros
│   └── recovery/              # Histórico de tentativas
└── workflows/
    └── dev-orchestration.yaml # (atualizado)

✅ Checklist de Aprovação¶

Para aprovar este plano, confirme:

[ ] Concordo com a priorização (P1 → P4)
[ ] Concordo com o timeline (2 semanas)
[ ] Autorizo início da Fase 1
[ ] Quero acompanhamento diário de progresso

📞 Próximos Passos¶

Após aprovação:

Werner inicia implementação da Fase 1
Updates diários no grupo SELLSYNC - Diretoria
Review ao final de cada fase
Documentação atualizada no portal APEX

Benefício Final

Forge 2.0 = Velocidade atual + Robustez do AIOS

✅ Mantém integração APEX
✅ Mantém nossa stack específica
✅ Adiciona recovery automático
✅ Adiciona memória de erros
✅ Adiciona self-critique
✅ ~50-70% mais eficiente

Documento gerado por Werner (CTO) em 2026-02-17