Claude Open Source Contributor

A Claude Code plugin that standardizes the open-source contribution workflow — from finding a genuine unaddressed bug to shipping a clean PR, with a traceable local log.

Most open-source contributions fail silently: you pick the wrong issue, can't reproduce it, or produce a PR that reads like it was generated by a tool. This plugin enforces a disciplined workflow with iron laws at every step — root cause before fix, failing test before code, human-readable PR.

Installation

You can install this plugin either directly within Claude Code or via your standard terminal.

1. Inside Claude Code (Recommended)

/plugin marketplace add https://github.com/ordinary9843/claude-open-source-contributor.git
/plugin install open-source-contributor@claude-open-source-contributor

2. Via Standard Terminal

claude plugin marketplace add https://github.com/ordinary9843/claude-open-source-contributor.git
claude plugin install open-source-contributor@claude-open-source-contributor

Restart Claude Code after installation to load the plugin.

How It Works

Four skills cover the full contribution lifecycle. Run them in sequence or jump in at any step:

/open-source-contributor:hunt       →  find a valid issue
/open-source-contributor:fix        →  reproduce, test, fix, verify
/open-source-contributor:contribute →  commit, push, open PR, log
/open-source-contributor:revise     →  address PR review feedback and reply

hunt — Find a Valid Issue

Searches GitHub for genuine, fixable bugs in active repositories. Reads the full issue thread (not just the title) to confirm the bug is real, uncontested, and has no existing PR or active contributor. Presents 3–5 ranked candidates for you to choose from.

Hard filters: ≥ 5,000 stars · last commit within 6 months · open issues · not a fork · not an unscoped monorepo

Disqualified automatically: won't fix / by design / duplicate labels · closed-as-invalid · active contributor · rejected or pending PR · feature requests · docs-only issues

fix — Reproduce, Debug, and Fix

Clones the repo, creates a fix branch, establishes root cause, writes a failing test (observes the red state), implements the minimal fix, and runs the full test suite and linter. Writes a partial log entry when all checks pass.

Iron Laws:

1. No fix without confirmed root cause — "The bug occurs because [code] [does wrong] when [condition]."
2. No fix code without a failing test first — write, run, observe red, then fix.
3. No completion claim without fresh verification evidence — show the full output.

contribute — Commit, Push, Open PR

Commits with your git config as the sole author (no Co-Authored-By, no AI references), forks the repo if needed, pushes the fix branch, opens a PR with a plain-English description, and updates the contribution log with the real PR URL.

Iron Laws:

1. No PR without explicit user confirmation — ask before every git operation.
2. Commit author = user's git config only — the commit must be indistinguishable from any human contributor.
3. Write the log after the PR is opened — if log write fails, report it; never roll back the PR.

revise — Address PR Review Feedback

Reads all maintainer review comments on an open PR, classifies each as actionable or noise, proposes concrete changes with reasoning, and — after you implement them — commits, pushes, and posts a plain-English reply. Repeats as many times as the review cycle requires.

Iron Laws:

1. No action without verifying you own the PR — author must match authenticated gh user.
2. No commit without user confirmation — show drafts for both commit message and PR reply before executing.
3. No AI markers in output — commit messages and PR replies must read as a human developer wrote them. No emoji, no bullet summaries, no AI-sounding phrasing.

Usage Examples

Full workflow

/open-source-contributor:hunt

Claude searches and presents 3–5 ranked candidates. You select one.

/open-source-contributor:fix

Claude clones, reproduces, tests, fixes, and verifies.

/open-source-contributor:contribute

Claude commits, pushes, and opens the PR.

Jump directly to fix

If you already know the issue:

/open-source-contributor:fix https://github.com/owner/repo/issues/123

Jump directly to contribute

If you have already fixed a bug locally:

/open-source-contributor:contribute

Claude verifies tests pass before doing anything.

Address a maintainer review

After a maintainer requests changes on your open PR:

/open-source-contributor:revise https://github.com/owner/repo/pull/123

Claude reads the review, filters bot noise, proposes changes, and handles commit + push + reply once you implement the changes.

Contribution Log

Your contribution history is stored at ~/.claude/open-source-contributor/log.json and managed by scripts/log.sh. The file is created automatically on first use.

[
  {
    "repo": "sinonjs/sinon",
    "issue": "https://github.com/sinonjs/sinon/issues/2656",
    "pr": "https://github.com/sinonjs/sinon/pull/2682",
    "description": "last behavior setter silently overridden by invoke priority order in invoke()",
    "date": "2026-03-25"
  }
]

Field	Description
repo	owner/name
issue	Full issue URL
pr	Full PR URL, or null if fix is complete but PR not yet submitted
description	One-sentence summary of exactly what was fixed
date	ISO 8601 date (YYYY-MM-DD)

hunt and fix both check this log before proceeding — no duplicate work.

Plugin Architecture

claude-open-source-contributor/
├── .claude-plugin/
│   ├── plugin.json              # Plugin manifest
│   └── marketplace.json         # Marketplace definition
├── skills/
│   ├── hunt/
│   │   ├── SKILL.md             # Find a valid issue to fix
│   │   └── examples/
│   │       └── candidate-output.md   # Reference output format
│   ├── fix/
│   │   ├── SKILL.md             # Reproduce, debug, and fix
│   │   └── examples/
│   │       └── fix-session.md        # Complete worked example (sinon #2656)
│   ├── contribute/
│   │   ├── SKILL.md             # Commit, push, open PR
│   │   └── examples/
│   │       └── pr-body.md            # PR body reference with tone examples
│   └── revise/
│       ├── SKILL.md             # Address PR review feedback
│       └── examples/
│           └── review-session.md     # Complete review session example
├── scripts/
│   ├── log.sh                   # jq-based log management (check-issue, append, update-pr, list, pending)
│   └── check-access.sh          # Verify gh CLI is authenticated; print username
├── hooks/
│   ├── hooks.json               # SessionStart hook configuration
│   └── session-start.sh         # Remind user of pending (pr: null) contributions
├── LICENSE
└── README.md

Requirements & Troubleshooting

Prerequisites

• Claude Code CLI — installed and running
• GitHub CLI — installed and authenticated (gh auth login)
• jq — required by scripts/log.sh

brew install gh jq
gh auth login

gh authentication is required. All four skills use gh exclusively. There is no WebFetch fallback.

Common Issues

1. "gh CLI is not authenticated"

Run gh auth login and follow the prompts. All four skills call scripts/check-access.sh at startup and will stop immediately if auth fails.

2. Scripts not executable

chmod +x scripts/log.sh scripts/check-access.sh hooks/session-start.sh

3. jq not found

brew install jq

4. Session-start reminder not firing

Verify hooks/hooks.json is present and hook scripts are executable. Run claude plugin validate . to check for errors.

Contributing

1. Clone this repository
2. Add the marketplace locally: claude plugin marketplace add .
3. Install the local plugin: claude plugin install open-source-contributor@claude-open-source-contributor
4. Run the audit to establish a baseline: /code-auditor:review .
5. Submit a PR and include the review score in the description

License

MIT — see LICENSE