auto-pr

auto-pr

Goal: point at any github repo and open N mergeable PRs — not N PRs. each one resolves a real issue (or a genuine discovered improvement), passes the repo's own test gate locally, and is signed off by a second engine before it ever reaches a maintainer.

this is a thin orchestration layer over the vouch auto-pr CLI. it is a sibling tool to the knowledge base: it never writes to storage / proposals / the audit log, and the review gate is untouched.

invocation

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> may be https://github.com/<owner>/<name>, [email protected]:<owner>/<name>.git, or the <owner>/<name> shorthand.

output: the URLs of the PRs that were actually opened (one per line, or a JSON array under --json). attempts that fail verification are reported on stderr as skipped with a reason — they are never opened. M genuine PRs beats N shaky ones; partial success is the intended behaviour, not an error.

prerequisites

• gh CLI authenticated for the target repo (gh auth status returns a session). used for fork/clone, issue listing, dedup search, and PR creation.
• claude (Claude Code) and codex on PATH — both engines are used; one fixes while the other reviews, alternating per PR.
• vouch CLI on PATH (pip install vouch-kb).

if claude or codex is missing, stop and tell the user — cross-verify is the whole point; don't silently fall back to a single engine.

how it works (the pipeline)

1. resolve workspace — if --workspace is already a clone, use it; else gh repo fork --clone (or a plain clone when you have push access). sync the default branch.
2. detect-or-bootstrap guidance — scan the repo for CONTRIBUTING.md, AGENTS.md, CLAUDE.md, .claude/skills/**/SKILL.md, .codex/, .github/PULL_REQUEST_TEMPLATE.md. if any exist, they become fixer/reviewer context. if none exist, fetch the repo's merged PRs and synthesize a contribution SKILL.md, written into the clone's .claude/skills/ (and a .codex/ mirror) so it's reused next run.
3. source N work items — open unassigned issues first (filterable by --issue-label); if fewer than N survive dedup, let the engines discover genuine bugs/improvements to fill the remainder. every candidate is dedup-checked against the repo's existing PRs.
4. per item (isolated auto-pr/<slug> branch): the fixer engine edits + commits; the repo's own gate runs (make check / pytest / npm test / cargo test / go test); the other engine reviews the diff. a red gate or a rejection feeds back to the fixer for up to --max-revise rounds. still failing ⇒ skip with a reason. passing ⇒ push to the fork and gh pr create.