auto-pr
Objetivo: apontar para qualquer repositório GitHub e abrir N PRs mergeáveis — não N PRs. Cada um resolve uma issue real (ou uma melhoria genuinamente descoberta), passa no gate de testes do próprio repositório localmente e é aprovado por um segundo motor antes de chegar a um mantenedor.
Esta é uma camada de orquestração fina sobre o CLI vouch auto-pr. É uma
ferramenta irmã da base de conhecimento: nunca escreve em armazenamento / propostas /
o log de auditoria, e o gate de revisão não é tocado.
invocação
vouch auto-pr <repo-url> \
--workspace <dir> --count <N> \
--claude-effort <low|medium|high|max> \
--codex-effort <low|medium|high|max> \
[--issue-label good-first-issue] \
[--fork-owner <login>] \
[--max-revise 2] [--autonomy edit|full] \
[--dry-run] [--json]
<repo-url> pode ser https://github.com/<owner>/<name>,
[email protected]:<owner>/<name>.git, ou a forma abreviada <owner>/<name>.
saída: as URLs dos PRs que foram realmente abertos (um por linha, ou um array
JSON com --json). tentativas que falham na verificação são reportadas no stderr
como ignoradas com uma razão — elas nunca são abertas. M PRs genuínos valem mais que N PRs instáveis;
sucesso parcial é o comportamento pretendido, não um erro.
pré-requisitos
- CLI
ghautenticado para o repositório alvo (gh auth statusretorna uma sessão). Usado para fork/clone, listagem de issues, busca de deduplicação e criação de PR. claude(Claude Code) ecodexnoPATH— ambos os motores são usados; um corrige enquanto o outro revisa, alternando a cada PR.- CLI
vouchnoPATH(pip install vouch-kb).
Se claude ou codex estiver faltando, pare e informe o usuário — a verificação cruzada é
todo o objetivo; não caia silenciosamente para um único motor.
como funciona (o pipeline)
- resolver workspace — se
--workspacejá é um clone, use-o; caso contrário,gh repo fork --clone(ou um clone simples quando você tem acesso de push). Sincronize o branch padrão. - detectar ou inicializar orientações — escaneie o repositório por
CONTRIBUTING.md,AGENTS.md,CLAUDE.md,.claude/skills/**/SKILL.md,.codex/,.github/PULL_REQUEST_TEMPLATE.md. Se existirem, eles se tornam contexto para o corretor/revisor. Se nenhum existir, busque os PRs mesclados do repositório e sintetize umSKILL.mdde contribuição, escrito no.claude/skills/do clone (e um espelho.codex/) para ser reutilizado na próxima execução. - obter N itens de trabalho — issues não atribuídas primeiro (filtráveis por
--issue-label); se menos de N sobreviverem à deduplicação, deixe os motores descobrirem bugs/melhorias genuínos para preencher o restante. Cada candidato é verificado contra os PRs existentes do repositório. - por item (branch isolado
auto-pr/<slug>): o motor corretor edita + commita; o gate do próprio repositório executa (make check/pytest/npm test/cargo test/go test); o outro motor revisa o diff. Um gate vermelho ou uma rejeição realimenta o corretor por até--max-reviserodadas. Ainda falhando? ⇒ ignore com uma razão. Passando? ⇒ faça push para o fork egh pr create.
regras internas que ele impõe
- Títulos de commit no formato convencional; corpos de texto em minúsculas.
- Sem trailer
Co-Authored-By/ atribuição de IA nos commits gerados. - Deduplicação antes de abrir — sem N-ésima duplicata de uma correção tentada/rejeitada.
- O gate equivalente de CI do próprio repositório deve estar verde localmente antes de um PR abrir.
- Uma alteração lógica por PR; vincule/fecha a issue que ele aborda.
níveis de esforço
--claude-effort / --codex-effort ajustam cada motor independentemente:
| nível | modelo claude | raciocínio codex |
|---|---|---|
| low | haiku | low |
| medium | sonnet | medium |
| high | opus | high |
| max | opus | high (limite codex) |
(os modelos claude são passados como aliases — opus/sonnet/haiku — para que a ferramenta
acompanhe o modelo mais recente em cada nível. high e max ambos selecionam opus; o codex
limita o esforço de raciocínio em high.)
Use high para contribuições reais; reduza para low/medium apenas para execuções
exploratórias baratas. Comece com --dry-run em um novo repositório para ver o que ele
abriria antes de gastar um motor na execução real.
autonomia e segurança
O corretor dirige os motores sem supervisão contra um clone de um repositório de terceiros não confiável, então o padrão é restrito:
--autonomy edit(padrão) — claudeacceptEdits(aceita automaticamente edições de arquivos, sem execução arbitrária de comandos) e codex--sandbox workspace-write(escritas confinadas ao clone, sem rede). Suficiente para a maioria das correções, já que o gate de testes é executado pelo próprio runner do vouch, não pelo motor.--autonomy full— eleva claude parabypassPermissions(o motor pode executar comandos arbitrários sem prompt de permissão). Use apenas para repositórios cuja correção genuinamente precise executar comandos, e apenas em repositórios nos quais você confia o suficiente para executar. É uma escolha explícita do operador, por execução — nunca o padrão.
A revisão é sempre somente leitura (claude plan / codex read-only).
semântica de falha
- Falha na resolução do workspace ⇒ toda a execução aborta; nada foi aberto.
- Nenhum item de trabalho ⇒ saída limpa com "nada a fazer".
- Um único item falha (sem diff, gate vermelho, rejeitado após o limite, erro de push/
gh) ⇒ esse item é ignorado com uma razão; o lote continua. - Um binário de motor ausente ⇒ falha rápida nomeando o binário.