trailofbits/code-improver

Code Improver

Melhore qualquer alvo de código executando /code-improver:improve — um fluxo de trabalho dinâmico que faz um loop entre o revisor nomeado e um subagente corretor até que uma revisão reporte zero descobertas críticas/graves, removendo em seguida seus próprios resíduos. O loop, seu registro e suas proteções residem no fluxo de trabalho; esta skill coleta as três entradas que o entry genérico requer e repassa o resultado.

Iniciando o loop

O usuário forneceu: $ARGUMENTS (se vazio, obtenha os detalhes da conversa).

1. Colete as três entradas obrigatórias — sem suposições

1. Alvo: o caminho absoluto para o diretório sob melhoria. Resolva caminhos relativos a partir do diretório de trabalho; verifique se o diretório existe.
2. Revisor: a skill ou agente instalado que realiza cada revisão. O usuário deve nomeá-lo — não há valor padrão e nenhum revisor embutido. Determine o tipo:
   • um agente namespaced (ex.: plugin-dev:skill-reviewer) → "kind": "agent"
   • uma skill instalada (ex.: pr-review-toolkit:review-pr) → "kind": "skill" Se o nome puder ser de qualquer tipo, verifique a lista de skills da sessão; se ainda ambíguo, pergunte ao usuário. Se nenhum revisor foi nomeado, pergunte — não escolha um.
3. Escopo: globs relativos ao repositório que o loop pode tocar. O entry genérico o exige explicitamente; se o usuário não o forneceu, proponha o diretório alvo (<repo-relative-target>/**) e confirme antes de lançar.

2. Resolva o script do loop

O loop é o fluxo de trabalho dinâmico workflows/improve.js neste plugin. Lance-o pelo caminho: scriptPath recebe um caminho absoluto resolvido, e o nome da ferramenta Workflow resolve fluxos embutidos e de projeto, então um instalado do marketplace pode não responder a code-improver:improve. Tente em ordem, o primeiro que funcionar vence — os diretórios home vêm antes de . para que uma cópia instalada supere um checkout deste marketplace:

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js" (se essa variável estiver definida)
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Use o caminho exatamente como impresso. Seu diretório plugin — o caminho com /workflows/improve.js removido — é pluginRoot. Se todos os três retornarem vazios, tente {name: "code-improver:improve"} uma vez; se também estiver indisponível, pare e diga que o loop não pôde ser localizado. Não monte um caminho manualmente e não improvise o loop.

3. Invoque o fluxo de trabalho

Execute-o com a ferramenta Workflow, {scriptPath: "<caminho do passo 2>", args: {...}}:

{
  "target": "<caminho absoluto do alvo>",
  "reviewer": { "kind": "agent|skill", "name": "<nome-namespaced>", "notes": "<o que o revisor deve saber sobre o alvo>" },
  "scope": ["<glob-relativo-ao-repo>/**"],
  "pluginRoot": "<diretório plugin do passo 2>",
  "maxRounds": 5
}

• maxRounds apenas se o usuário pediu um limite diferente.
• pluginRoot permite que a execução encontre seu coletor de métricas; omita a chave apenas se o passo 2 acabou usando o nome do fluxo — o fluxo então se busca.
• finalize ({"version_bump": bool, "narration_strip": bool, "docs_pass": bool}) apenas para sobrescrever os padrões: version bump quando o alvo está dentro de um plugin, narração strip e docs pass sempre.
• decision apenas na continuação (abaixo).

O fluxo de trabalho roda em background e não precisa de supervisão: ele revisa, corrige, re-revisa, verifica escopo após cada rodada de correção, e só pode ser concluído com uma revisão limpa. Ele nunca faz commit; todas as alterações permanecem na árvore de trabalho.

Se a ferramenta Workflow estiver indisponível ou negada, pare e diga isso. Não improvise o loop diretamente com edições — o registro, o guardião de escopo e as garantias de escalação vivem no fluxo de trabalho, e uma imitação inline não tem nenhum deles.

Se o resultado for halted: "reviewer-unavailable", repasse-o e pare. O revisor nomeado não está instalado nesta sessão; diga ao usuário qual plugin o fornece e re-execute após a instalação. Não revise o alvo você mesmo.

Não termine seu turno enquanto o loop estiver rodando. A ferramenta Workflow retorna um id de tarefa imediatamente; o resultado vem depois. Em uma sessão interativa a notificação de conclusão re-invoca você — aguarde. Em uma execução não interativa (scriptada, CI, avaliação) não há turno posterior: parar abandona o loop no meio de uma rodada, então após lançar, faça polling da tarefa (TaskOutput com o id da tarefa retornado, ou durma-e-reverifique) até que ela complete, então repasse o resultado. Uma sessão que responde "o loop está rodando, vou relatar depois" perdeu a execução.

Repassando o resultado

O fluxo de trabalho retorna um resultado estruturado. Relate-o honestamente — as distinções importam:

• converged: true — a última ação foi uma revisão com zero descobertas críticas/graves. Reporte as rodadas usadas, as descobertas menores restantes (open_minor_count) e os caminhos dos artefatos (ledger_path, metrics).
• capped: true — o orçamento de correções acabou e a revisão FINAL ainda encontrou problemas bloqueantes. Diga claramente: limitado, NÃO convergido, e liste open_blocking. Não apresente isso como sucesso.
• escalation — o loop detectou que não estava convergindo (descobertas recorrentes, contagens não decrescentes, ou uma correção deslocando um problema). Repasse a mensagem de escalação e os ids das descobertas ao usuário: isso precisa de uma decisão de design, não de mais rodadas.
• halted — um guardião disparou (violação de escopo, novos arquivos não registrados, um revisor morto ou indisponível, ou uma passada de finalização cujas próprias edições falharam na verificação que a segue). Repasse os caminhos em violations/new_untracked_files, os locais em finalize_regressions e as notas.
• notes sempre acompanham o resultado — destaque-os; eles incluem avisos importantes como "um repositório git foi inicializado".

Continuando após uma escalação

O loop para na escalação por design. Quando o usuário decidir, inicie uma nova execução com o mesmo target e reviewer mais:

{ "decision": "<a decisão do usuário, na íntegra>" }

A nova execução recarrega o registro em disco, então cada descoberta, rejeição e veredito se mantém — as rodadas reiniciam, a re-derivação não ocorre.

Para parar um loop em execução, interrompa a tarefa do fluxo de trabalho (TaskStop); o registro em disco está atualizado até a última rodada e uma re-execução retoma a partir dele.

Quando NÃO usar

• Uma skill do Claude Code: use o entry skill-improver — ele conecta o revisor correto
• Uma branch / pull request: use o entry pr-improver — ele deriva o escopo do diff
• Revisão única: despache o revisor diretamente; o valor do loop é a iteração
• Correções únicas rápidas: edite o arquivo diretamente