bracelabs/agent-skills - agmsg-team

Desenvolvimento de equipe selecionada por modelo (agmsg)

Use este skill para formar uma equipe de pares com escopo de tarefa. Não há comandante permanente nem grupo de trabalhadores residente: o Dono da Tarefa é o modelo que você selecionou para esta sessão (no Claude Code ou Codex). Ele é responsável pela tarefa do início ao fim, e então inicia apenas os papéis necessários para o trabalho delimitado via agmsg.

Requer o skill agmsg (https://github.com/fujibee/agmsg) instalado, e tanto as CLIs claude quanto codex disponíveis — uma equipe agmsg cria pares em ambos. Leia o skill agmsg instalado antes de chamar seus scripts. Use apenas seus scripts Bash fornecidos; nunca acesse seu banco de dados, arquivos de equipe ou configuração diretamente.

Iniciar ou retomar uma equipe

Resolva a equipe antes de realizar o trabalho da tarefa. Use o nome da CLI da sessão atual (claude-code ou codex onde <cli> aparecer abaixo.

1. Se a invocação especificar um nome de equipe, use exatamente esse nome. Se estiver ausente localmente, crie/ingresse com join.sh; se existir, inspecione sua lista com team.sh e trabalhe nela. Não crie um homônimo local quando a solicitação for para puxar uma equipe remota — siga o fluxo de pull remoto do agmsg.
2. Sem um nome explícito, execute whoami.sh "$(pwd)" <cli> e team-list.sh --scope project "$(pwd)". Retome a única equipe associada a este projeto. Se não houver nenhuma, crie uma equipe local com nome baseado em um slug seguro em minúsculas do nome do diretório do projeto (por exemplo, payments-api). Se mais de uma se aplicar, pergunte ao usuário qual equipe existente usar; nunca escolha arbitrariamente.
3. Registre o Dono da Tarefa com join.sh <team> <agent> <cli> "$(pwd)" quando necessário. Escolha uma identidade não utilizada, como <team>-owner (opcionalmente qualificada pelo modelo, ex: <team>-sol-owner); inspecione team.sh <team> primeiro e adicione um número em caso de colisão. Lembre-se da equipe e identidade do agente resolvidos para esta tarefa.
4. Verifique a caixa de entrada do dono no início de cada turno retomado e antes de declarar a conclusão: inbox.sh <team> <owner>.

A primeira invocação, portanto, cria a equipe de projeto padrão quando nenhuma equipe de projeto utilizável existe; uma equipe fornecida explicitamente sempre vence. Equipes e identidades de agentes são estado local do agmsg, portanto não assuma que são compartilhadas entre máquinas a menos que a sincronização remota tenha sido configurada.

Roteamento de modelos

O Dono da Tarefa (DT) controla a seleção e escalação de modelos. Os trabalhadores retornam seus resultados ou solicitações de escalação ao DT; eles nunca reatribuem ou passam trabalho diretamente. Limites de provedor não importam porque o contexto da tarefa e os resultados podem se mover através do agmsg.

Use o modelo mais barato que pode completar a tarefa de forma confiável. O papel define responsabilidade; o modelo define a capacidade de raciocínio necessária para a tarefa atual. Não escolha um modelo caro apenas porque um papel é nomeado Consultor ou Especialista.

• Geral — Luna: implementação rotineira, edições mecânicas, refatoração direta, documentação simples e outro trabalho claro de execução pesada.
• Consultor — Terra ou Sonnet: planejamento, análise de requisitos/produto, revisões, design ou arquitetura diretos, depuração moderada e análise de trade-offs. Escolha pela adequação à tarefa, não por afinidade com o provedor.
• Especialista — Sol ou Opus: arquitetura ou UX complexa, depuração difícil e design de refatoração, revisão profunda, raciocínio entre domínios e decisões com impacto substancial a jusante. Nenhum é o padrão obrigatório para o papel.
• Escalação — Astra: raciocínio excepcionalmente difícil ou de alto risco, problemas sistêmicos não resolvidos ou revisão independente final após Sol ou Opus permanecerem insuficientes. Astra não é um modelo Especialista padrão.

A rota normal é Luna → Terra/Sonnet → Sol/Opus → Astra; o DT pode pular um nível quando a tarefa claramente justificar. Escalone com base em ambiguidade, profundidade de raciocínio necessária, tamanho do contexto, custo de falha, tentativas anteriores fracassadas ou confiança insuficiente — não apenas na importância da tarefa.

Quando um trabalhador acredita que seu modelo atribuído é insuficiente, ele relata o que está estabelecido, o que permanece não resolvido, por que a abordagem atual é insuficiente, se a escalação é recomendada e que raciocínio adicional é necessário. O DT decide então se deve tentar novamente, trocar dentro do nível, escalar ou solicitar uma opinião independente.

O usuário seleciona o modelo do Dono antes de invocar este skill; o skill não altera o modelo de uma sessão em execução. Se o modelo escolhido não estiver claro, pergunte ao usuário em vez de gerar um segundo Dono para decidir.

O Dono da Tarefa selecionado deve estabelecer requisitos e critérios de aceitação, inspecionar código e documentação relevantes, dividir apenas trabalho independente, implementar ou integrar o resultado, executar testes apropriados e verificar a conclusão. Luna é o modelo de trabalhador delegado padrão, a menos que as regras de roteamento justifiquem escalação.

Delegue pesquisa somente leitura, QA e revisão de segurança livremente quando forem independentes. Não permita que dois pares editem o mesmo arquivo simultaneamente; particione arquivos ou use worktrees Git separadas. Um Dono da Tarefa é responsável pelos resultados, não por pessoalmente executar cada etapa.

Use uma mensagem em formato de ticket. Envie apenas o contexto que o destinatário precisa e cite arquivos, commits, diffs ou descobertas anteriores em vez de fazer outro modelo redescobri-los. Leia modelos de mensagem ao delegar ou escalar.

Papéis e comunicação direta

• Dono da Tarefa (seu modelo selecionado): é dono do escopo, decisões, integração, testes e verificações finais.
• Engenheiro / Investigador: recebe um ticket de implementação ou pesquisa delimitado e reporta diretamente ao dono.
• Gerente de Produto / PdM: use quando o problema do produto ou os requisitos precisam de definição antes do design ou implementação. Esclareça o resultado do usuário, escopo, prioridade, regras de negócio e critérios de aceitação; não escolha estrutura de tela, copy de UI ou implementação, e traga decisões de produto não resolvidas ao dono.
• Designer de Produto: use quando os requisitos do produto precisam de uma especificação de tela/UX antes da implementação. Defina hierarquia de informação, fluxos, estados de caminho não feliz e copy de UI concisa e consistente em um nível prontamente utilizável pelo Engenheiro; não altere requisitos, regras de negócio, API/modelo de dados ou abordagem de implementação, e relate lacunas ou contradições de requisitos ao dono.
• Revisor de Acessibilidade: use para mudanças significativas de UI ou fluxo de usuário quando a revisão de acessibilidade for necessária. Verifique operação por teclado, foco, rótulos, feedback de erro e status, contraste e instruções que dependem apenas de cor; relate barreiras com evidências e uma remediação prática, e normalmente não edite código ou altere requisitos.
• QA: use para mudanças de comportamento, correções de bugs, mudanças em vários arquivos, risco de regressão, múltiplos critérios de aceitação ou pontos cegos significativos do dono. QA normalmente relata descobertas e não edita código.
• Revisor de Segurança: use apenas para auth/authz, sessões/cookies, APIs/entrada externa, uploads, segredos, DB/RLS, infraestrutura, atualizações de dependências ou dados sensíveis. Relate gravidade, evidências e remediação; normalmente não edite código.
• Consultor: dá um julgamento focado apenas. O dono fornece Problema, Estado atual, Opções, Trade-offs, Recomendação, Arquivos relevantes e uma Pergunta exata. Não envie para reinvestigar todo o repositório.
• Especialista: lida com um problema difícil e estreitamente definido após o roteamento por dificuldade, incerteza, custo de falha e tentativas anteriores. Não selecione um modelo apenas baseado no título deste papel.

Cada trabalhador retorna seu resultado ao DT. Os trabalhadores podem se comunicar diretamente quando necessário, mas não devem reatribuir trabalho ou escolher o próximo papel/modelo; o DT permanece como a autoridade de roteamento e alinhamento.

Escalação e geração (spawn)

Mantenha o Dono selecionado durante toda a tarefa. Escalone apenas em um ponto de decisão ou falha concreto; registre a resposta de volta para esse Dono, que toma a decisão de implementação e conclusão.

Ciclo de vida sob demanda e reutilização de contexto

Trate todo papel não-dono como um trabalhador sob demanda: spawn-o para um ticket delimitado, aguarde seu relatório, incorpore o resultado, então despawn-o. Não mantenha processos ociosos de QA, segurança, consultor ou engenheiro entre itens de trabalho.

spawn.sh <type> <name> --project "$(pwd)" [--team <team>] [--model <cli-model-id>] [--boot-prompt "<ticket>"] [--no-wait] [--fresh] pré-ingressa <name>, abre um painel tmux (dentro do tmux) ou um novo terminal, e inicia o CLI. Um spawn claude-code bloqueia até que seu watcher anexe; um spawn codex retorna imediatamente, então um par codex deve receber sua tarefa via --boot-prompt, não por uma mensagem enviada após estar ocioso.

Para trazer um papel de volta mais tarde na mesma tarefa, spawn o mesmo nome novamente sem --fresh — o agmsg retoma sua sessão gravada, então envie apenas o delta (status, arquivos/commit relevantes, uma próxima pergunta). Use --fresh apenas quando o contexto anterior puder enganar.

despawn.sh <team> <owner> <name> [--force] é o inverso de spawn e apenas derruba um papel que este dono criou. Um despawn normal de um par codex frequentemente relata "no live lock" (codex não tem watcher) — isso é normal; adicione --force apenas se uma janela de terminal for deixada aberta. Nunca despawn um par iniciado manualmente.

Interfaces do agmsg

Resolva o diretório scripts/ do skill agmsg de onde ele estiver instalado no ambiente atual (seu diretório de skill) em vez de assumir um caminho fixo, depois chame:

bash <agmsg-skill-dir>/scripts/send.sh <team> <from> <to> "<structured ticket>"
bash <agmsg-skill-dir>/scripts/inbox.sh <team> <agent>
bash <agmsg-skill-dir>/scripts/team.sh <team>
bash <agmsg-skill-dir>/scripts/spawn.sh <codex|claude-code> <agent> --project "$(pwd)" --team <team> --model <installed-cli-model-id> --boot-prompt "<bounded ticket>"
bash <agmsg-skill-dir>/scripts/despawn.sh <team> <owner> <spawned-agent> [--force]

--model é passado pelo agmsg para o CLI instalado. Use apenas IDs de modelo local verificados — para pares Codex gpt-5.6-luna, gpt-5.6-terra, gpt-5.6-sol, gpt-6-astra; para outro CLI, use seu identificador documentado em vez de inventar um. Um par Codex sem entrega por monitor deve receber sua tarefa inicial através de --boot-prompt, não por uma mensagem enviada após estar ocioso.

Crie (spawn) apenas quando gerar trabalho paralelo útil. Prefira um trabalhador de escopo estreito a vários trabalhadores especulativos; paralelize apenas tickets independentes. Para um par iniciado manualmente, send.sh é suficiente. Inspecione a lista antes de atribuir; todo from e to deve estar registrado a menos que esteja intencionalmente usando a exceção --force documentada do agmsg.

Portão de conclusão

O Dono da Tarefa selecionado fecha a tarefa somente após os requisitos e critérios de aceitação serem atendidos, os testes relevantes passarem, as revisões de QA e segurança acionadas forem resolvidas, nenhum bloqueador permanecer e o diff não conter alterações não relacionadas. Se uma recomendação de modelo caro foi usada, valide e implemente seu resultado antes do fechamento.