diff --git a/README.md b/README.md index 8677925..4c9a7a1 100644 --- a/README.md +++ b/README.md @@ -1,231 +1,3 @@ [English](./README.md) · [简体中文](./README.zh-CN.md) -# auto-github-contributor - -![auto-github-contributor](./assets/cover_en.png) - -A Claude Code skill + slash command that takes any GitHub repo and drives a full OSS contribution pipeline end-to-end: discover a quick-win candidate (labeled issues + repo scan), run a TDD dev-loop until lint/typecheck/tests all pass, then open a PR via `gh` and print the URL. - -One slash command, full pipeline, any repo. - ---- - -## Overview - -When you invoke `/auto-contribute` inside Claude Code, the skill runs an 11-step interactive playbook: - -1. **Prereqs** — verify `gh`, `git`, `jq` are installed and `gh auth status` is green. -2. **Target repo** — accept `owner/name` or a GitHub URL (or ask interactively). -3. **Discover candidates in parallel**: - - Labeled issues (`good first issue`, `help wanted`, `documentation`, …) - - Repo-scan quick wins: typos, missing tests, i18n gaps, actionable TODOs -4. **Ranked picklist** with estimated time + LLM cost per item. -5. **Wait for explicit user confirmation** before touching anything. -6. **Isolate** a workdir + feature branch under `$AGC_WORK_ROOT`. -7. **Write SPEC.md + TODO.md** from templates. -8. **TDD dev-loop** per todo (red → green → refactor), capped at 20 iterations. -9. **Final verification**: clean install + lint + typecheck + tests + build. -10. **Commit, push, open PR** via `gh pr create`. Prefers `TARGET_FORK` over upstream. -11. **Print the PR URL** on its own line. - -Safety rails: never force-push, never commit to `main`/`master`/`develop`, never `rm -rf` outside `$AGC_WORK_ROOT`, never post to external systems unasked. - -## Requirements - -- `gh` (GitHub CLI) — authenticated (`gh auth login`, `repo` scope) -- `git` -- `jq` -- Claude Code - -Optional but nice to have: - -- `rg` (ripgrep) — the scanner falls back to `grep` when absent -- `pnpm` / `yarn` / `npm` / `bun` — autodetected from the target repo's lockfile -- `python3` — used by `create-pr.sh` to render the PR body template - -## Installation - -This repo ships the slash command (`commands/auto-contribute.md`) and the skill (`skills/auto-github-contributor/`) as plain files — no plugin manifest, no marketplace registration. Drop them into Claude Code's user or project directory and they're live. - -**A. User-level (recommended — available in every project)** - -```bash -git clone https://github.com/nexu-io/auto-github-contributor.git /tmp/auto-github-contributor -mkdir -p ~/.claude/commands ~/.claude/skills -cp /tmp/auto-github-contributor/commands/auto-contribute.md ~/.claude/commands/ -cp -R /tmp/auto-github-contributor/skills/auto-github-contributor ~/.claude/skills/ -``` - -Restart Claude Code. `/auto-contribute` appears as a slash command, and Claude can also invoke the `auto-github-contributor` skill by name. - -**B. Project-level (scoped to one repo)** - -From the target repo's root: - -```bash -git clone https://github.com/nexu-io/auto-github-contributor.git /tmp/auto-github-contributor -mkdir -p .claude/commands .claude/skills -cp /tmp/auto-github-contributor/commands/auto-contribute.md .claude/commands/ -cp -R /tmp/auto-github-contributor/skills/auto-github-contributor .claude/skills/ -``` - -The command and skill are then available only inside that project. - -**C. Skill-only (no slash command)** - -If you don't want the `/auto-contribute` command — just the skill — drop `skills/auto-github-contributor/` into `~/.claude/skills/` (or `.claude/skills/`) alone. Invoke it by asking Claude to "auto-contribute to ``" or similar; the description in `SKILL.md` handles trigger words. - -## Usage - -```text -/auto-contribute # skill will ask for the repo -/auto-contribute cli/cli # owner/name form -/auto-contribute https://github.com/cli/cli # URL form -``` - -Override defaults via env vars before launching Claude Code (or export them in your shell profile): - -| Variable | Default | Purpose | -|---|---|---| -| `TARGET_REPO` | _(prompted)_ | `owner/name` of the upstream | -| `TARGET_FORK` | _(empty → push to origin)_ | Where to push the feature branch | -| `AGC_BASE_BRANCH` | `main` | Base branch for the PR | -| `AGC_WORK_ROOT` | `$HOME/auto-gh-contrib-work` | Where workdirs get cloned | -| `AGC_LABELS` | `good first issue,help wanted,documentation,good-first-issue` | Issue labels to search | -| `AGC_ISSUE_LIMIT` | `30` | Max issues per label | -| `AGC_INSTALL_CMD` / `AGC_LINT_CMD` / `AGC_TYPECHECK_CMD` / `AGC_TEST_CMD` / `AGC_BUILD_CMD` | pnpm-flavored | Fallback dev-loop commands (overridden by lockfile detection) | -| `AGC_DEV_URL` | `http://localhost:5173` | URL for browser-verify stub | - -## How to test - -The skill has three testable layers. Start with Layer 1 — it's cheap, deterministic, and covers most of the real surface area. - -### Layer 1 — Script smoke tests (read-only, safe) - -All scripts live in `skills/auto-github-contributor/scripts/` and emit `KEY=VAL` lines or JSON. You can drive each one directly. - -```bash -SKILL_DIR=skills/auto-github-contributor/scripts - -# 1. Prerequisites -bash "$SKILL_DIR/check-prereqs.sh" -# expect: ✓ gh / ✓ git / ✓ jq / ✓ gh authed as ; exit 0 - -# 2. Issue discovery against a real repo -TARGET_REPO=cli/cli AGC_ISSUE_LIMIT=3 bash "$SKILL_DIR/fetch-issues.sh" \ - | jq '.[] | {number, title, score, labels}' -# expect: ranked array of open issues matching the configured labels - -# 3. Quick-win scanner against any clone -SCRATCH=/tmp/agc-smoke && rm -rf "$SCRATCH" \ - && git clone --depth 1 https://github.com/expressjs/express.git "$SCRATCH" -bash "$SKILL_DIR/scan-quick-wins.sh" --workdir "$SCRATCH" --max 20 \ - | jq 'group_by(.kind) | map({kind: .[0].kind, count: length})' -# expect: an array with some of {typo, missing-test, i18n, todo} - -# 4. Parse-check the scripts that mutate state -bash -n "$SKILL_DIR/setup-workspace.sh" -bash -n "$SKILL_DIR/dev-loop-check.sh" -bash -n "$SKILL_DIR/create-pr.sh" -bash -n "$SKILL_DIR/browser-verify.sh" -``` - -### Layer 2 — Slash command + skill loading - -In a Claude Code session at the repo root, type `/auto-contribute` and verify: - -- the slash command autocompletes (proves `commands/auto-contribute.md` is registered), -- Claude immediately invokes the `auto-github-contributor` skill, -- it runs `check-prereqs.sh` first, -- it asks for the target repo via `AskUserQuestion`, -- it fetches issues and scans quick-wins in parallel, -- it renders a picklist with time/cost estimates and **stops for confirmation**. - -You can cancel at the picklist — no workdir is created beyond a `_scratch` shallow clone. - -### Layer 3 — End-to-end on a sandbox repo - -Create a throwaway repo you own (e.g. `your-handle/agc-sandbox`) with a known quick-win seeded — for instance, write `# Teh setup guide` (note `Teh`) in `README.md`. Then: - -```text -/auto-contribute your-handle/agc-sandbox -``` - -Pick the typo from the list, approve, and let the skill drive through to a real PR. Close the PR once you've verified the flow. - -Tip: set `TARGET_FORK=your-handle/agc-sandbox` so it pushes to the same repo (branch) instead of prompting about origin. - -## How it works - -``` -commands/auto-contribute.md # /auto-contribute slash command (thin wrapper) -skills/auto-github-contributor/ - SKILL.md # orchestration playbook Claude reads - scripts/ - config.sh # shared env + helpers - check-prereqs.sh # gh/git/jq + auth check - fetch-issues.sh # label-based issue discovery + ranking - scan-quick-wins.sh # typo / missing-test / i18n / TODO scanner - setup-workspace.sh # clone + feature branch - dev-loop-check.sh # red/green/final phases, lockfile-aware - browser-verify.sh # visual-verification stub - create-pr.sh # commit, push, open PR, render body - templates/ - SPEC.template.md # problem / acceptance / approach / risk - TODO.template.md # atomic todos mirrored to TaskCreate - PR-BODY.template.md # rendered into .auto-pr/PR-BODY.md -``` - -The skill file (`SKILL.md`) is the contract Claude follows. The scripts do the real work; Claude only orchestrates, reads their output, and makes decisions at the branching points. - -## How to contribute - -Contributions welcome. The most valuable additions right now: - -1. **New quick-win kinds** — extend `scan-quick-wins.sh`. Good targets: - - broken markdown links - - unused exports (ts-prune-style) - - missing JSDoc on public APIs - - outdated dependency pins in a package.json section -2. **Browser-verify backend** — `browser-verify.sh` is a deliberate stub. Wire up a Playwright / Puppeteer / chrome-devtools MCP backend so UI changes get screenshotted before the PR. -3. **Language/framework dev-loops** — `dev-loop-check.sh` currently detects JS package managers. Add Python (`uv`/`poetry`/`pip`), Go, Rust, etc. -4. **Cost estimator** — the picklist cost numbers are hand-waved rules of thumb. A smarter estimator (token-weighted file size × action kind) would help users pick more confidently. - -### Guidelines - -- **Scripts emit machine-readable output.** Stdout is `KEY=VAL` lines or JSON. Human logs go to stderr via `agc::log` / `agc::err`. Don't mix them. -- **No silent stubs.** If a feature isn't wired up yet, print `stub: ` so the PR body can surface the caveat. -- **Safety rails stay on.** Never force-push, never commit to `main`/`master`/`develop`, never `rm -rf` outside `$AGC_WORK_ROOT`. If you add a new mutation path, add the guard too. -- **Config via env vars.** New tunables go into `config.sh` with a sensible default and an entry in the README table above. -- **Shell style.** `set -euo pipefail` (relax only where explicitly justified, as in `scan-quick-wins.sh`). Prefer `$(...)` over backticks. Quote expansions. - -### Local dev loop - -```bash -# parse-check all scripts -for f in skills/auto-github-contributor/scripts/*.sh; do bash -n "$f" || exit 1; done - -# smoke the scanner against a local clone -bash skills/auto-github-contributor/scripts/scan-quick-wins.sh --workdir /path/to/some/repo | jq . - -# run shellcheck if you have it installed -shellcheck skills/auto-github-contributor/scripts/*.sh -``` - -### Filing issues - -- Include the Claude Code version, OS, and `gh --version`. -- Paste the stderr log from the failing script (the `[auto-gh]` lines are the useful ones). -- If the issue is in discovery, include `TARGET_REPO` — different repos expose very different label sets. - -### PR checklist - -- [ ] `bash -n` passes for every touched script -- [ ] Script output still follows the stdout-is-data / stderr-is-log split -- [ ] New env vars documented in `README.md` and defaulted in `config.sh` -- [ ] Safety rails not weakened -- [ ] If you touched `SKILL.md`, re-read it end-to-end — Claude follows it literally - -## License - -MIT — see [LICENSE](LICENSE). +# auto-github-shitter diff --git a/README.zh-CN.md b/README.zh-CN.md index 8433a43..50d451c 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,231 +1,3 @@ [English](./README.md) · [简体中文](./README.zh-CN.md) -# auto-github-contributor - -![auto-github-contributor](./assets/cover_zh.png) - -一套 Claude Code skill + slash 命令:对任意 GitHub 仓库端到端跑通一次开源贡献流程 —— 自动发现 quick-win 候选(带标签的 issue + 仓库扫描),按 TDD 走 red/green/refactor 直到 lint/typecheck/tests 全绿,然后通过 `gh` 开 PR 并输出链接。 - -一条 slash 命令,覆盖完整流水线,适用于任何仓库。 - ---- - -## 简介 - -在 Claude Code 中调用 `/auto-contribute` 后,skill 会按 11 步交互式 playbook 执行: - -1. **环境检查** —— 确认 `gh` / `git` / `jq` 已安装,`gh auth status` 正常。 -2. **锁定目标仓库** —— 接受 `owner/name` 或 GitHub URL(缺参时交互式询问)。 -3. **并行发现候选**: - - 带标签的 issue(`good first issue`、`help wanted`、`documentation` 等) - - 仓库扫描的 quick-win:拼写错误、缺测试、i18n 缺 key、可执行的 TODO -4. **排序挑选列表**,每一项都带时间和 LLM 成本估算。 -5. **等待用户明确确认** 后才动手改代码。 -6. **隔离工作区**:在 `$AGC_WORK_ROOT` 下建独立目录和功能分支。 -7. **写 SPEC.md + TODO.md**,用模板生成。 -8. **TDD 开发循环**(red → green → refactor),每个 todo 最多 20 轮。 -9. **最终验证**:clean install + lint + typecheck + tests + build。 -10. **提交、推送、开 PR**(`gh pr create`),优先推到 `TARGET_FORK`,否则推到 upstream。 -11. **单独一行输出 PR URL**,方便用户点击。 - -安全约束:绝不 force-push;绝不提交到 `main`/`master`/`develop`;绝不在 `$AGC_WORK_ROOT` 外 `rm -rf`;未经授权绝不向外部系统(Slack、邮件等)发消息。 - -## 环境要求 - -- `gh`(GitHub CLI)—— 已登录(`gh auth login`,需要 `repo` scope) -- `git` -- `jq` -- Claude Code - -可选但推荐: - -- `rg`(ripgrep)—— 没有时扫描脚本会回退到 `grep` -- `pnpm` / `yarn` / `npm` / `bun` —— 根据目标仓库的 lockfile 自动识别 -- `python3` —— `create-pr.sh` 渲染 PR 正文模板时用到 - -## 安装 - -本仓库只包含 slash 命令(`commands/auto-contribute.md`)和 skill(`skills/auto-github-contributor/`),都是普通文件 —— 不需要 plugin manifest,也不需要注册 marketplace。拷到 Claude Code 的 user 或 project 目录下即可生效。 - -**A. 用户级安装(推荐,所有项目通用)** - -```bash -git clone https://github.com/nexu-io/auto-github-contributor.git /tmp/auto-github-contributor -mkdir -p ~/.claude/commands ~/.claude/skills -cp /tmp/auto-github-contributor/commands/auto-contribute.md ~/.claude/commands/ -cp -R /tmp/auto-github-contributor/skills/auto-github-contributor ~/.claude/skills/ -``` - -重启 Claude Code,`/auto-contribute` 就会出现在 slash 命令列表里,`auto-github-contributor` skill 也能被 Claude 按名字调用。 - -**B. 项目级安装(只在单个仓库生效)** - -在目标项目根目录下: - -```bash -git clone https://github.com/nexu-io/auto-github-contributor.git /tmp/auto-github-contributor -mkdir -p .claude/commands .claude/skills -cp /tmp/auto-github-contributor/commands/auto-contribute.md .claude/commands/ -cp -R /tmp/auto-github-contributor/skills/auto-github-contributor .claude/skills/ -``` - -这样命令和 skill 只在这个项目里可用。 - -**C. 只要 skill、不要 slash 命令** - -只把 `skills/auto-github-contributor/` 拷到 `~/.claude/skills/`(或 `.claude/skills/`)即可。之后用自然语言触发(例如 "auto-contribute to ``")——`SKILL.md` 里的 description 字段会匹配关键词。 - -## 使用 - -```text -/auto-contribute # 不带参数,会交互式问仓库 -/auto-contribute cli/cli # owner/name 形式 -/auto-contribute https://github.com/cli/cli # URL 形式 -``` - -在启动 Claude Code 前通过环境变量覆盖默认值(也可以放进 shell profile): - -| 变量 | 默认值 | 用途 | -|---|---|---| -| `TARGET_REPO` | _(运行时询问)_ | upstream 的 `owner/name` | -| `TARGET_FORK` | _(空即推到 origin)_ | 功能分支推往哪个 fork | -| `AGC_BASE_BRANCH` | `main` | PR 的 base 分支 | -| `AGC_WORK_ROOT` | `$HOME/auto-gh-contrib-work` | 克隆工作区根目录 | -| `AGC_LABELS` | `good first issue,help wanted,documentation,good-first-issue` | 搜索 issue 用的标签 | -| `AGC_ISSUE_LIMIT` | `30` | 每个标签最多拉多少条 | -| `AGC_INSTALL_CMD` / `AGC_LINT_CMD` / `AGC_TYPECHECK_CMD` / `AGC_TEST_CMD` / `AGC_BUILD_CMD` | pnpm 风格 | dev-loop 兜底命令(lockfile 识别会覆盖它们) | -| `AGC_DEV_URL` | `http://localhost:5173` | 浏览器可视化校验的 URL | - -## 如何测试 - -整个 skill 可以分三层来测。建议从 Layer 1 起 —— 成本最低、确定性最强,覆盖真正容易出问题的代码路径。 - -### Layer 1 —— 脚本冒烟测试(只读、安全) - -所有脚本都在 `skills/auto-github-contributor/scripts/` 下,输出都是 `KEY=VAL` 或 JSON,可独立调用: - -```bash -SKILL_DIR=skills/auto-github-contributor/scripts - -# 1. 环境检查 -bash "$SKILL_DIR/check-prereqs.sh" -# 预期: ✓ gh / ✓ git / ✓ jq / ✓ gh authed as <你的用户名>;exit 0 - -# 2. 用真实仓库跑 issue 发现 -TARGET_REPO=cli/cli AGC_ISSUE_LIMIT=3 bash "$SKILL_DIR/fetch-issues.sh" \ - | jq '.[] | {number, title, score, labels}' -# 预期: 按 score 排序的 open issue 数组 - -# 3. 对任意克隆跑 quick-win 扫描 -SCRATCH=/tmp/agc-smoke && rm -rf "$SCRATCH" \ - && git clone --depth 1 https://github.com/expressjs/express.git "$SCRATCH" -bash "$SKILL_DIR/scan-quick-wins.sh" --workdir "$SCRATCH" --max 20 \ - | jq 'group_by(.kind) | map({kind: .[0].kind, count: length})' -# 预期: 数组里包含 {typo, missing-test, i18n, todo} 中的若干种 - -# 4. 对会改状态的脚本做语法检查 -bash -n "$SKILL_DIR/setup-workspace.sh" -bash -n "$SKILL_DIR/dev-loop-check.sh" -bash -n "$SKILL_DIR/create-pr.sh" -bash -n "$SKILL_DIR/browser-verify.sh" -``` - -### Layer 2 —— slash 命令 + skill 装载 - -在本仓库根目录启动 Claude Code,输入 `/auto-contribute`,检查: - -- slash 命令能自动补全(说明 `commands/auto-contribute.md` 被识别) -- Claude 立即通过 Skill 工具加载 `auto-github-contributor` -- 先跑 `check-prereqs.sh` -- 通过 `AskUserQuestion` 交互式问目标仓库 -- 并行拉 issue 与扫描 quick-win -- 展示带时间/成本估算的挑选列表,**然后停下来等确认** - -在挑选列表处直接取消即可,不会产生 `_scratch` 之外的任何副作用。 - -### Layer 3 —— 真实端到端 - -建一个你自己的实验仓库(例如 `your-handle/agc-sandbox`),刻意埋一个 quick-win —— 比如在 `README.md` 里写 `# Teh setup guide`(注意 `Teh` 是错的)。然后: - -```text -/auto-contribute your-handle/agc-sandbox -``` - -从挑选列表里选中这个 typo、同意继续,让 skill 走完完整流水线开出一个真 PR。验证完关掉 PR 就行。 - -小技巧:同时设 `TARGET_FORK=your-handle/agc-sandbox`,这样会直接推到同仓库的分支,不会提示推 origin 的确认。 - -## 工作原理 - -``` -commands/auto-contribute.md # /auto-contribute slash 命令(薄壳) -skills/auto-github-contributor/ - SKILL.md # Claude 要读的 orchestration playbook - scripts/ - config.sh # 共享环境变量 + 工具函数 - check-prereqs.sh # gh/git/jq + 登录态检查 - fetch-issues.sh # 按标签发现 + 排序 issue - scan-quick-wins.sh # typo / 缺测试 / i18n / TODO 扫描 - setup-workspace.sh # 克隆 + 创建功能分支 - dev-loop-check.sh # red/green/final 阶段,识别 lockfile - browser-verify.sh # 浏览器可视化验证(stub) - create-pr.sh # commit/push/开 PR/渲染正文 - templates/ - SPEC.template.md # 问题/验收标准/方案/风险 - TODO.template.md # 会镜像到 TaskCreate 的原子 todo - PR-BODY.template.md # 渲染到 .auto-pr/PR-BODY.md -``` - -`SKILL.md` 是 Claude 要遵守的契约;真正干活的是 scripts/。Claude 只做编排 —— 读脚本输出、在分支点做决定。 - -## 如何贡献 - -欢迎 PR。目前最有价值的方向: - -1. **新增 quick-win 类型** —— 扩展 `scan-quick-wins.sh`,候选: - - markdown 死链检查 - - 未使用的 export(ts-prune 风格) - - 缺 JSDoc 的 public API - - package.json 里过时的依赖版本 pin -2. **浏览器验证后端** —— `browser-verify.sh` 目前是有意保留的 stub。接上 Playwright / Puppeteer / chrome-devtools MCP 后端,让 UI 改动在开 PR 前先截一张图。 -3. **多语言/框架 dev-loop** —— `dev-loop-check.sh` 当前只识别 JS 包管理器。欢迎加 Python(`uv` / `poetry` / `pip`)、Go、Rust 等。 -4. **成本估算器** —— 挑选列表里的成本数字目前只是经验拍的。更靠谱的算法(按 token 加权的文件大小 × 动作类型)能帮用户更有信心地选。 - -### 贡献约定 - -- **脚本输出是机器可读的。** stdout 只写 `KEY=VAL` 或 JSON;人类日志走 stderr,通过 `agc::log` / `agc::err`。别混。 -- **不允许静默 stub。** 新功能没接完就打印 `stub: <原因>`,让 PR 正文能把 caveat 带出来。 -- **安全约束保持开启。** 绝不 force-push、绝不提交到 `main`/`master`/`develop`、绝不在 `$AGC_WORK_ROOT` 外 `rm -rf`。新加会改状态的代码路径必须顺手加 guard。 -- **配置通过环境变量。** 新的可调项统一进 `config.sh`,给个合理默认值,并在本文件的环境变量表里补上一行。 -- **Shell 风格。** 默认 `set -euo pipefail`(只在有明确理由时放宽,如 `scan-quick-wins.sh`)。用 `$(...)` 代替反引号,注意对扩展加引号。 - -### 本地开发循环 - -```bash -# 对全部脚本做语法检查 -for f in skills/auto-github-contributor/scripts/*.sh; do bash -n "$f" || exit 1; done - -# 对本地任意克隆跑扫描器 -bash skills/auto-github-contributor/scripts/scan-quick-wins.sh --workdir /path/to/some/repo | jq . - -# 装了 shellcheck 的话 -shellcheck skills/auto-github-contributor/scripts/*.sh -``` - -### 提 issue - -- 附上 Claude Code 版本、操作系统、`gh --version`。 -- 粘出失败脚本的 stderr 日志(特别是 `[auto-gh]` 开头的那些行,信息量最大)。 -- 如果是发现阶段的问题,把 `TARGET_REPO` 写进来 —— 不同仓库的标签集差异很大。 - -### PR checklist - -- [ ] 所有改动过的脚本 `bash -n` 通过 -- [ ] 输出仍然遵守「stdout 是数据 / stderr 是日志」的分工 -- [ ] 新环境变量在 `README.md` 里有文档、在 `config.sh` 里有默认值 -- [ ] 安全约束没有被削弱 -- [ ] 改过 `SKILL.md` 的话,从头到尾读一遍 —— Claude 是严格按它执行的 - -## 许可证 - -MIT —— 详见 [LICENSE](LICENSE)。 +# 自动拉屎贡献者 diff --git a/assets/cover_en.png b/assets/cover_en.png deleted file mode 100644 index ce92852..0000000 Binary files a/assets/cover_en.png and /dev/null differ diff --git a/assets/cover_zh.png b/assets/cover_zh.png deleted file mode 100644 index aee4cc0..0000000 Binary files a/assets/cover_zh.png and /dev/null differ diff --git a/commands/auto-contribute.md b/commands/auto-contribute.md deleted file mode 100644 index 7c558d9..0000000 --- a/commands/auto-contribute.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: Find a quick-win contribution in a GitHub repo and open a PR end-to-end. -argument-hint: "[repo-url-or-owner/name]" ---- - -You are entering the **auto-github-contributor** flow. - -User input (may be empty): `$ARGUMENTS` - -## What to do right now - -1. **Load the skill** by invoking the `auto-github-contributor` skill via the Skill tool. The skill owns the full execution playbook — do not reimplement it inline. - -2. **Pass the user input forward**: - - If `$ARGUMENTS` looks like a repo (`https://github.com//` or `/`), set it as `TARGET_REPO` and skip the "ask for repo" step in the skill. - - Otherwise, the skill will interactively ask for the repo URL via `AskUserQuestion`. - -3. **Honor the interactive contract**: - - Always run the prerequisite check first (`gh` installed + authed). If it fails, surface the install/auth hint and stop — do not try workarounds. - - Always present the discovered candidates (labeled issues + repo-scan quick wins) with estimated time/cost, and **wait for explicit user confirmation** before starting the dev-loop. - - At the end, print the PR URL on its own line so the user can click through. - -Begin by invoking the skill now. diff --git a/skills/auto-github-contributor/SKILL.md b/skills/auto-github-contributor/SKILL.md deleted file mode 100644 index 4ecabf7..0000000 --- a/skills/auto-github-contributor/SKILL.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -name: auto-github-contributor -description: Interactively pick a quick-win contribution in any GitHub repo — either a labeled issue ("good first issue", "help wanted", docs) or a repo-scan candidate (typo, missing tests, i18n gap, actionable TODO). Runs a TDD dev-loop, opens a PR via gh, and returns the PR URL. Use when the user wants to auto-contribute to an open-source project end-to-end. Trigger words: auto-contribute, open a PR for me, find a good first issue, contribute to . -allowed-tools: - - Bash - - Read - - Write - - Edit - - AskUserQuestion - - TaskCreate - - TaskUpdate - - WebFetch ---- - -# 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: - -```bash -source "$(dirname "$0")/config.sh" -``` - -Override config via env vars on invocation: - -```bash -TARGET_REPO=owner/name TARGET_FORK=me/name bash