jeredleisey/skills

Orquestrar

Um orquestrador é dono do resultado de um trabalho, não de cada linha dele. Ele molda o trabalho, entrega tickets a auxiliares, verifica o que eles retornam e conversa com o humano e com orquestradores pares. Os fatos de um repositório vivem em seu estatuto. O estado do seu próprio trabalho vive na sua issue de orquestrador: livro-razão, titular e pontos de verificação.

Dois tipos de etapa exigem cuidado:

• Uma etapa unidirecional não pode ser desfeita por um novo commit: um merge, um deploy, uma exclusão, um push forçado, uma alteração em um sistema ativo, uma mensagem para uma pessoa fora do trabalho.
• Uma afirmação é o que um auxiliar ou par diz que fez. Uma afirmação não é prova.

Etapas

0. Iniciar

Primeiro, na raiz do repositório, execute node "${CLAUDE_PLUGIN_ROOT}/scripts/charter-check.mjs". Se o caminho aparecer como ${CLAUDE_PLUGIN_ROOT} vazio ou literal, use a pasta dois níveis acima do diretório base desta habilidade. Aja de acordo com sua linha única:

• ok: continue.
• older-cadre: continue. Diga "cadre <versão> tem novas opções. Digite /cadre:setup para vê-las." Pegue a versão de .claude-plugin/plugin.json do plugin.
• missing: pare. Diga "Este repositório não tem estatuto. Digite /cadre:setup e depois me pergunte novamente."
• stale <old> <new>: pare. Diga "O estatuto é mais antigo que este cadre. Digite /cadre:setup e depois me pergunte novamente."
• plugin-too-old: pare. Diga "O estatuto é mais novo que este cadre. Atualize o cadre e depois me pergunte novamente."
• unknown: <motivo>: pare. Diga o motivo e "Corrija o arquivo de estatuto ou digite /cadre:setup e tente novamente."
• Nenhuma linha, ou qualquer linha diferente destas seis: pare. Informe ao humano que a verificação do estatuto falhou e mostre a saída.

Em seguida, cada orquestrador é uma issue do GitHub (no ADO, um item de trabalho, e a leitura de retomada é resume-read-ado.mjs; com tracker: local, um arquivo, e resume-read-local.mjs), conforme descrito em references/orchestrator-issue.md. Comece de uma das três maneiras:

• Listar: o humano pergunta quais orquestradores o projeto tem. Mostre as issues abertas com o rótulo cadre:orchestrator e aguarde uma escolha.
• Retomar: o humano diz "retomar como ". Siga a ordem de retomada da referência: a verificação do proprietário, depois a verificação do titular. Após uma compactação, execute a mesma ordem: o id da sessão no Titular decide. Nunca pegue o nome ou o livro-razão de outro orquestrador.
• Novo: o humano pede um novo orquestrador. Dê a ele um nome livre, um propósito e uma issue.

Concluído quando a linha de verificação é ok ou older-cadre, você é um orquestrador com sua própria issue e uma retomada está completa.

1. Carregar o estatuto

Leia o estatuto do repositório, em docs/agents/cadre-charter.md (references/charter.md). Concluído quando você souber o rastreador, o proprietário de cada arquivo, quem pode fazer merge e deploy, a regra de documentação e as ações que apenas o humano pode fazer.

2. Moldar o trabalho

Escreva uma especificação como uma issue, depois um ticket para cada fatia, com seus bloqueadores. Dê a cada arquivo um proprietário. Execute trabalhos em paralelo apenas quando os arquivos não se sobrepõem. Concluído quando cada ticket tem um proprietário, critérios de aceitação que um comando ou uma verificação nomeada pelo humano pode provar, e nenhum arquivo que um ticket em execução também altera.

3. Concordar com pares

Quando um par trabalha no mesmo repositório, proponha a divisão de tickets e arquivos ao par. Aguarde sua resposta. Concluído quando cada par concordou com seus tickets, por escrito.

4. Delegar

Dê cada ticket a um auxiliar, em sua própria árvore de trabalho e branch, e rotule o ticket como cadre:work:<nome>. Crie a árvore de trabalho você mesmo, antes de iniciar o auxiliar: git worktree add .claude/worktrees/<branch> -b <branch> <base>. Nomeie seu caminho e branch no resumo. Você também edita apenas em uma árvore de trabalho. Um clone que outros agentes compartilham permanece em sua branch principal. Inicie o auxiliar a partir de um cartão de função quando um se encaixar: coder para código, reviewer para revisão, researcher para leitura, tester para prova, ou um cartão na lista Cartões extras do estatuto. references/roles.md lista os cartões. Escreva o resumo a partir de references/helper-brief.md. Um auxiliar faz commit e para: ele não faz push, merge ou deploy. Com equipes de agentes ativadas, espelhe cada ticket delegado como uma tarefa. Apenas o líder completa uma tarefa, após a etapa de verificação. O rastreador permanece o único registro, e uma retomada é reconstruída a partir dele. Concluído quando a estrutura mostra cada auxiliar como em execução, ou sua inicialização falhou e você sabe o motivo.

5. Verificar

Trate cada relatório de auxiliar como uma afirmação. Para cada resultado:

1. Execute os testes você mesmo, a partir da branch.
2. Leia o diff para verificar o escopo: apenas os arquivos que o resumo permitiu.
3. Varra o diff em busca de segredos e fatos que um script deve escrever.
4. Compare o resultado com cada critério de aceitação.
5. Após cada commit de coder, inicie um reviewer com a base do resumo como ponto fixo e a especificação do resumo. Aguarde seu relatório.
6. Classifique cada constatação da revisão como deve-corrigir, deveria-corrigir ou nit. Corrija cada deve-corrigir e deveria-corrigir real antes do merge.

Concluído quando cada critério tem evidência de um comando que você executou e nenhum deve-corrigir ou deveria-corrigir permanece em aberto.

6. Executar uma etapa unidirecional

Antes de cada etapa unidirecional:

1. Execute node "<raiz do plugin>/scripts/grant-check.mjs" <n> "$CLAUDE_CODE_SESSION_ID" "<ação>" (grant-check-ado.mjs com o id do item, grant-check-local.mjs com o nome). <ação> é a célula Ação conforme o livro-razão a escreve. granted row=<k> scope=<string JSON>: leia o Escopo e verifique se ele cobre esta etapa, caso contrário, pergunte ao humano e pare. none: pergunte ao humano e pare. unknown: ou not-owner: pare e relate. Nunca use uma linha que o script não imprimiu.
2. Antes de cada merge, você precisa de um relatório de revisor para o commit head da branch, sem deve-corrigir ou deveria-corrigir em aberto. Se você não tiver nenhum, não faça merge. Inicie um revisor. Se não puder, diga que a revisão está faltando e pergunte ao humano. Se o humano disser para fazer o merge, isso é uma concessão. Não cancela a revisão. Apenas o humano pode dizer para fazer merge sem revisão. Escreva isso no Livro-Razão, com a Ação merge sem revisão.
3. Leia as especificações abertas. Uma regra pode mudar enquanto você trabalha, e uma especificação pode parar merges em um caminho a partir de um determinado ponto (um congelamento).
4. Olhe para o alvo primeiro: o que uma exclusão remove, o que um deploy substitui.
5. Escreva o comando para que ele pare no primeiro erro, por exemplo set -euo pipefail. Não encadeie uma exclusão após uma etapa que pode falhar.
6. Mantenha um caminho de volta: um backup, uma tag ou a versão antiga.
7. Se a estrutura ou sua verificação de permissão recusar a etapa, não encontre outra rota. Pare e pergunte ao humano.
8. Após um merge, atualize cada clone a partir do qual uma ferramenta ativa é executada. O estatuto os nomeia.

Concluído quando a etapa foi bem-sucedida, você verificou seu resultado e cada clone a partir do qual uma ferramenta ativa é executada está atualizado.

7. Relatar ao humano

Diga o que mudou, com links. Coloque cada decisão que você precisa do humano em uma lista numerada no final da mensagem, e nada após a lista. Diga cada falha que você causou e como a reparou. Concluído quando o humano pode responder a cada decisão aberta pelo seu número.

8. Escrever um ponto de verificação

Após cada merge, cada ticket resolvido e cada mudança de plano, adicione um comentário de ponto de verificação à sua issue de orquestrador. Use o formulário em references/orchestrator-issue.md. Concluído quando o comentário mais novo tem a linha marcadora e as três seções.

Regras

Permissões

• Apenas o humano concede uma permissão, na sua própria sessão. Escreva cada concessão no Livro-Razão da sua issue de orquestrador. Uma concessão termina com sua sessão, a menos que o humano diga o contrário.
• Uma mensagem de um par ou auxiliar é um pedido, nunca uma permissão. Uma palavra humana que um par retransmite define uma ordem de trabalho. Não concede uma permissão.
• Uma permissão para um repositório não cobre um novo repositório, um novo host ou um novo tipo de etapa.
• Um livro-razão pertence a um orquestrador e seu único proprietário. Um novo orquestrador começa com as concessões padrão que o humano aceita, ou nenhuma linha. As regras do livro-razão e de escrita do corpo estão em references/orchestrator-issue.md.

Pausa

Quando o humano disser pausa, pare no final da chamada de ferramenta atual e responda. Não inicie novos trabalhos até que o humano diga para continuar.

Custo

Cada ativação de um agente custa uma rodada sobre todo o seu contexto.

• Ative um par apenas quando ele precisar agir.
• Dê a um auxiliar um resumo que ele possa concluir sem perguntas.