Arasz/ai-badger

skill de orquestração de tarefas

Executa uma tarefa do backlog como uma unidade de trabalho separada e rastreada por token. Pensamento de alto impacto — o planejamento e o portão de qualidade final — é delegado a um modelo de raciocínio avançado; modelos de implementação fazem o trabalho prático; a sessão orquestradora integra e rastreia tudo para que uma sessão interrompida possa ser retomada.

Todas as especificidades do projeto vêm de .ai-badger/config.json — nunca codifique um comando de build, um nome de persona ou um repositório. Os dados de rastreamento ficam em .ai-badger/task-tracking/ (ignorados pelo git). Os scripts ficam em scripts/ desta skill.

Contrato de configuração (leia primeiro)

De .ai-badger/config.json:

• commands.build / commands.test / commands.lint — os comandos de verificação para a Fase 3.
• personaRouting — mapeia tipos de trabalho para as personas geradas; orienta a distribuição da Fase 2.
• sourceControl — plataforma + URLs de repositório/projeto; controla a extensão de controle de versão (fluxo de PR, ciclo de revisão, integração com issues/quadro). Se sourceControl.platform == "github" e uma repoUrl estiver presente, o fragmento extensions/github/ desta skill está ativo — siga-o para as etapas de PR/ciclo de revisão abaixo. Caso contrário, faça commit localmente e integre conforme sua plataforma.

Modelo e política de delegação

Gaste capacidade de raciocínio avançado em planos, decomposição e revisão — não em digitar implementações. A sessão orquestradora obtém esse raciocínio por delegação explícita, não assumindo seu próprio modelo.

• Delegue a um agente de raciocínio avançado (planejamento/decomposição na Fase 1; o portão final de correção + arquitetura na Fase 3). Prefixe a descrição dessas chamadas para manter o modelo visível rapidamente.
• Delegue a agentes de implementação adequados ao trabalho, usando as personas do personaRouting em config.json. TDD é obrigatório para código.
• Delegue trabalho mecânico trivial (atualizações de doc/comentários, refatorações rotineiras, preenchimento de testes) a um modelo barato.
• A sessão orquestradora faz diretamente: buscar a tarefa, ler docs, registrar uso de tokens, a verificação leve de conclusão por subagente, executar o build/teste configurado e pequenas correções cirúrgicas encontradas durante o portão de qualidade.

Os prompts dos subagentes devem ser autocontidos: escopo, critérios de aceitação, arquivos/docs para ler, regras de TDD + estilo de código do projeto (aponte-os para CLAUDE.md) e o que reportar de volta. Execute subagentes independentes em paralelo.

Artefato de exibição conhecido — não diagnostique erroneamente como um bug de distribuição: o painel do agente ao vivo mostra o campo model por tarefa (e qualquer linha de status personalizada que o leia) pode transitoriamente exibir um valor obsoleto — por exemplo, mostrando o modelo da sessão pai para um subagente que foi realmente distribuído com uma substituição de model diferente. Causa raiz: o campo do painel vem de um feed de status ao vivo assíncrono, um caminho de código separado do resolvedModel que o Claude Code escreve nos metadados do resultado da ferramenta do transcript da sessão na conclusão da chamada. O transcript é a verdade absoluta; o painel é um instantâneo que pode ficar desatualizado. Se houver dúvida sobre o modelo real de uma distribuição, pesquise no transcript .jsonl da sessão pelo Agent tool_use cuja description corresponda e verifique o tool_result correspondente toolUseResult.resolvedModel em vez de confiar no painel. Não perca tempo reinvestigando isso como um problema de código de distribuição, a menos que o próprio transcript mostre o resolvedModel errado.

Distribuição com consciência de cache: o prefixo de requisição de cada agente inclui o contexto sempre carregado do seu projeto (instruções equivalentes a CLAUDE.md/AGENTS.md, .ai-badger/state.json e quaisquer outros arquivos que seu projeto carrega em cada turno) — mantenha-os estáveis em bytes dentro de uma tarefa (nunca os reescreva no meio da tarefa; o protocolo de finalização escreve o estado entre tarefas) para que sirvam como leituras de cache por cerca de um décimo do custo, em vez de uma nova escrita. Os caches dos subagentes são inicializações a frio independentes com um TTL de ~5 minutos, então: prefira um subagente com múltiplos turnos a várias distribuições únicas para um cluster de etapas relacionadas (amortiza a inicialização a frio) e use /rewind em vez de /compact para retroceder dentro de uma tarefa (rewind reutiliza o prefixo em cache; compact paga por uma nova escrita de resumo). Compact apenas nos limites da tarefa (Fase 0). token-usage.json registra um cacheEfficiency da sessão principal (cache_read ÷ (cache_read + cache_creation)); uma proporção baixa significa que o prefixo está sendo alterado. A divisão de cache por subagente não está disponível — a notificação de conclusão expõe apenas total_tokens.

Se você não puder gerar subagentes (você está executando como um subagente, ou a ferramenta Agent está indisponível), faça o trabalho diretamente na sessão com o modelo disponível — o fluxo de trabalho de rastreamento e o protocolo de finalização ainda se aplicam, mas anote em seu resumo que o planejamento/revisão foi executado com rigor reduzido, pois a delegação de raciocínio avançado não foi possível.

Fase 0 — Higiene de contexto

1. python3 scripts/task_tracker.py status. Se uma tarefa anterior não foi concluída, finalize-a ou estacione-a.
2. Confirme que .ai-badger/state.json reflete a última tarefa concluída; repare se não.
3. Se esta sessão carregar um histórico pesado, diga ao usuário para /compact (ou começar do zero) e re-invocar /task <id> em um contexto limpo, e então pare — a menos que seja autônomo.

Fase 1 — Iniciar

1. Resolva a tarefa (uma URL de issue ou texto livre usado como escopo/título; verifique cruzadamente o quadro do projeto por meio da extensão de controle de versão, se ativa). Leia os docs referenciados.
2. Registre: python3 scripts/task_tracker.py start <taskId> --title "<título>" --branch task/<taskId>-<slug>.
3. Peça ao usuário para renomear a sessão para corresponder à tarefa (pule se autônomo).
4. Crie/mude para o branch da tarefa.
5. Planeje: delegue a decomposição a um agente de raciocínio avançado (a persona architect), fornecendo o corpo da tarefa e trechos de doc. Use seu plano para orientar a Fase 2.

Fase 2 — Executar

1. Distribua subagentes de implementação de acordo com personaRouting. Instrua cada subagente de código a escrever o teste com falha primeiro (TDD).
2. Registre o total_tokens de cada subagente na conclusão: python3 scripts/task_tracker.py subagent <taskId> <total_tokens> --description "<o que fez>".
3. Revise cada resultado nas junções (corresponde ao plano? critérios de aceitação?). Envie feedbacks em vez de reescrever, a menos que a correção seja de algumas linhas.
4. Faça commit e push por pacote de trabalho (commits pequenos). Se a extensão de controle de versão estiver ativa, abra um PR rascunho cedo, conforme extensions/github/.

Fase 3 — Portão de qualidade

Execute você mesmo os commands.build e commands.test configurados e capture a saída. Em seguida, delegue uma revisão a um agente de raciocínio avançado (a persona code-reviewer) com o diff, critérios de aceitação, docs de arquitetura relevantes e a saída de build/teste. Peça para julgar a correção da implementação (lógica, casos extremos, honestidade dos testes) e a arquitetura (pureza de camada, consistência com os docs). Corrija as descobertas (triviais você mesmo, substanciais por meio de um subagente), reexecute build/teste e prossiga.

Fase 4 — Protocolo de finalização

1. Se a extensão de controle de versão estiver ativa, siga extensions/github/ para PR pronto, o ciclo de rodadas de revisão e squash-merge. Caso contrário, integre conforme sua plataforma.
2. Atualize os arquivos de estado: adicione a entrada concisa da tarefa concluída no início de completedTasks em .ai-badger/state.json, atualize next/lastUpdated; escreva notas/decisões detalhadas no arquivo de notas do projeto.
3. Verificação de compactação no CLAUDE.md se o projeto mantiver um.
4. Feche o rastreamento: python3 scripts/task_tracker.py finish <taskId>.
5. Peça ao usuário para avaliar a skill de 0 a 5: python3 scripts/task_tracker.py grade <taskId> <0-5> (pule/deixe não definido se autônomo).
6. Reporte o custo de token da tarefa e recomende /compact ou uma nova sessão antes da próxima tarefa — este é o final padrão. Auto-continuação autorizada (caminho alternativo, apenas quando uma condição observável for válida: o modo autonômico/parceiro da skill auto-wm estiver ativo, ou o usuário na invocação original disse explicitamente para continuar para a próxima tarefa): após a Fase 5 ser concluída, compacte conforme a orientação da Fase 0, leia a próxima tarefa do campo next em .ai-badger/state.json (ou o próximo item não reivindicado em sua fonte de backlog configurada) e invoque esta skill novamente para essa tarefa. Se nenhuma condição for válida e nenhum usuário estiver disponível, inicie uma nova sessão e diga ao usuário para re-invocar a skill para que a próxima tarefa comece em um contexto limpo.

Fase 5 — Auditoria de lacunas de documentação

Após a integração, delegue um agente de auditoria de docs (isolado da árvore de trabalho) para verificar CLAUDE.md e os docs do projeto contra o código mesclado, corrigir pequenos desvios e relatar lacunas que precisam de uma decisão.

Recuperação

task_tracker.py registra o ID da sessão e o comando de retomada de cada tarefa; um cron de retomada monitora sessões paradas. Se você acordar em uma sessão retomada no meio de uma tarefa, execute python3 scripts/task_tracker.py reattach <taskId> primeiro e, em seguida, continue.

Extensões: o comportamento de PR/issue/ciclo de revisão do controle de versão é definido em extensions/<nome>/ e é incorporado pelo welcome-ai-badger apenas quando config.json fornece os dados necessários. A skill base acima permanece neutra em plataforma e stack.