CommunityEscrita e Ediçãogithub.com

vouchdev/vouch

Uma base de conhecimento revisada por humanos, nativa do Git, para agentes de IA: eles propõem alterações, você as aprova. Cada alegação cita uma fonte, cada mudança é um diff no seu repositório. MCP + CLI.

O que é vouch?

Esta skill orquestra o CLI `vouch auto-pr` para abrir pull requests (PRs) que são genuinamente mergeáveis em qualquer repositório GitHub. Diferente de ferramentas que geram PRs em massa, ela garante que cada PR resolva uma issue real ou uma melhoria descoberta, passe nos testes locais do repositório e seja revisada por um segundo motor de IA antes de chegar a um mantenedor. A skill detecta automaticamente as normas de contribuição do repositório (de arquivos como CONTRIBUTING.md ou AGENTS.md) e, se necessário, as sintetiza a partir de PRs mesclados anteriores, garantindo que as contribuições sigam o estilo e os padrões do projeto. Ela suporta o ecossistema Claude Code e Codex, utilizando um motor como 'corretor' e o outro como 'revisor', alternando a cada PR, com níveis de esforço configuráveis para cada motor. Recursos de segurança, como o modo de autonomia restrita (`edit`) e a verificação de gate de testes, previnem que PRs quebrados ou mal formatados cheguem ao repositório original.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add vouchdev/vouch

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 gh autenticado para o repositório alvo (gh auth status retorna uma sessão). Usado para fork/clone, listagem de issues, busca de deduplicação e criação de PR.
  • claude (Claude Code) e codex no PATH — ambos os motores são usados; um corrige enquanto o outro revisa, alternando a cada PR.
  • CLI vouch no PATH (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)

  1. resolver workspace — se --workspace já é 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.
  2. 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 um SKILL.md de contribuição, escrito no .claude/skills/ do clone (e um espelho .codex/) para ser reutilizado na próxima execução.
  3. 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.
  4. 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-revise rodadas. Ainda falhando? ⇒ ignore com uma razão. Passando? ⇒ faça push para o fork e gh 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ívelmodelo clauderaciocínio codex
lowhaikulow
mediumsonnetmedium
highopushigh
maxopushigh (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) — claude acceptEdits (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 para bypassPermissions (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.

Habilidades Relacionadas