ptmrio/harness-subagent

Harness Subagent

Despache outro agente de codificação como subagente único, depois sintetize.

Princípio central: o harness é um subagente, não um oráculo. Um modelo revisando seu próprio trabalho reproduz seus próprios pontos cegos. Esse valor é destruído se você encaminhar a resposta sem julgá-la.

Voz do orquestrador: nível CTO — breve, conciso, bullet points, prévias ASCII quando forem melhores que prosa. Mantenha-se alinhado com o operador humano (superficie suposições; pergunte sobre ações irreversíveis e preferências de produto não estabelecidas; não invente escopo silenciosamente).

Rota fixa: Se o filho atingir limites de uso/taxa (ou qualquer falha suave que tente uma troca), não redirecione para outro backend ou modelo. Relate a falha, marque como NÃO VERIFICADO / bloqueado, pergunte uma vez. Exceção: uma pergunta no-verdict da mesma família / "qual harness" é um vazamento de ninho — reescreva a cerca de identidade, relance uma vez, mesmo backend; não pergunte e não troque. Em um loop de orquestração completo, pare a lista de verificação — não continue para estágios posteriores sem a entrega do estágio falhado (por exemplo, não Implemente se Práticas morreu em um limite).

Não escolha um harness por causa de um estereótipo de tarefa, a menos que a configuração do usuário tenha essa chave (veja references/user-config.md). Ordem de roteamento: esta expressão → configuração do usuário → pergunte uma vez. Mesmo protocolo para cada backend. Mapa de personalidade de papéis e Superpoderes: references/roles.md (canônico).

Padrão para Revisar (não edite arquivos da aplicação). Permita gravações na aplicação apenas quando o usuário (ou um plano aprovado) pedir Implementar. Revisão e Visual podem criar arquivos temporários e escrever relatórios.

Níveis de comando (não misture)

Esta skill é de uso único. O filho não deve reentrá-la. CLIs de fornecedores podem permitir Agente aninhado/spawn_agent; isso não é licença para executar este protocolo novamente.

Nível	Quem	Comandos	Proibido como "seus"
L0	Humano	/harness-subagent, "orquestre", harness nomeado, fixar self	Flags de spawn.sh
L1	Pai que carregou esta skill	scripts/spawn.sh --backend --mode, roteamento de configuração, pular mesma família, perguntar uma vez, sintetizar	Colocar invocações de spawn.sh no brief; perguntar ao filho qual harness
L2	CLI spawn.sh lançada	Apenas Superpoderes do papel, Playwright / capturas nomeadas, report.md	Esta skill, spawn.sh, requesting-code-review, "qual harness?", pergunta da mesma família

L1 invoca scripts/spawn.sh --mode …. Esse argv não é uma instrução para o filho. Se você é L2 (HARNESS_SUBAGENT_RUN definida, ou o prompt começa com VOCÊ É O TRABALHADOR), pare de ler este protocolo de spawn e faça o trabalho descrito no brief.

spawn.sh exporta HARNESS_SUBAGENT_RUN e define CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1. Um spawn.sh aninhado morre (variável já definida).

Orquestrar vs uso único

Precedência (avalie em ordem):

1. Especificação de trabalho único vence uso único — a expressão nomeia um trabalho (segunda opinião, revisar este diff, implementar apenas …, reescrever o README, pesquisar X) → um brief, um spawn. Um "Orquestre isto —" inicial não força o loop completo.
2. Loop completo explícito vence — o usuário diz "execute o loop completo" / nomeia práticas+implementar+revisar juntos / "orquestre esta funcionalidade de ponta a ponta" aberto sem substantivo de trabalho único → lista de verificação completa abaixo. Um harness nomeado aqui apenas fixa o backend para cada estágio (ou configuração por estágio); não colapsa o loop em um único disparo.
3. Caso contrário, pergunte uma vez o que eles querem (loop completo vs trabalho único).

Lista de verificação do loop completo (pule etapas já feitas ou dispensadas pelo usuário; um trabalho por spawn):

1. Práticas — Pesquise (ou self do pai se fixado): exatamente duas âncoras — uma diretriz oficial Anthropic + uma OpenAI. Opcionalmente, suplemente (não substitua) com Cursor/xAI quando a pilha/harness os tornar relevantes. Cite + carimbo de data.
2. Implementar — fatia delimitada contra essas práticas. Cole a tabela TDD completa de roles.md.
3. Validar — code-review (adversarial). Adicione code-review-visual quando UI estiver envolvida.
4. Coerência final — self padrão do pai (ou um spawn curto de Revisão): lógica, redundância, sanidade geral contra as duas âncoras e a solicitação original.

Se qualquer estágio estiver bloqueado (incluindo limites de rota fixa), pare e pergunte — não pule adiante.

Escolha um backend

Nunca spawn a própria família do pai a menos que o usuário a tenha nomeado nesta rodada (pai Grok → sem grok; pai Claude Code → sem claude; pai Codex → sem codex; pai Antigravity → sem agy). Um harness por pergunta, a menos que o usuário tenha solicitado múltiplas opiniões.

Família é o produto/CLI pai, não o id do modelo. Cursor Agent, cursor-agent e Grok Bot são cursor (mesmo quando o modelo é Grok). CLI Grok Build é grok. Claude Code é claude. CLI Codex é codex. CLI Antigravity é agy. CLI Gemini legado é gemini (uma família diferente; não trate como agy). Um pai Cursor com defaults.implement = "cursor" pula e pergunta uma vez — esse token é um backend, não self. Fixe self quando esta sessão deve fazer o trabalho.

Usuário diz	Binário (PATH)	Modelo padrão (série mais recente)	Pensamento padrão	Flags
Claude, Opus, Fable, ask-claude	claude	opus (também fable, sonnet, haiku)	xhigh	references/backend-claude.md
GPT, Codex, Sol, Terra, Luna, ask-gpt	codex	gpt-5.6-sol	xhigh	references/backend-codex.md
Grok, ask-grok	grok	grok-4.6	xhigh	references/backend-grok.md
Gemini, Antigravity, agy, ask-gemini	agy	padrão do fornecedor (omitir --model; listar: agy models)	high	references/backend-agy.md
Não especificado	Chave defaults.* correspondente na configuração do usuário (spec, spec-ui, plan, plan-ui, implement, implement-ui, writer, research, code-review, code-review-visual, …) se definida e (backend não é da família do pai, ou valor é self-class); caso contrário, pergunte uma vez. Aliases de Revisão: code-review-task / code-review-adversarial / code-review-adverserial / review → code-review (veja ordem de resolução em user-config).	Config [models] / [effort], senão padrões da tabela	—	references/user-config.md

Se o usuário fixou um id de modelo, use-o. Cursor Agent / OpenCode / Droid / CLI Gemini legado: references/more-clis.md (não em scripts/spawn.sh). Token de configuração gemini é esse CLI legado, não um alias para agy.

Liste o que esta máquina realmente tem:

claude --help
codex debug models --bundled
grok models
agy models
cursor-agent --list-models

Windows PowerShell: Get-Command claude,codex,grok,agy. Não codifique ~/.local/bin/…. agent no PATH é frequentemente Grok Build, não Cursor. O CLI do Cursor é cursor-agent.

Não há skill harness-spawn. Stubs obsoletos ask-claude / ask-gpt / ask-grok: esta skill.

Configuração do usuário

Opcional. Sobrevive a atualizações da skill. Nunca armazene preferências no clone da skill (npx skills add se espalha em todos os diretórios do agente).

• Se $HARNESS_SUBAGENT_CONFIG estiver definido: esse arquivo. Arquivo ausente → pergunte uma vez (não caia para o próximo).
• Senão: ${XDG_CONFIG_HOME:-$HOME/.config}/harness-subagent/config.toml

Esquema, busca, e caminho de escrita "sempre use X": references/user-config.md. Não crie o arquivo a menos que o usuário tenha pedido para fixar.

Se o valor de defaults.* correspondente for self, orchestrator, parent ou you, faça o trabalho nesta sessão. Não escreva um brief. Não chame scripts/spawn.sh. Um backend da família do pai (grok enquanto você é Grok) não é self — pule e pergunte uma vez a menos que esta expressão nomeie esse harness.

SO, temp, stdin

Agentes pais frequentemente canalizam stdin. Trate isso como hostil.

	Linux / macOS / WSL	Windows cmd	Windows PowerShell
Diretório de execução	${TMPDIR:-/tmp}/harness-subagent/<run-id>	%TEMP%\harness-subagent\<id>	Join-Path $env:TEMP "harness-subagent\<id>"
Spawn	bash <skill>/scripts/spawn.sh …	Git Bash no caminho do script	argv de arquivo do Git Bash (abaixo) — nunca uma receita -lc entre aspas duplas

Invoque scripts/spawn.sh do diretório da skill do SKILL.md que você carregou nesta rodada (caminho no cabeçalho da skill). npx skills add -g distribui cópias; não misture ~/.claude/skills, ~/.cursor/skills e ~/.agents/skills em uma sessão.

cwd / -C / --cwd deve ser um caminho que o CLI entenda (WSL /mnt/d/… vs Windows D:\…). Não misture Windows claude.exe no WSL.

Capturas de tela visuais: Claude e Cursor Agent precisam de --add-dir "$RUN" com capturas em $RUN. agy Revisão/Visual também; agy Implementar não deve passar --add-dir (torna $RUN um espaço de trabalho gravável). Grok: copie capturas para dentro de --project (árvore da aplicação), nunca apenas em $RUN — Grok não consegue ler o diretório temporário de execução. Codex: -i (script --image).

Windows PowerShell (armadilhas — não pule)

PowerShell expande $(…), cat e $RUN antes do bash vê-los. Um & bash -lc "claude … $(cat $RUN/brief.md) > $RUN/last.md" entre aspas duplas vai procurar D:\c\Users\…, escrever last.md em /, ou passar um prompt vazio/achatado. system32\bash.exe é WSL — ele não pode ver %TEMP% como /c/….

1. Fixe o Git Bash: "$env:ProgramFiles\Git\bin\bash.exe" (confirme Test-Path; não use bash do WSL).
2. Escreva brief.md com a ferramenta Write (UTF-8). Não use Out-File / > do PowerShell 5.1 (UTF-16LE + NULs).
3. Execute o script da skill como argumentos, coloque a chamada Shell em segundo plano (block_until_ms: 0 no Cursor):

& "$env:ProgramFiles\Git\bin\bash.exe" -- "<skill-dir>\scripts\spawn.sh" --backend claude --mode review --project "D:/Code/app" --run "C:/Users/<you>/AppData/Local/Temp/harness-subagent/<id>"

4. Liste o diretório de execução com Shell (Get-ChildItem / ls). O Glob do Cursor tem escopo no workspace e perderá %TEMP%.
5. Duas falhas de lançamento → pare. Responda a partir das evidências do pai. Marque o harness como NÃO VERIFICADO. Não invente uma terceira receita de citação.

Se este pai permite automaticamente apenas alguns CLIs, o spawn será bloqueado no bash / bash.exe, neste script, ou no backend alvo (codex, …). Peça ao usuário para permitir esses, ou use um modo de aprovação que possa permitir o spawn único. Não codifique uma lista de permissões da máquina.

Spawn fixa permissão Auto-equivalente: Claude/Grok --permission-mode auto. Codex todos os modos --approve-for-me (não passe também --sandbox: mutex 0.147). agy Implementar --dangerously-skip-permissions (agy não tem classificador Auto; isso é YOLO). agy Revisão omite. Claude Revisão ainda omite Editar/Escrever em --tools (Bash permanece para arquivos temporários). Não passe --ask-for-approval para codex exec (apenas TUI; exec rejeita). Restrição de edição de aplicação é o brief (Não edite arquivos da aplicação.), não um sandbox somente leitura.

Protocolo compartilhado

0. Portão. Nomeie a única coisa que você não pode responder a partir deste repositório / deste contexto. Se você não puder nomeá-la, não faça spawn — a menos que esta expressão já tenha nomeado um harness (expressão ainda vence; writer=self não suprime "Peça ao Claude para reescrever o README"). Nomenclatura, estilo, formatação e "já tentei" que já são a resposta não valem uma execução. Escrita/pesquisa sustentada (uma reescrita de README, uma consulta competitiva) não é "nomear": faça spawn quando a rota resolvida for um CLI.
1. Escreva brief.md sob o diretório temporário de execução (nunca dentro do repositório).
2. Faça spawn de scripts/spawn.sh em segundo plano (minutos; um timeout em primeiro plano mata o gasto). Não copie ou edite o script.
3. Aguarde até que o processo termine. Então leia $RUN/last.md e $RUN/capture-status.txt. Processo ainda rodando + sem VERDICT ainda → não concluído. spawn.sh já prefere $RUN/report.md sobre o stdout final e normaliza linhas em negrito/VERDICT:. Se o status for usage-limit ou no-verdict, marque o harness como NÃO VERIFICADO / bloqueado — não invente um veredito e não redirecione backends (rota fixa). Exceção: no-verdict que é uma pergunta da mesma família / "qual harness" é um vazamento de ninho — reescreva a cerca de identidade e relance uma vez (mesmo backend). Não relance um trabalho concluído por causa de um preâmbulo.
4. Sintetize — nunca apenas cole.

Escreva o brief

Descrição da tarefa, não um despejo de dados. Não cole diffs ou conteúdos de arquivo — nomeie caminhos e uma investigação delimitada. Exceção: arquivos inacessíveis a partir do diretório de trabalho (capturas de tela sob o diretório temporário de execução).

• Prefira arquivos/símbolos nomeados a "explore o repositório."
• Diff: intervalo exato, git diff <A>..<B> -- <caminhos…>.
• Visual/confirmação: proíba git log, git diff de árvore completa, despejos de status. spawn.sh --image é apenas Codex. Claude: copie capturas em $RUN (já recebe --add-dir "$RUN"). Grok: copie capturas em --project. Nomeie os arquivos no brief.
• Coloque evidências do pai sob O que já foi tentado. Prefira "verifique isso" a "redescubra." Se você já executou gh/curl e o Codex Review pode não ter rede, coloque a saída aqui e proíba reexecutar esses comandos.
• Substituição de produto: se o usuário bloqueou uma decisão de produto, diga isso.

Seis partes, em ordem:

1. Cerca de identidade do filho — cole primeiro, literalmente, de references/roles.md. Nunca escreva scripts/spawn.sh ou --mode visual no brief (L2 trata isso como uma ordem para re-orquestrar).
2. Objetivo — uma frase nomeando o veredito / entrega (dica de objetivo do cartão de papel).
3. Onde olhar — caminhos, comandos delimitados, símbolos; lista de permissão de edição se Implementar.
4. O que já foi tentado
5. O que mudaria minha opinião — evidências de liquidação (Revisão) ou portões de aceitação (Implementar).
6. Formato de retorno — cole de references/roles.md: o contrato de retorno do papel (inclui escreva report.md antes da limpeza), mapa de Superpoderes (nomes exatos), deve/não deve, e para implementar/implement-ui a tabela de política TDD completa (nunca "veja roles.md" sozinho). O cartão de papel vence qualquer redação de stub mais antiga. Nomeie o caminho do diretório de execução para report.md.