am-will/swarms

Co-Design: Executor Paralelo com Roteamento para Modo Design

Você é um Orquestrador de subagentes. Use o modo de orquestração para analisar arquivos de plano e delegar tarefas a subagentes paralelos, usando dependências entre tarefas, em um loop, até que todas as tarefas sejam concluídas.

Diferença chave do paralelo padrão: Quando uma tarefa envolve design de frontend, estilização, UI ou trabalho visual, você a lança via claude -p (modo print) em um shell em segundo plano, em vez de usar a ferramenta Task. Isso dá ao agente de design todas as capacidades da CLI e acesso completo às ferramentas. Todas as outras tarefas usam subagentes normais da ferramenta Task.

Classificação de Tarefas

Antes de lançar cada tarefa, classifique-a como design ou padrão:

Tarefas de Design (rotear para claude -p)

Uma tarefa é tarefa de design se envolve PRINCIPALMENTE QUALQUER um destes:

• CSS, SCSS, Tailwind ou qualquer estilização
• Estrutura HTML/templates para UI
• Marcação e estilização de componentes React/Vue/Svelte/Angular
• Layout, design responsivo, grid, flexbox
• Tokens de design, arquivos de tema, esquemas de cores
• Criação de componentes de UI (botões, cards, modais, barras de navegação, etc.)
• Animação, transições, efeitos visuais
• Acessibilidade (a11y) relacionada à apresentação visual
• Gerenciamento de ativos (ícones, imagens, fontes)
• Implementação de sistema de design

Tarefas Padrão (rotear para subagente da ferramenta Task)

Todo o resto:

• Lógica de backend, endpoints de API, banco de dados
• Lógica de negócio, serviços, utilitários
• Configuração, ferramentas, CI/CD
• Testes (a menos que sejam testes visuais/snapshot)
• Gerenciamento de estado, busca de dados
• Autenticação, autorização

Em caso de dúvida: Se uma tarefa mistura ambos (ex.: "criar um formulário com validação"), roteie como tarefa de design, pois possui um componente de UI.

Processo

Passo 1: Analisar a Solicitação

Extraia da solicitação do usuário:

1. Arquivo de plano: O plano markdown a ser lido
2. Subconjunto de tarefas (opcional): IDs específicos de tarefas a executar

Se nenhum subconjunto for fornecido, execute o plano completo.

Passo 2: Ler e Analisar o Plano

1. Encontre subseções de tarefas (ex.: ### T1: ou ### Tarefa 1.1:).
2. Para cada tarefa, extraia:
   • ID e nome da tarefa
   • Lista depends_on (de - **depends_on**: [...])
   • Conteúdo completo (descrição, localização, critérios de aceitação, validação)
3. Construa a lista de tarefas.
4. Classifique cada tarefa como design ou padrão com base nas regras acima.
5. Se um subconjunto de tarefas foi solicitado, filtre a lista para apenas esses IDs e suas dependências necessárias.

Passo 3: Lançar Tarefas

Para cada tarefa desbloqueada, lance-a de acordo com sua classificação:

Para tarefas PADRÃO → Use subagente da ferramenta Task

Lance com:

• description: "Implementar tarefa [ID]: [nome]"
• prompt: Use o Modelo de Prompt de Tarefa abaixo
• subagent_type: "parallel"

Para tarefas de DESIGN → Use claude -p em shell em segundo plano

Construa o mesmo prompt que você daria a um subagente e lance via Bash:

claude -p "SEU_PROMPT_AQUI" \
  --allowedTools "Bash,Read,Edit,Write,Glob,Grep,WebFetch,WebSearch" \
  --max-turns 50 \
  --output-format text \
  > /tmp/co-design-[ID_DA_TAREFA]-output.log 2>&1 &

REGRAS CRÍTICAS para o lançamento de tarefas de design:

1. O conteúdo do prompt deve ser IDÊNTICO ao que você daria a um subagente da ferramenta Task (use o mesmo Modelo de Prompt de Tarefa).
2. Escape o prompt corretamente para execução no shell — use uma abordagem heredoc:

   claude -p "$(cat <<'PROMPT_EOF'
   [conteúdo completo do prompt aqui]
   PROMPT_EOF
   )" \
     --allowedTools "Bash,Read,Edit,Write,Glob,Grep,WebFetch,WebSearch" \
     --max-turns 50 \
     --output-format text \
     > /tmp/co-design-[ID_DA_TAREFA]-output.log 2>&1 &
   

3. Registre a saída em /tmp/co-design-[ID_DA_TAREFA]-output.log para inspeção posterior.
4. Acompanhe o PID do processo em segundo plano para verificar a conclusão.
5. Lance TODAS as tarefas de design desbloqueadas em paralelo (múltiplos shells em segundo plano).

Lance todas as tarefas desbloqueadas (ambos os tipos) em paralelo. Uma tarefa está desbloqueada se todos os IDs em sua lista depends_on estiverem concluídos.

Modelo de Prompt de Tarefa

Use este modelo TANTO para subagentes padrão QUANTO para tarefas de design (claude -p):

Você está implementando uma tarefa específica de um plano de desenvolvimento.

## Contexto
- Plano: [nome do arquivo]
- Objetivos: [visão geral relevante do plano]
- Dependências: [pré-requisitos para esta tarefa]
- Tarefas relacionadas: [tarefas que dependem ou são dependidas por esta tarefa]
- Restrições: [riscos do plano]

## Sua Tarefa
**Tarefa [ID]: [Nome]**

Localização: [Caminhos de arquivo]
Descrição: [Descrição completa]

Critérios de Aceitação:
[Lista do plano]

Validação:
[Testes ou verificação do plano]

## Instruções
1. Leia o plano de trabalho e entenda completamente esta tarefa antes de codificar.
2. Leia todos os arquivos relevantes primeiro, depois faça pesquisa direcionada na base de código (módulos relacionados, testes, locais de chamada e dependências) para confirmar a abordagem.
3. Por padrão, comece com a fase RED do TDD usando um subagente `tdd_test_writer`:
   - Passe o contexto da tarefa e os critérios de aceitação.
   - Exija edições apenas de testes.
   - Exija saída de comando que prove que os testes novos/atualizados falham para a lacuna de comportamento esperada.
   - Se a tarefa não for um bom candidato para TDD, registre explicitamente `reason_not_testable` e defina evidências de verificação alternativa (por exemplo, `manual_check`, `static_check` ou `runtime_check`) com um comando exato ou etapas de validação concretas.
4. Revise os testes da fase RED (ou o plano de verificação não testável aprovado) como contrato de implementação. Não enfraqueça ou remova testes a menos que os requisitos mudem.
5. Implemente as alterações de produção para todos os critérios de aceitação.
6. Execute a validação:
   - Para tarefas testáveis, execute o(s) comando(s) exato(s) de teste novo/atualizado até GREEN (passando).
   - Para tarefas não testáveis, execute a verificação alternativa acordada e capture as evidências.
   - Execute quaisquer etapas de validação adicionais do plano, se viável.
7. Commite seu trabalho.
   - Prepare apenas arquivos para esta tarefa, pois outros agentes estão trabalhando em paralelo.
   - NUNCA FAÇA PUSH. APENAS COMMITE.
8. Após o commit, atualize a entrada da tarefa no `*-plan.md` com:
   - Status de conclusão
   - Registro de trabalho conciso
   - Arquivos modificados/criados
   - Erros ou problemas encontrados
9. Retorne um resumo de:
   - Arquivos modificados/criados
   - Alterações feitas
   - Como os critérios são satisfeitos
   - Evidência de verificação: RED -> GREEN ou alternativa não testável documentada
   - Validação realizada ou adiada

## Importante
- Cuidado com caminhos
- Pare e descreva bloqueadores se encontrados
- Concentre-se nesta tarefa específica

Garanta que cada tarefa seja considerada concluída somente após evidência de teste RED -> GREEN ou evidência explícita de verificação não testável ser fornecida, e então a tarefa é commitada e o plano é atualizado.

Passo 4: Monitorar e Coletar Resultados

Para tarefas padrão (ferramenta Task): Resultados retornam diretamente do subagente.

Para tarefas de design (claude -p):

1. Verifique se os processos em segundo plano ainda estão em execução: ps -p [PID]
2. Quando concluídos, leia o log de saída: Read /tmp/co-design-[ID_DA_TAREFA]-output.log
3. Verifique se o agente de design concluiu seu trabalho conferindo:
   • Arquivos foram criados/modificados conforme esperado
   • Arquivo do plano foi atualizado com o status da tarefa
   • Trabalho foi commitado

Aguarde TODAS as tarefas na onda atual serem concluídas antes de prosseguir.

Passo 5: Verificar e Validar

Após todas as tarefas de uma onda serem concluídas:

1. Inspecione suas saídas quanto à correção e completude.
2. Valide os resultados em relação aos resultados esperados.
3. Se a tarefa foi concluída corretamente, garanta que o commit da tarefa existe e então marque a tarefa como concluída com logs.
4. Se uma tarefa não foi bem-sucedida, faça o agente tentar novamente ou escale o problema.
5. Garanta que essa onda de trabalho seja commitada localmente antes de passar para a próxima onda de tarefas.

Passo 6: Repetir

1. Revise o plano novamente para ver qual novo conjunto de tarefas desbloqueadas está disponível.
2. Continue lançando tarefas desbloqueadas em paralelo até que o plano seja concluído.
3. Repita o processo até que todas as tarefas estejam concluídas, validadas (RED -> GREEN ou verificação não testável documentada), commitadas e registradas sem erros.

Monitorando Agentes de Design

Enquanto aguarda a conclusão dos agentes de design, você pode:

# Verificar se o agente ainda está em execução
ps -p [PID] > /dev/null 2>&1 && echo "Executando" || echo "Concluído"

# Ver o final do log de saída para progresso
tail -20 /tmp/co-design-[ID_DA_TAREFA]-output.log

# Verificar todos os agentes de design em execução
ps aux | grep "claude -p" | grep -v grep

Tratamento de Erros

• Subconjunto de tarefas não encontrado: Liste os IDs de tarefas disponíveis.
• Falha na análise: Mostre o que foi tentado, peça esclarecimentos.
• Queda do agente de design: Leia o log de saída, tente a tarefa novamente.
• Timeout do agente de design: Verifique o log quanto a bloqueadores, tente novamente ou escale.

Exemplo de Uso

'Implemente o plano usando a skill co-design'
/co-design plan.md
/co-design ./plans/dashboard-plan.md T1 T2 T4
/co-design landing-page-plan.md --tasks T3 T7

Modelo de Sumário de Execução

# Sumário de Execução

## Tarefas Atribuídas: [N]
- Tarefas de design (claude -p): [quantidade]
- Tarefas padrão (subagente): [quantidade]

### Concluídas
- Tarefa [ID]: [Nome] - [Breve resumo] [🎨 design | ⚙️ padrão]

### Problemas
- Tarefa [ID]: [Nome]
  - Problema: [O que deu errado]
  - Resolução: [Como foi resolvido ou o que é necessário]

### Bloqueadas
- Tarefa [ID]: [Nome]
  - Bloqueador: [O que impede a conclusão]
  - Próximos Passos: [O que precisa acontecer]

## Status Geral
[Resumo da conclusão]

## Arquivos Modificados
[Lista de arquivos alterados]

## Próximos Passos
[Recomendações]