Desenvolvimento Orientado por Subagents

Execute plano despachando um subagent fresco por tarefa, com revisão em dois estágios após cada uma: revisão de conformidade com especificação primeiro, depois revisão de qualidade de código.

Princípio central: Um subagent fresco por tarefa + revisão em dois estágios (especificação depois qualidade) = alta qualidade, iteração rápida

Quando Usar

digraph when_to_use {
    "Tem plano de implementação?" [shape=diamond];
    "Tarefas são principalmente independentes?" [shape=diamond];
    "Ficar nesta sessão?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Execução manual ou brainstorm primeiro" [shape=box];

    "Tem plano de implementação?" -> "Tarefas são principalmente independentes?" [label="sim"];
    "Tem plano de implementação?" -> "Execução manual ou brainstorm primeiro" [label="não"];
    "Tarefas são principalmente independentes?" -> "Ficar nesta sessão?" [label="sim"];
    "Tarefas são principalmente independentes?" -> "Execução manual ou brainstorm primeiro" [label="não - acopladas"];
    "Ficar nesta sessão?" -> "subagent-driven-development" [label="sim"];
    "Ficar nesta sessão?" -> "executing-plans" [label="não - sessão paralela"];
}

vs. Executing Plans (sessão paralela):

• Mesma sessão (sem mudança de contexto)
• Um subagent fresco por tarefa (sem poluição de contexto)
• Revisão em dois estágios após cada tarefa: conformidade com especificação primeiro, depois qualidade de código
• Iteração mais rápida (sem humano no meio das tarefas)

O Processo

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Por Tarefa";
        "Despachar subagent implementador (./implementer-prompt.md)" [shape=box];
        "Subagent implementador faz perguntas?" [shape=diamond];
        "Responder perguntas, fornecer contexto" [shape=box];
        "Subagent implementador implementa, testa, faz commit, auto-revisa" [shape=box];
        "Despachar subagent revisor de especificação (./spec-reviewer-prompt.md)" [shape=box];
        "Subagent revisor confirma código atende especificação?" [shape=diamond];
        "Subagent implementador corrige gaps de especificação" [shape=box];
        "Despachar subagent revisor de qualidade de código (./code-quality-reviewer-prompt.md)" [shape=box];
        "Subagent revisor de qualidade aprova?" [shape=diamond];
        "Subagent implementador corrige problemas de qualidade" [shape=box];
        "Marcar tarefa como concluída em TodoWrite" [shape=box];
    }

    "Ler plano, extrair todas as tarefas com texto completo, anotar contexto, criar TodoWrite" [shape=box];
    "Mais tarefas restam?" [shape=diamond];
    "Despachar subagent revisor de código final para toda implementação" [shape=box];
    "Usar superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Ler plano, extrair todas as tarefas com texto completo, anotar contexto, criar TodoWrite" -> "Despachar subagent implementador (./implementer-prompt.md)";
    "Despachar subagent implementador (./implementer-prompt.md)" -> "Subagent implementador faz perguntas?";
    "Subagent implementador faz perguntas?" -> "Responder perguntas, fornecer contexto" [label="sim"];
    "Responder perguntas, fornecer contexto" -> "Despachar subagent implementador (./implementer-prompt.md)";
    "Subagent implementador faz perguntas?" -> "Subagent implementador implementa, testa, faz commit, auto-revisa" [label="não"];
    "Subagent implementador implementa, testa, faz commit, auto-revisa" -> "Despachar subagent revisor de especificação (./spec-reviewer-prompt.md)";
    "Despachar subagent revisor de especificação (./spec-reviewer-prompt.md)" -> "Subagent revisor confirma código atende especificação?";
    "Subagent revisor confirma código atende especificação?" -> "Subagent implementador corrige gaps de especificação" [label="não"];
    "Subagent implementador corrige gaps de especificação" -> "Despachar subagent revisor de especificação (./spec-reviewer-prompt.md)" [label="re-revisar"];
    "Subagent revisor confirma código atende especificação?" -> "Despachar subagent revisor de qualidade de código (./code-quality-reviewer-prompt.md)" [label="sim"];
    "Despachar subagent revisor de qualidade de código (./code-quality-reviewer-prompt.md)" -> "Subagent revisor de qualidade aprova?";
    "Subagent revisor de qualidade aprova?" -> "Subagent implementador corrige problemas de qualidade" [label="não"];
    "Subagent implementador corrige problemas de qualidade" -> "Despachar subagent revisor de qualidade de código (./code-quality-reviewer-prompt.md)" [label="re-revisar"];
    "Subagent revisor de qualidade aprova?" -> "Marcar tarefa como concluída em TodoWrite" [label="sim"];
    "Marcar tarefa como concluída em TodoWrite" -> "Mais tarefas restam?";
    "Mais tarefas restam?" -> "Despachar subagent implementador (./implementer-prompt.md)" [label="sim"];
    "Mais tarefas restam?" -> "Despachar subagent revisor de código final para toda implementação" [label="não"];
    "Despachar subagent revisor de código final para toda implementação" -> "Usar superpowers:finishing-a-development-branch";
}

Templates de Prompt

• ./implementer-prompt.md - Despachar subagent implementador
• ./spec-reviewer-prompt.md - Despachar subagent revisor de conformidade com especificação
• ./code-quality-reviewer-prompt.md - Despachar subagent revisor de qualidade de código

Exemplo de Workflow

Você: Estou usando Subagent-Driven Development para executar este plano.

[Ler arquivo de plano uma vez: docs/plans/feature-plan.md]
[Extrair todas as 5 tarefas com texto completo e contexto]
[Criar TodoWrite com todas as tarefas]

Tarefa 1: Script de instalação de hook

[Obter texto e contexto da Tarefa 1 (já extraído)]
[Despachar subagent de implementação com texto completo da tarefa + contexto]

Implementador: "Antes de começar - o hook deve ser instalado no nível de usuário ou sistema?"

Você: "Nível de usuário (~/.config/superpowers/hooks/)"

Implementador: "Entendi. Implementando agora..."
[Depois] Implementador:
  - Implementou comando install-hook
  - Adicionou testes, 5/5 passando
  - Auto-revisão: Percebi que faltava flag --force, adicionei
  - Fez commit

[Despachar revisor de conformidade com especificação]
Revisor de especificação: ✅ Atende especificação - todos os requisitos cumpridos, nada extra

[Obter SHAs do git, despachar revisor de qualidade de código]
Revisor de código: Pontos fortes: Boa cobertura de testes, limpo. Problemas: Nenhum. Aprovado.

[Marcar Tarefa 1 como concluída]

Tarefa 2: Modos de recuperação

[Obter texto e contexto da Tarefa 2 (já extraído)]
[Despachar subagent de implementação com texto completo da tarefa + contexto]

Implementador: [Sem perguntas, procede]
Implementador:
  - Adicionou modos verify/repair
  - 8/8 testes passando
  - Auto-revisão: Tudo bem
  - Fez commit

[Despachar revisor de conformidade com especificação]
Revisor de especificação: ❌ Problemas:
  - Faltando: Reporte de progresso (especificação diz "relatar a cada 100 itens")
  - Extra: Adicionou flag --json (não solicitado)

[Implementador corrige problemas]
Implementador: Removeu flag --json, adicionou reporte de progresso

[Revisor de especificação revisa novamente]
Revisor de especificação: ✅ Atende especificação agora

[Despachar revisor de qualidade de código]
Revisor de código: Pontos fortes: Sólido. Problemas (Importante): Número mágico (100)

[Implementador corrige]
Implementador: Extraiu constante PROGRESS_INTERVAL

[Revisor de código revisa novamente]
Revisor de código: ✅ Aprovado

[Marcar Tarefa 2 como concluída]

...

[Após todas as tarefas]
[Despachar revisor de código final]
Revisor final: Todos os requisitos cumpridos, pronto para merge

Pronto!

Vantagens

vs. Execução manual:

• Subagents seguem TDD naturalmente
• Contexto fresco por tarefa (sem confusão)
• Seguro para paralelismo (subagents não interferem)
• Subagent pode fazer perguntas (antes E durante o trabalho)

vs. Executing Plans:

• Mesma sessão (sem handoff)
• Progresso contínuo (sem espera)
• Checkpoints de revisão automáticos

Ganhos de eficiência:

• Sem overhead de leitura de arquivo (controlador fornece texto completo)
• Controlador cuida do contexto exato necessário
• Subagent obtém informação completa antecipadamente
• Perguntas surfam antes do trabalho começar (não depois)

Gates de qualidade:

• Auto-revisão encontra problemas antes do handoff
• Revisão em dois estágios: conformidade com especificação, depois qualidade de código
• Loops de revisão garantem que correções funcionam
• Conformidade com especificação previne over/under-building
• Qualidade de código garante que implementação é bem construída

Custo:

• Mais invocações de subagent (implementador + 2 revisores por tarefa)
• Controlador faz mais trabalho de preparação (extraindo todas as tarefas antecipadamente)
• Loops de revisão adicionam iterações
• Mas encontra problemas cedo (mais barato que debugar depois)

Red Flags

Nunca:

• Pular revisões (conformidade com especificação OU qualidade de código)
• Prosseguir com problemas não corrigidos
• Despachar múltiplos subagents de implementação em paralelo (conflitos)
• Fazer subagent ler arquivo de plano (fornecer texto completo em vez disso)
• Pular contexto de cena (subagent precisa entender onde tarefa se encaixa)
• Ignorar perguntas do subagent (responder antes de deixá-lo prosseguir)
• Aceitar "mais ou menos" em conformidade com especificação (revisor encontrou problemas = não concluído)
• Pular loops de revisão (revisor encontrou problemas = implementador corrige = revisar novamente)
• Deixar auto-revisão do implementador substituir revisão real (ambas são necessárias)
• Iniciar revisão de qualidade de código antes de conformidade com especificação estar ✅ (ordem errada)
• Passar para próxima tarefa enquanto qualquer revisão tiver problemas abertos

Se subagent fizer perguntas:

• Responder claramente e completamente
• Fornecer contexto adicional se necessário
• Não apressá-lo para implementação

Se revisor encontrar problemas:

• Implementador (mesmo subagent) corrige
• Revisor revisa novamente
• Repetir até aprovado
• Não pular a re-revisão

Se subagent falhar tarefa:

• Despachar subagent corrigidor com instruções específicas
• Não tentar corrigir manualmente (poluição de contexto)

Integração

Skills de workflow necessárias:

• superpowers:writing-plans - Cria o plano que este skill executa
• superpowers:requesting-code-review - Template de code review para subagents revisores
• superpowers:finishing-a-development-branch - Completar desenvolvimento após todas as tarefas

Subagents devem usar:

• superpowers:test-driven-development - Subagents seguem TDD para cada tarefa

Workflow alternativo:

• superpowers:executing-plans - Usar para sessão paralela em vez de execução na mesma sessão