amElnagdy/delegate-skills

Pi Delegate

Você é o orquestrador. Delegue uma tarefa de codificação delimitada a um implementador separado - a CLI do agente de codificação Pi - então revise o que foi produzido e faça o commit você mesmo. Você escreve o briefing e detém o julgamento; o implementador faz as alterações em sua própria sessão; você verifica e faz commit.

O ciclo precisa apenas de um comando de shell e acesso a arquivos, então qualquer orquestrador comparável pode conduzi-lo.

Quando NÃO usar isso

• A tarefa é pequena o suficiente para ser feita inline; a sobrecarga de delegação não vale a pena.
• A CLI pi não está instalada ou autenticada.
• Você precisa de um implementador em ambiente isolado. Pi não tem sandbox e nem modos de permissão; --read-only restringe a superfície de ferramentas, mas uma execução com capacidade de escrita executa sem prompts.

Pré-requisitos (verifique uma vez)

1. Instale pi com npm install -g @earendil-works/pi-coding-agent.
2. Autentique-se: /login dentro do pi para um provedor de assinatura, ou uma variável de ambiente de chave de API / arquivo de autenticação do pi para um provedor de chave de API.
3. Confirme que pi --version funciona.
4. Trabalhe no repositório git de destino, ou aponte --cd para ele.

Escolha o modelo (opcional)

Omita --model para usar o padrão configurado do pi. Para escolher outro, selecione a partir de pi --list-models e passe um id explícito ou padrão como <provider>/<model-id> ou sonnet:high. O relay aceita apenas letras, dígitos e . _ : / - (o valor chega a um shell no Windows), então padrões glob com * não são encaminhados.

O ciclo

Execute estas cinco etapas por tarefa. As etapas 1, 4 e 5 exigem julgamento; 2 e 3 são mecânicas.

1. Escreva o briefing

Pi vê apenas o texto que você envia, mais o que pode inspecionar no espaço de trabalho - sem histórico de chat ou contexto compartilhado. Inclua o objetivo, o estado atual, o que mudar, o que deixar intocado, os verdadeiros portões do projeto e um contrato de relatório. Diga ao pi para não fazer commit. Mantenha uma tarefa por briefing. Pi carrega automaticamente os arquivos de contexto AGENTS.md/CLAUDE.md do espaço de trabalho e seus diretórios pai, então as instruções do repositório chegam sem necessidade de incluir inline. Veja references/writing-the-brief.md.

2. Envie

Use o relay fornecido. Ele envia o briefing para pi --mode json no stdin, captura o fluxo de eventos JSON e escreve result.json. (<skill-dir> é a pasta instalada que contém este SKILL.md.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /caminho/para/repositorio
# escolha um modelo:                           adicione --model <id de pi --list-models>
# escolha um provedor:                         adicione --provider <nome>
# execução somente leitura (revisão/diagnóstico):  adicione --read-only
# confiar nos recursos .pi do projeto:          adicione --approve
# retomar a sessão mais recente:                 adicione --resume-last  (apenas briefing delta)
# retomar uma sessão específica:                 adicione --session <id> (apenas briefing delta)
# limite de tempo rígido (watchdog):            adicione --timeout 2h  (o padrão de 30 minutos serve para execuções curtas; briefings de implementação geralmente precisam de 1-2h)
# ver todas as opções:                          node .../relay.mjs --help

O cwd do processo filho fixa o espaço de trabalho. O relay escreve artefatos no diretório temp do sistema por padrão e nunca faz commit. Veja references/dispatch-and-poll.md.

3. Aguarde a conclusão

O relay bloqueia até o pi terminar. Execute-o com o recurso de comando em segundo plano do orquestrador, ou coloque-o em segundo plano no shell e verifique a existência de result.json. Um erro de uso pré-execução sai com código 2 e não escreve resultado; um pi ausente sai com código 127 e escreve status: "pi_unavailable".

Confie no estado do processo e na árvore de trabalho em vez de uma exibição de progresso. Conclusão significa que o processo terminou e result.json existe. O relatório completo do pi é o campo finalMessage em result.json (também impresso na íntegra no stdout entre os marcadores de relatório).

4. Revise - não confie no autorrelato

Trate a mensagem final do pi e as alegações de portões como alegações:

• Execute os portões do projeto você mesmo.
• Leia o diff contra o briefing, começando com touchedFiles.
• Execute skills de guarda relevantes, se instaladas.
• Faça migrações completas e busque por referências pendentes após remoções ou renomeações.

Veja references/review-and-land.md.

5. Finalize

O implementador edita a árvore de trabalho; o orquestrador faz o commit. Faça o commit somente após os portões passarem e o diff se sustentar. Se for necessário retrabalho, envie um briefing delta com --resume-last ou --session <id>, então revise novamente.

Autonomia e permissões

Pi não tem sandbox e nem modos de permissão. Uma execução headless padrão lê, escreve, edita e executa comandos de shell sem prompts - os controles são:

1. --read-only restringe as ferramentas chamáveis do pi para --tools read,grep,find,ls em ferramentas integradas, de extensão e personalizadas. O código de extensão instalado ainda é executado com as permissões do host do usuário.
2. O relay passa --no-approve por padrão, então as configurações .pi do projeto, extensões e skills permanecem não confiáveis. --approve é a aceitação explícita para um repositório que o usuário confia.
3. touchedFiles e o diff são o registro do que mudou. Inspecione-os após cada execução.

Modelo de autorização

A delegação é algo que o humano opta por fazer. Uma vez que ele tenha aceitado ("execute esta fila", "prossiga"), fazer commit de trabalho verificado que passa nos portões é o contrato acordado. Dois limites permanecem: superfície, não absorva (relate as decisões de design do pi, desvios defensáveis mas não solicitados, e pequenos problemas não bloqueadores) e pare para mudanças de escopo (se a conclusão correta exigir ir além do briefing, pergunte em vez de expandir o mandato). Veja references/review-and-land.md.

Referências

• references/writing-the-brief.md - estrutura, contrato de relatório, portões reais, entrega via stdin e briefings delta.
• references/dispatch-and-poll.md - flags, artefatos, result.json, polling e recuperação de falhas.
• references/review-and-land.md - lista de verificação de revisão, limite de commit e retrabalho através de sessões pi.
• references/multi-task-queues.md - filas sequenciais, propagação de restrições, acompanhamento de progresso e a passagem final de coerência.