Suporte upstream empacotado

Arquivos de suporte são incluídos em caminhos relativos à skill. Veja UPSTREAM-NOTICE.md para suas fontes fixadas, licenças, hashes e alterações de importação.

Pi Delegate

Quando Usar

• Você quer delegar uma tarefa de codificação limitada a um pi implementador separado (Pi) e depois revisar o diff gerado por você mesmo.
• O usuário pediu explicitamente a delegação para este implementador.

Você é o orquestrador. Delegue uma tarefa de codificação limitada a um implementador separado - o agente de codificação CLI do Pi - depois revise o que ele produziu e aplique as mudanças você mesmo. Você escreve o resumo e é responsável pelo julgamento; o implementador faz as alterações em sua própria sessão; você verifica e confirma.

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

Quando NÃO Usar

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

Pré-requisitos (verificar uma vez)

1. Instale o pi com npm install -g @earendil-works/pi-coding-agent.
2. Autentique: /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 é bem-sucedido.
4. Trabalhe em, ou aponte --cd para, o repositório git alvo.

Escolha o modelo (opcional)

Omita --model para usar o padrão configurado do pi. Para escolher outro, selecione entre 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 loop

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

1. Escreva o resumo

O Pi vê apenas o texto que você envia mais o que ele pode inspecionar no workspace - sem histórico de chat ou contexto compartilhado. Inclua o objetivo, o estado atual, o que mudar, o que não tocar, os portões reais do projeto e um contrato de relatório. Diga ao Pi para não confirmar. Mantenha uma tarefa por resumo. O Pi carrega automaticamente arquivos de contexto AGENTS.md/CLAUDE.md do workspace e seus pais, então instruções do repositório chegam a ele sem serem incluídas. Veja references/writing-the-brief.md.

2. Despache

Use o relay empacotado. Ele envia o resumo para pi --mode json via stdin, captura o fluxo de eventos JSON e escreve result.json. (<skill-dir> é a pasta instalada contendo este SKILL.md.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a model:                          add --model <id from pi --list-models>
# choose a provider:                       add --provider <name>
# read-only run (review/diagnosis):        add --read-only
# trust project .pi resources:             add --approve
# resume the most recent session:          add --resume-last  (delta brief only)
# resume a specific session:               add --session <id> (delta brief only)
# hard time limit (watchdog):              add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# see all options:                         node .../relay.mjs --help

O cwd do processo filho fixa o workspace. O relay escreve artefatos no diretório temporário do sistema por padrão e nunca confirma. Veja references/dispatch-and-poll.md.

3. Aguarde a conclusão

O relay bloqueia até que o Pi termine. Execute-o com a instalação de comando em segundo plano do orquestrador, ou coloque-o em segundo plano no shell e consulte 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 por extenso no stdout entre os marcadores de relatório).

4. Revise - não confie no auto-relato

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

• Re-execute os portões do projeto você mesmo.
• Leia o diff em relação ao resumo, começando com touchedFiles.
• Execute skills de guarda relevantes se instaladas.
• Migrações de ida e volta e grep por referências pendentes após remoções ou renomeações.

…