Auto GitHub Contributor

auto-github-contributor — interactive OSS PR agent

One command, full pipeline, any repo:

1. Check prerequisites (gh, git, jq, gh auth) — guide the user to fix anything missing.
2. Ask for the target repo (owner/name or GitHub URL). Default fork to the authed gh user.
3. Discover candidates from two sources in parallel:
   • Labeled issues (good first issue, help wanted, documentation, etc.)
   • Repo scan for quick wins (typos, missing tests, i18n gaps, actionable TODOs)
4. Present a ranked picklist with estimated time + LLM cost per item.
5. Wait for explicit user confirmation before touching anything.
6. Run the TDD dev-loop (red → green → refactor) until lint / typecheck / tests all pass.
7. Push + open PR via gh. Print the PR URL on its own line so the user can click.

Scripts live next to this file under scripts/. Each script emits machine-readable KEY=VAL lines on stdout and logs to stderr. Source the shared helpers from every script:

source "$(dirname "$0")/config.sh"

Override config via env vars on invocation:

TARGET_REPO=owner/name TARGET_FORK=me/name bash <script>

Execution steps — follow in order

Step 1 — Prerequisite check (always first)

bash "$SKILL_DIR/scripts/check-prereqs.sh"

Reads GH_USER=... from stdout — capture it as the default fork owner.

• Exit code 0: continue.
• Exit code 2: surface the printed install / auth hint verbatim to the user and stop. Do not attempt token workarounds, sudo installs, or other shortcuts. The user runs the fix and restarts the flow.

Step 2 — Resolve the target repo

Priority order:

1. If the slash command passed TARGET_REPO via $ARGUMENTS, normalize and use it.
2. Otherwise, ask the user via AskUserQuestion with one free-text prompt titled "Target repo" and hint owner/name or https://github.com/owner/name. If the user gives a URL, strip the protocol + trailing .git.
3. Ask for fork owner (optional) — default to $GH_USER. If the user confirms no fork, TARGET_FORK stays empty and we push to origin (create-pr.sh will warn 3s before doing so).

Validate: gh repo view "$TARGET_REPO" must succeed. If the repo doesn't exist or the user lacks access, stop and surface the gh error.

Export TARGET_REPO and TARGET_FORK for the rest of the session.

Step 3 — Discover candidates (parallel)

3a. Labeled issues

bash "$SKILL_DIR/scripts/fetch-issues.sh" > /tmp/agc-issues.json

This queries each label in $AGC_LABELS (default: good first issue, help wanted, documentation, good-first-issue), merges, de-dupes, and ranks by a score that weights label specificity + freshness + body clarity. Top of the list = easiest high-quality pick.

3b. Repo quick-win scan

We need a shallow clone first so scan-quick-wins.sh has files to read. Use a scratch clone rather than the per-issue workdir (no branch yet):

SCRATCH="$AGC_WORK_ROOT/$(echo $TARGET_REPO | tr / -)/_scratch"
if [[ ! -d "$SCRATCH/.git" ]]; then
  git clone --depth 1 "https://github.com/$TARGET_REPO.git" "$SCRATCH"
fi
bash "$SKILL_DIR/scripts/scan-quick-wins.sh" --workdir "$SCRATCH" > /tmp/agc-quickwins.json

Returns an array of {kind, title, summary, file, line, estimated_minutes, slug}. Kinds: typo, missing-test, i18n, todo.

Step 4 — Present the picklist

Render a single merged table. For each entry compute:

• Estimated time — issues: flat 60min (we'll refine after reading the body); quick-wins: estimated_minutes from the scanner.
• Estimated cost — use this rule of thumb, cheap and transparent:
  • typo, tiny doc fix: ~$0.30
  • i18n, small test add: ~$1.50
  • missing-test for a non-trivial module: ~$3
  • TODO resolution or labeled issue: ~$5–8 depending on scope
  • UI-affecting issue that needs visual verification: +$2 The point isn't precision — it's letting the user pick a ceiling.

Format as markdown so the user can scan quickly:

Discovered candidates in owner/name:

Quick wins (repo scan)
  1. [typo]         Fix "teh" → "the" in docs/intro.md:42           ~5 min  ~$0.30
  2. [missing-test] Add tests for src/utils/parse.ts                 ~30 min ~$1.50
  3. [i18n]         Fill 12 missing keys in locales/zh-CN.json       ~45 min ~$2.00
  ...

Issues (labeled)
  a. #124  Clarify CONTRIBUTING steps for monorepo setup             ~60 min ~$3.00
     labels: documentation · good first issue
  b. #131  Add --json flag to `cli list` command                     ~90 min ~$6.00
     labels: good first issue · help wanted
  ...

Then call AskUserQuestion titled "Pick one" with options: top quick-wins (numbered) + top issues (lettered) + "Other: paste issue # or slug" fallback + "Cancel".

If the user picks "Cancel", stop cleanly. No work, no clones beyond _scratch.

Step 5 — Isolate the workdir

# For issue pick:
bash "$SKILL_DIR/scripts/setup-workspace.sh <ISSUE_NUMBER>"

# For quick-win pick:
bash "$SKILL_DIR/scripts/setup-workspace.sh <SLUG> --title "<short title>"

Capture WORKDIR=..., BRANCH=..., ISSUE_TITLE=... from stdout.

Step 6 — Write the spec

Fill templates/SPEC.template.md → $WORKDIR/.auto-pr/SPEC.md:

• Problem: restate in your own words.
• Acceptance criteria: testable bullets.
• Approach: concrete change plan.
• Files likely touched: from a quick rg/find pass against the target repo.
• Risk / blast radius.
• Test plan: unit + integration + visual.

For quick-win picks, the spec can be minimal (1–2 acceptance criteria). Don't over-invest for a typo fix.

Step 7 — Generate TODO breakdown + mirror to TaskCreate

Fill templates/TODO.template.md → $WORKDIR/.auto-pr/TODO.md, then create one TaskCreate entry per atomic todo. Prefer failing test → minimal implementation → refactor triples. Mark each TaskUpdate in_progress before starting, completed when dev-loop green.