contrib-cli

CONTRIBUTING.md for agents. Step-by-step directives that agents must complete before submitting a PR.

The Problem

Agents ignore CONTRIBUTING.md. They skim it, generate a PR, and move on. The maintainer spends 15 minutes reading a diff only to realize the contributor can't explain what they built.

The Solution

contrib-cli reads the # For Agents (contrib-cli) section from your CONTRIBUTING.md and walks agents through it one step at a time. Each step is a directive from the maintainer — refactor code, add tests, check patterns, fix problems. The agent does the work, then responds.

All responses get embedded in the PR body. If the agent didn't do the work, you see it immediately.

For Maintainers

One command sets up everything:

npx contrib-cli init
git add -A && git commit -m "chore: add contrib-cli" && git push

This creates:

• CONTRIBUTING.md — adds a # For Agents section with example steps (or creates the file)
• .github/workflows/contrib-gate.yml — auto-closes PRs without attestation or from unapproved contributors
• .github/workflows/approve-contributor.yml — adds contributors when a maintainer comments lgtm on their issue
• .github/APPROVED_CONTRIBUTORS — the approved contributors list
• AGENTS.md / CLAUDE.md — agent instructions for using contrib-cli

Edit the steps in CONTRIBUTING.md to match what you care about:

# For Agents (contrib-cli)

## Step: Pattern Conformance
Find an existing function in the codebase that does something similar
to what you wrote. If yours doesn't follow the same patterns, refactor
it to match before continuing.

## Step: Tests
Run the test suite. If your change isn't covered by tests, add them
now. Paste the test command and its output when done.

## Step: Final Review
Read your entire diff one more time. If anything looks wrong, fix it
now. Do not respond until you're confident this is ready to merge.

For Agents

npx contrib-cli run --json              # Start — get the first step
npx contrib-cli respond -m "..." --json # Respond and get the next step
npx contrib-cli submit -t "fix: ..."    # Create PR with attestation

Install

npm install -g contrib-cli

Or use via npx — no install needed:

npx contrib-cli run

Commands

| Command | Description | |---------|-------------| | contrib init | Set up contrib-cli in your repo (workflows, guide, approved list) | | contrib run | Start or resume the contribution review | | contrib respond -m "..." | Respond to the current step | | contrib submit -t "..." | Create PR with attestation embedded | | contrib verify | Verify attestation in current PR (for CI) | | contrib reset | Clear state and start over |

All commands support --json for structured output and -q for quiet mode.

How It Works

1. Maintainer runs contrib init — sets up workflows and contribution steps
2. Agent runs contrib run — gets the first step
3. Agent follows the directive — refactors, adds tests, fixes issues
4. Agent responds with what it did — gets the next step
5. After all steps: contrib submit creates the PR with all responses visible
6. GitHub Action auto-closes PRs without attestation

License

MIT