Executar Workflow de Tasks

Restrições Inegociáveis

• O agente principal não implementa código. Sua única responsabilidade é orquestrar: ler o tasks.md, escolher a próxima task pendente, despachar sub-agente, consolidar memória e decidir gates. Toda mudança de código é responsabilidade exclusiva do sub-agente que executa a skill executar-task.
• Gate humano obrigatório antes de tasks alta ou critica. Antes de despachar uma task com essas complexidades, o orquestrador deve pedir aprovação explícita via AskUserQuestion. Tasks baixa e media rodam sem gate.
• Fail-fast. Se qualquer task falhar (build quebrado, teste vermelho, task-review retornando severidade crítico ou major, dependências não satisfeitas ou exception não tratada do sub-agente), o orquestrador para imediatamente, registra a falha em workflow-memory.md e devolve para o humano. Não tenta retry, não tenta autocorreção.
• Reentrada baseada em status. A próxima task a executar é sempre a primeira X.0 com status ⬜ Pendente no tasks.md cujas dependências já estejam ✅. Nunca confie em variáveis em memória entre execuções da skill.
• Memória é fato, não narrativa. workflow-memory.md registra apenas fatos descobertos durante a execução (paths reais criados/modificados, novos códigos de EnumErro, nome de migration, classes novas, nomes de filas/exchanges, IDs gerados). Sem resumos de implementação, sem decisões já presentes na Tech Spec, sem repetição do conteúdo da task.
• Não altere a estrutura do template em assets/workflow-memory-template.md.

Procedimentos

Passo 1: Identificar Diretório do Workflow (Obrigatório)

1. Determine o tipo e nome do documento-fonte a partir do input do usuário (prd-[nome], investigacao-[nome] ou spike-[nome]).
2. Confirme via Bash (ls ./docs/tasks/[tipo]-[nome]/) que existem:
   • tasks.md
   • ao menos um [num]_task.md
3. Se algo faltar, interrompa e instrua o usuário a executar criar-tasks antes.
4. Se o usuário informou apenas um nome, liste ./docs/tasks/ via Bash e confirme via AskUserQuestion quando houver ambiguidade.

Passo 2: Carregar Estado Atual (Obrigatório)

1. Leia o tasks.md completo via Read.
2. Extraia a tabela Lista de Tarefas (ID, Título, Tipo, Complexidade, Dependências, Status).
3. Se já existir ./docs/tasks/[tipo]-[nome]/workflow-memory.md, leia-o por completo.
4. Se não existir, crie-o copiando assets/workflow-memory-template.md e preenchendo o cabeçalho (documento-fonte, data de início).

Passo 3: Selecionar Próxima Task (Obrigatório)

1. Identifique a primeira tarefa principal X.0 com status ⬜ Pendente.
2. Verifique se todas as dependências dela estão com status ✅ Concluída.
   • Se houver dependência pendente, pare e reporte ao usuário qual task está bloqueada e por quê.
3. Se não há mais tarefas ⬜, vá direto para o Passo 8 (encerramento).
4. Leia o arquivo [X]_task.md correspondente via Read para conhecer a complexidade declarada e a presença de bloco de rollback.

Passo 4: Gate Humano por Complexidade (Obrigatório quando aplicável)

1. Se a complexidade da task for alta ou critica:
   • Apresente ao usuário, via AskUserQuestion, um resumo curto (ID, título, complexidade, dependências, principais arquivos a modificar) e pergunte se autoriza a execução agora.
   • Não prossiga sem aprovação explícita. Se o usuário recusar ou pedir ajustes, pare e devolva o controle.
2. Se a complexidade for baixa ou media, não abra gate — apenas notifique em uma linha que está iniciando a task.

Passo 5: Despachar Sub-Agente (Obrigatório)

1. Invoque a ferramenta Agent com:
   • subagent_type: claude.
   • description: Executar task [X.0] [tipo]-[nome].
   • prompt: instrução autocontida contendo:
     • O comando exato a executar: invoque a skill executar-task com argumentos [num] [tipo]-[nome].
     • O caminho do [X]_task.md, tasks.md, documento-fonte e techspec.md.
     • O conteúdo integral do workflow-memory.md atual, com instrução explícita de consultá-lo para paths e identificadores já descobertos antes de criar arquivos ou códigos novos.
     • Instrução de retorno estruturada: ao final, o sub-agente deve devolver um bloco ## Resultado com:
       • status: success ou failure.
       • motivo: (em caso de falha — build quebrado, teste vermelho, severidade do task-review, etc.).
       • fatos-descobertos: lista bruta de pares chave: valor (paths criados/modificados, enums novos com código, nome do arquivo de migration, classes novas, filas/exchanges criadas, IDs gerados). Sem prosa, sem resumos.
2. Aguarde o retorno do sub-agente. Não inicie outra tool call em paralelo.

Passo 6: Processar Retorno do Sub-Agente (Obrigatório)

1. Se status: failure:
   • Adicione uma entrada em workflow-memory.md na seção ## Falhas contendo: ID da task, data/hora, motivo verbatim devolvido pelo sub-agente.
   • Pare o workflow. Reporte ao usuário em até 5 linhas: ID/título da task, motivo, próximos passos sugeridos (ex.: corrigir e reexecutar a skill).
   • Não marque a task como concluída.
   • Encerre a skill.
2. Se status: success:
   • Confirme via Read no tasks.md que a task aparece com status ✅ (o sub-agente já é responsável por marcá-la). Se não estiver, marque você mesmo via Edit.
   • Anexe os fatos-descobertos em workflow-memory.md, respeitando a seção apropriada (ver template). Não copie texto livre — apenas pares chave/valor.
   • Atualize o contador de tasks concluídas no cabeçalho do workflow-memory.md.

Passo 7: Loop

1. Volte ao Passo 3 para selecionar a próxima task pendente.
2. Não execute mais de uma task em paralelo. O workflow é estritamente sequencial.

Passo 8: Encerramento (Obrigatório)

1. Quando não houver mais tasks ⬜:
   • Atualize o workflow-memory.md com a data de conclusão.
   • Reporte ao usuário, em até 5 linhas: total de tasks concluídas, quantas exigiram gate, caminho do workflow-memory.md e sugestão de rodar executar-review antes do PR.
2. Não anexe o conteúdo do workflow-memory.md na resposta — apenas o caminho.

Helpers Bundled

• assets/workflow-memory-template.md — read-only. Estrutura canônica do workflow-memory.md (cabeçalho + seções de fatos por categoria + falhas). Replicar sem alterar a ordem das seções.
• references/quality-checklist.md — read-only. Auditoria leve aplicada antes do encerramento do workflow (Passo 8).

Tratamento de Erros

• tasks.md ausente: interrompa e instrua o usuário a executar criar-tasks.
• [X]_task.md referenciado no tasks.md mas inexistente em disco: marque a task como bloqueada na memória e pare; não invente o arquivo.
• Dependência da próxima task está em estado inválido (🟡 Em andamento ou similar): pare e peça intervenção humana. Nunca force progressão.
• Sub-agente devolveu resposta sem o bloco ## Resultado estruturado: trate como failure com motivo retorno não-estruturado e pare.
• workflow-memory.md já existe e está corrompido (sem seções esperadas): confirme com o usuário se deve sobrescrever a partir do template ou abortar.
• Usuário recusou o gate de uma task alta/critica: pare e devolva o controle; não tente burlar a recusa rebaixando a complexidade.
• Mais de uma task ⬜ elegível ao mesmo tempo: sempre processe primeiro a de menor ID X.0. Empate é resolvido por ordem de aparição no tasks.md.