FlexGodX/ciclo-de-desenvolvimento-autonomo-agenciado

Ciclo de Desenvolvimento Autônomo Agenciado (Pipeline com Quality Gates)

Este skill formaliza o fluxo de trabalho de engenharia em 5 fases e o pipeline de arbitragem multi-agente, desenvolvido e verificado durante a criação autônoma da Quest Nova (Flutter + Go + PostgreSQL 16 + Drift/SQLite).

Ele garante alta fidelidade arquitetural, zero perda de dados, segurança estrita (Zero-Trust/IDOR) e sincronização distribuída matematicamente verificada, sem intervenção humana entre as fases.

[!NOTE] Engenharia Reversa Excluída: A fase de engenharia reversa foi omitida/desabilitada. O pipeline começa diretamente com a Definição de Objetivos e a criação da Especificação Funcional (ou aceita um briefing de produto existente como entrada).

---

1. Princípios Centrais da Arquitetura

1. Autonomia Sem Interrupção: O orquestrador avança por todas as fases autonomamente. A confirmação é derivada estritamente de auditorias rigorosas dos Quality Gates, em vez de perguntar ao usuário.
2. Verificação Independente com Contexto Limpo: Revisores e juízes são gerados como subagentes dedicados com contexto limpo (recebem apenas o artefato alvo verificável, as especificações de referência e os critérios de avaliação explícitos — livres de raciocínio prévio do chat).
3. Barreira de Aprovação Unânime: A transição para a próxima fase é bloqueada até que todos os auditores/juízes concedam um veredito explícito APPROVED. Listas de defeitos (CHANGES_REQUESTED) acionam um loop imediato de correção e re-auditoria.
4. Roteamento de Modelo de Fallback: Quando os modelos de raciocínio primário encontram limites de taxa (ex.: esgotamento de cota HTTP 429), o pipeline roteia tarefas perfeitamente para modelos de alta disponibilidade (ex.: Gemini 3.8 Flash) preservando estritamente os papéis dos agentes e os limites de contexto limpo.

---

2. O Pipeline de 5 Fases

flowchart TD
    P1["Fase 1: Formulação do Objetivo e Especificação Funcional"] --> QG1{"Quality Gate 1: Auditoria de Especificação"}
    QG1 -->|"CHANGES_REQUESTED"| P1Fix["Resolução de Defeitos na Especificação"]
    P1Fix --> QG1
    QG1 -->|"APPROVED (Unânime)"| P2["Fase 2: Design de Sistema e Arquitetura"]
    P2 --> QG2{"Quality Gate 2: Tribunal de 3 Agentes"}
    QG2 -->|"CHANGES_REQUESTED"| P2Fix["Refinamento da Arquitetura"]
    P2Fix --> QG2
    QG2 -->|"APPROVED (Unânime)"| P3["Fase 3: Artefato de QA e Plano de Implementação"]
    P3 --> QG3{"Quality Gate 3: Revisão Cruzada de Rastreabilidade"}
    QG3 -->|"CHANGES_REQUESTED"| P3Fix["Alinhamento do Plano e QA"]
    P3Fix --> QG3
    QG3 -->|"APPROVED (Unânime)"| P4["Fase 4: Implementação (Backend + Cliente)"]
    P4 --> P5["Fase 5: Verificação Completa, Testes de Estresse e Lançamento"]

---

3. Convenção de Nomenclatura de Artefatos

Cada artefato produzido pelo pipeline é um arquivo versionado. Nunca sobrescreva um artefato no lugar — crie a próxima versão.

<ARTEFATO-NOME>-<data>-<NN>.md

• <ARTEFATO-NOME> — Nome UPPER_SNAKE do artefato: GOAL, SPECIFICATION, DESIGN, QA_ARTIFACT, IMPLEMENTATION_PLAN, RELEASE_NOTES.
• <data> — data de criação no formato ISO YYYY-MM-DD.
• <NN> — número de sequência de dois dígitos (01, 02, …) que desambigua artefatos com o mesmo nome criados dentro de um dia. Comece em 01 no primeiro artefato de um determinado dia e incremente a cada revisão subsequente desse mesmo artefato naquele dia. O contador é por nome de artefato, portanto, artefatos diferentes criados no mesmo dia podem compartilhar o mesmo número (ex.: GOAL-2026-11-10-01.md e DESIGN-2026-11-10-01.md). Em um novo dia, o contador começa novamente em 01.

Exemplo:

Artefato	Primeiro artefato do dia	Segundo artefato do mesmo dia
Objetivo	docs/GOAL-2026-11-10-01.md	docs/GOAL-2026-11-10-02.md
Especificação	docs/SPECIFICATION-2026-11-10-01.md	docs/SPECIFICATION-2026-11-10-02.md
Design	docs/DESIGN-2026-11-10-01.md	docs/DESIGN-2026-11-10-02.md

Regras:

1. As entregas das fases e todas as referências cruzadas (prompts de Quality Gates, planos, notas de lançamento) devem citar o nome de arquivo versionado exato, nunca um nome não versionado como docs/GOAL.md.
2. O <NN> mais alto para um nome de artefato é a versão autoritativa atual; versões anteriores permanecem intocadas como trilha de auditoria.
3. Os Quality Gates auditam a versão específica que lhes foi entregue e registram esse nome de arquivo em seu veredito.

Ao longo deste skill, <data> e <NN> representam a data e o número de sequência descritos acima.

---

4. Guia de Execução Fase a Fase

Fase 1: Formulação do Objetivo e Especificação Funcional (Quality Gate 1)

• Objetivo: Formular limites explícitos do sistema, loops de usuário, modelos de domínio e especificações técnicas com base diretamente nos requisitos/briefing.
• Entregas:
  • docs/GOAL-<data>-<NN>.md: Escopo global do sistema, invariantes centrais, Definição de Pronto (DoD).
  • docs/SPECIFICATION-<data>-<NN>.md: Esquemas de entidades, mecânicas temporais, protocolo de sincronização, versionamento OCC, regras de merge de 3 vias, proteção IDOR, esquemas DDL.
• Quality Gate 1 (Auditor de Contexto Limpo):
  • Gerar subagente (typeName: "research").
  • Fornecer apenas docs/SPECIFICATION-<data>-<NN>.md e critérios (completude, segurança, integridade de dados, consistência).
  • Loop até APPROVED.

Fase 2: Design de Sistema e "Tribunal de Três Agentes" (Quality Gate 2)

• Objetivo: Arquitetar backend escalável e tolerante a falhas e cliente reativo.
• Entrega: docs/DESIGN-<data>-<NN>.md (documento de design do sistema: backend, cliente, segurança).
• Quality Gate 2 (O Tribunal de Três Agentes): Gerar 3 subagentes independentes com contexto limpo:
  1. Juiz 1 (Arquiteto de Backend e Sistema): Avalia esquema de BD, limites de transação, locks em nível de linha, ordenação topológica DAG, esquemas de partição e OCC.
  2. Juiz 2 (Arquiteto de Cliente e UI): Avalia BD Offline-First (Drift/SQLite), isolates em segundo plano, orçamento de frame (< 16,6 ms), coalescência de fila de mutações e máquinas de estado BLoC.
  3. Juiz 3 (Crítico de Segurança e Casos Extremos): Identifica condições de corrida, deadlocks de cold-start, loops de eco, repetição de token (RTR), roubo de sessão e vulnerabilidades IDOR.
  • Todos os 3 juízes devem retornar APPROVED antes de prosseguir.

Fase 3: Artefato de QA, Plano de Rastreabilidade e Quality Gate 3

• Objetivo: Garantir rastreabilidade bidirecional de 100% entre especificação, arquitetura e testes antes de escrever código.
• Entregas:
  • docs/QA_ARTIFACT-<data>-<NN>.md: Critérios de Aceitação Completos (AC-XX), cenários de Teste Unitário, Integração, Sincronização Distribuída (TC-SYNC-XX) e Testes de Estresse (STRESS-XX).
  • docs/IMPLEMENTATION_PLAN-<data>-<NN>.md: Divisão de tarefas em etapas mapeadas diretamente para os casos de QA.
• Quality Gate 3 (Auditor Cruzado):
  • Verificar se cada critério de aceitação e caso extremo em docs/QA_ARTIFACT-<data>-<NN>.md mapeia diretamente para uma etapa de implementação em docs/IMPLEMENTATION_PLAN-<data>-<NN>.md.
  • Loop até APPROVED.

Fase 4: Implementação e Verificação de Testes

1. Migrações de Banco de Dados: Aplicar todas as migrações DDL com índices compostos e particionamento.
2. Motor Backend:
   • Clean Architecture: domain/, repository/, usecase/, delivery/http/.
   • Execução de testes unitários e de integração: cd backend && go test -v ./....
3. Motor Cliente:
   • Utilitários temporais centrais (PlainDate, FloatingTime, SparseSortOrder).
   • Motor de Merge Diferencial de 3 Vias (5 cenários de checklist, notas de zero perda de dados).
   • Coalescência de mutação in-loco e tratamento de condições de corrida em voo (MutationQueueManager).
   • Arquitetura BLoC e UI Adaptativa (Desktop 3 painéis + Navegação Mobile).
   • Execução de testes do cliente: cd client && flutter test.
   • Verificação do linter: cd client && flutter analyze (0 problemas).

Fase 5: Testes de Estresse, Lançamento e Entrega

1. Verificação de Sincronização Distribuída: Executar concorrência multi-dispositivo, conflitos OCC, supressão de Eco e reconciliação de Bootstrap HTTP 410.
2. Testes de Estresse:
   • Saturação do Pool de Conexões do Banco de Dados (STRESS-01): workers concorrentes com 0 vazamentos de pool.
   • Benchmark de Orçamento de Frame da UI (STRESS-02): 1000 tarefas processadas em < 16,6 ms (60/120 FPS estáveis).
3. Compilação de Artefatos:
   • Construir binário nativo do backend: go build -o bin/<serviço> cmd/<serviço>/main.go.
   • Construir bundle do cliente: flutter build bundle / flutter build macos / flutter build web.
4. Notas de Lançamento: Gerar docs/RELEASE_NOTES-<data>-<NN>.md documentando métricas verificadas, checklist DoD e instruções de execução.

---

5. Modelos de Prompt para Auditores e Juízes

Para modelos de prompt usados ao invocar subagentes de contexto limpo para os Quality Gates 1, 2 e 3, consulte references/auditor_prompts.md.