Feature Delivery — Fluxo de Entrega com Time de Agentes

O que é

Um pipeline de entrega de features onde uma equipe de agentes de IA trabalha como um time de desenvolvimento real — planejamento, execução paralela, QA independente e review — orquestrada por um coordenador e supervisionada por você.

O princípio central: cada papel é um estágio com contrato de entrada/saída, não uma persona. Nenhum agente "finge ser gerente" — cada um recebe uma tarefa escopada, contexto mínimo e um critério de aceite verificável.

O time

Fluxo fim a fim

 pedido ("implementa X")
        │
        ▼
 1. TRIAGE ────────── classifica o pedido, escolhe artefatos mínimos
        │
        ▼
 2. BRIEF ─────────── docs/features/<ID>.md + linha no índice
        │
        ▼
 3. ADR (se preciso) ─ só para decisão estrutural/difícil de reverter;
        │              correlaciona com ADRs anteriores, não re-decide
        ▼
 4. PLANO ─────────── docs/plans/<ID>-plan.md: tarefas, ownership,
        │              waves, launch spec, verificação por tarefa
        ▼
 5. DECISION GATE ─── decisão blocking? → PARA e pergunta ao PM
        │              senão → auto-aprova (aprovação única)
        ▼
 6. ISSUE SYNC ────── (opcional) espelha as tarefas do plano no tracker
        │              do time. Só com opt-in explícito e plano clean.
        │              Fluxo contínuo não para: vira sugestão no fim
        ▼
 7. EXECUTE ───────── loop por wave (detalhado abaixo)
        │
        ▼
 8. PÓS-EXECUÇÃO ──── bundle de review → checkpoint →
        │              verification-before-completion
        ▼
 9. DONE ──────────── status sincronizado: índice + brief + plano
        │
        ▼
10. EXTERNAL WAIT ─── (opcional) poll CI/deploy até green/red/timeout
                       host-agnóstico: gh --watch ou scheduler/loop

O loop de execução (o coração)

╔══════════════ PARA CADA WAVE ══════════════╗
║                                            ║
║  DEVs lançados em paralelo                 ║
║  (escopos de escrita disjuntos)            ║
║              │                             ║
║              ▼                             ║
║  Coordenador coleta os handoffs            ║
║  + audita mudanças em testes               ║
║              │                             ║
║              ▼                             ║
║  QA: 1 validator por entrega               ║
║  · postura padrão = REFUTADO               ║
║  · re-executa a verificação ele mesmo      ║
║  · diff × escopo permitido                 ║
║  · caça teste enfraquecido/omitido         ║
║       │              │                     ║
║   validated       refuted                  ║
║       │              │                     ║
║       │              ▼                     ║
║       │      retry do Dev com os           ║
║       │      findings (1x) → re-valida     ║
║       │      refutou de novo? → PARA       ║
║       ▼                                    ║
║  CI: verificação focada da wave             ║
║      suíte completa no fechamento           ║
║              │                             ║
║              ▼                             ║
║  Team Board impresso + log no plano        ║
║                                            ║
╚════════════════════════════════════════════╝

Por que o QA importa: antes, a wave avançava com a palavra do próprio Dev ("completed"). No teste de validação do pipeline, um Dev foi instruído a entregar um bug escondido atrás de um teste verde (comportamento quebrado sem assert que o cobrisse) e alegar 100%. O validator pegou: rodou probe direto no código, apontou a linha do bug, acusou que exatamente o comportamento quebrado era o único sem teste — e classificou a evidência do Dev como "placebo". Após o retry com os findings, a re-validação independente confirmou a correção.

Visibilidade: o Team Board

Em cada transição de estado (início de wave, veredito de QA, fechamento, bloqueio) o coordenador imprime:

FEAT-20260720-checkout — Wave 2/3 ▓▓▓▓▓▓░░░ 67%

Waves: [x]──[>]──[ ] · Bloqueios: 0 · Gate: validação da Task 2 Cost: economy · Model scope: workers Tokens: 108k wave · 216k feature

• Progresso é dado real — checkboxes das tarefas reportados nos handoffs, nunca estimativa.
• Tokens quando o host informa — soma real do custo de cada agente, por wave e acumulado; quando não houver telemetria, mostra unavailable.
• Cada board é copiado para o Wave Execution Log do plano — o arquivo guarda a linha do tempo.
• Na árvore do terminal, cada agente aparece nomeado: DEV A · slugify · wave 1, QA B · word_count · wave 1 · retry 1.

Custo e latência

• economy usa Workers em standard, Validators mecânicos em fast, Reviewers em standard e Verifiers shell (sem modelo) ou fast.

• balanced é o padrão quando o usuário não escolhe custo; quality é reservado para risco alto ou pedido explícito.

• Um modelo solicitado pelo usuário vale para Workers por padrão. Use Override scope: wave ou all somente quando essa abrangência for explícita.

• O Coordinator espera eventos. Não faz polling de list_agents nem imprime heartbeat.

• Workers recebem apenas o bloco da Task e a linha do launch spec. Prefira fork_turns: none.

• A revisão pós-execução pode ser um único bundle com seções de simplify, clean-comments, code-review-and-quality e test-guide quando acionado; separar agentes só quando houver gates ou escopos diferentes.

• Mutação e julgamento ficam separados: o Coordinator roda simplify/clean-comments; Reviewer é sempre read-only.

• Antes do Validator: status, diff rastreado, arquivos untracked, ownership e outputs de verificação formam um pacote congelado obrigatório.

• Falha final só é “preexistente” com evidência da suíte anterior; teste tocado pela feature é responsabilidade da feature até prova contrária.

Protocolo wire v1

No OMP, chamadas do tool task são capturadas automaticamente. Cada spawn gera um spawn.request; o ciclo de vida do subagente gera eventos agent.lifecycle para started, completed, failed ou aborted. O gate também bloqueia a chamada quando o limite de dois subagentes ativos ou de retry é excedido.

workflow_event continua disponível para checkpoints, evidências, handoffs, veredictos e bloqueios que exigem julgamento do Coordinator. Um subagente concluído automaticamente não é tratado como validado: a validação ainda precisa de evidência e de uma verificação aprovada.

workflow_lookup consulta o cache por objetivo e escopo. Um cache hit devolve referências de evidência; o consumidor ainda lê o arquivo quando precisar. Um arquivo, variável de ambiente, runtime, configuração ou dependência divergente torna o resultado um cache miss.

Os eventos são persistidos na sessão. O status workflow-efficiency mostra tokens quando o host fornece uso real, além de tools, launches, retries, veredictos, cache hits/misses e eventos automáticos.

Inspeção interativa da sessão

No OMP interativo, use /workflow para abrir um modal centralizado do TUI da sessão atual:

• 1: timeline de mensagens, entradas de sessão e eventos de workflow;
• 2: agents agrupados por workstream, com status e quantidade de eventos;
• Tab: alterna entre as visões;
• j/k ou setas: navega;
• [/] ou PageUp/PageDown: rola o detalhe selecionado;
• r: atualiza a leitura;
• q/Esc: fecha.

O viewer reutiliza a branch da sessão e os eventos persistidos pelo plugin. Quando o host fornece sessionFile para um lifecycle de agent, ele carrega o transcript completo da sessão filha em modo somente leitura e o anexa ao detalhe do agent. Se o arquivo não existir ou estiver fora da pasta de artifacts da sessão, mostra os eventos disponíveis sem tentar acessar o caminho.

Evidências carregam o SHA-256 do arquivo inteiro. O consumidor recalcula o hash antes de reutilizar a referência, inclusive para arquivos novos ou alterados sem commit. Verificações também carregam comando, ambiente, runtime e arquivos de configuração/dependência relevantes.

JSON/NDJSON é a fonte canônica. Binário e base64 não são usados no prompt: agentes precisam ler e produzir o contrato sem uma camada opaca adicional.

Gate de orquestração

Plano sem Parallelization, Wave Schedule e Subagent Launch Spec é sequencial: nenhuma skill externa de orquestração pode adicionar Scouts, Planners, Readers ou Reviewers. O teto é um Worker limitado e um Validator para diff substantivo; trabalho pequeno fica inline.

Orquestração só passa com duas ou mais frentes independentes, ownership sem sobreposição, contratos compartilhados definidos e waves registradas. O limite padrão é dois subagentes ativos; cada agente adicional precisa de justificativa de latência ou evidência de risco independente no plano.

Readers, Scouts, Verifiers e Validators mecânicos ficam em tier fast. Tier high exige risco consequencial explícito — migration, segurança ou contrato público — na linha de lançamento daquele papel.

Presets de workflow

Integração com contrato já publicado

Para um único consumidor de API/evento com contrato já verificado, use o preset fast-contract: snapshot curto do contrato, um Worker, um Validator, testes focados e um build final. Ele não cria PRD, ADR, plano, waves ou sync de tracker sem necessidade. A revisão ampla fica por pedido ou risco não coberto pelo Validator; comentários e testes só disparam suas passadas quando o diff os toca. Auth, migration, contrato novo, persistência, shell/design system ou ownership compartilhado promovem o trabalho para standard ou full.

Aprovação única

O fluxo só interrompe você em 3 situações:

1. Decisão blocking — persistência, contratos públicos, migração, auth, ownership;
2. Plano que não fecha limpo no self-check de validação;
3. QA refutou o mesmo workstream duas vezes (retry esgotado).

Economia de tokens

Cada subagente custa ~30k+ tokens só de spin-up. As alavancas são menos lançamentos e prompts menores — nunca checagem mais fraca:

• Prompt do agente = só o bloco da tarefa + linha do launch spec. Nunca o plano inteiro.
• Documentos grandes são lidos por agentes Reader que devolvem digest compacto.
• fork_turns: none é o padrão para não copiar o histórico inteiro para cada agente.
• QA em modelo rápido quando o check é mecânico; padrão quando julga cobertura/semântica.
• Trabalho pequeno fica inline com o coordenador — sem par Dev+QA para meia dúzia de edits.
• Um validator por entrega, nunca por step; validated é final, sem re-validar por segurança.
• Trabalho inline trivial usa verificação local; diff substantivo recebe um único Validator, mesmo sem Worker.

Garantias do desenho

1. Ninguém se auto-avalia. Quem implementa não valida; quem valida não confia em output colado — re-executa.
2. Escopo de escrita é contrato. Arquivo fora do escopo permitido = entrega refutada, sem discussão.
3. Evidência ou não aconteceu. Status done só com verificação re-executada e registrada.
4. Paralelismo sem conflito. Waves agrupam tarefas independentes; escopos disjuntos; merge em ordem de dependência.
5. O humano decide o que é do humano. Decisões estruturais param o fluxo; o resto flui.