contribkit

Do not open the pull request until the repository's contribution contract is satisfied.

contribkit checks a repository's contribution rules before an agent or human opens a pull request. It reads explicit repo artifacts (CONTRIBUTING, PR templates, CODEOWNERS, and optional contribkit.yml), compiles them into a deterministic contract, and evaluates the local diff.

This is not contributor-image generation (LizardByte/contribkit), not a contribution-proposal bot (vidiyala99/contribkit), and not a GitHub merge gate (PatchGate).

Live status (2026-08-24): 0 GitHub stars, 0 forks, and no verified external consumer or pilot. 0.1.0-alpha.7 is on GitHub main. The npm alpha dist-tag currently resolves 0.1.0-alpha.6; alpha.7 is prepared in source but still requires npm two-factor verification before publication. Not in the Anthropic community plugin catalog. Not a Claude-for-OSS eligibility claim.

If one preflight run saved you a rejected pull request, star it. That is the only growth signal this repo tracks.

git clone --branch v0.1.0-alpha.7 https://github.com/daichunghy/contribkit.git
cd contribkit
npm ci
npm run verify
node dist/src/cli.js preflight --repo . --base HEAD

A clean clone against HEAD should print contribkit pass. There is no pull request yet, so missing npm test records and empty PR checkboxes are not blockers.

For the first result on another repository, use the first-use walkthrough.

When you have local changes, record tests (opt-in) or the receipt stays blocked until a passing allowlisted command is recorded:

node dist/src/cli.js preflight --repo . --base HEAD --run-tests
node dist/src/cli.js preflight --repo . --base HEAD --body-file /tmp/pr.md --out /tmp/receipt.json
node dist/src/cli.js explain /tmp/receipt.json

Library:

import { compile, evaluate } from "contribkit";

Claude Code plugin (local marketplace, not the Anthropic catalog):

/plugin marketplace add daichunghy/contribkit
/plugin install contribkit@daichunghy

--json prints machine-readable contract or receipt JSON. Preflight exit codes: blocked → 1; pass and needs-human → 0. --repo must be a git clone root, not a nested folder of another repository.

--run-tests is opt-in. It only executes exact allowlisted argv (npm test, npm run test, pnpm test, yarn test, pytest, python -m pytest, cargo test, go test, bun test, deno test, mix test, mvn test). Extra arguments, pipes, &&, and $() are rejected. Default preflight only records commands already supplied; it does not run the target repository.

CONTRIBKIT_ALLOW=1 sets receipt.overridden = true. It does not rewrite tool argv.

What is shipped

• Deterministic compile + evaluate (no LLM, no network in the hot path)
• CLI: compile / preflight / explain / mcp
• Extractors 1–10 (license, PR checkboxes, issue link, CODEOWNERS, size, workflow paths, recorded tests, AI disclosure, DCO, contribkit.yml)
• Golden fixtures under fixtures/repos/
• Claude plugin: .claude-plugin/plugin.json, skills/*, hooks/hooks.json (Bash|PowerShell gh/glab and mcp__.*__create_pull_request)
• MCP stdio: node dist/src/cli.js mcp tools compile_contract, preflight_diff, explain_receipt
• Bundled adapters: python-pytest, node-npm-test, go-test, bun-test, deno-test, elixir-mix, java-maven (advisory command_recorded only unless blockAdapters)
• Adapter authoring guide: docs/ADAPTER_AUTHORING.md

What is not shipped

• Anthropic community plugin catalog listing
• GitHub Action merge gate (that is PatchGate's lane)
• A v0.1.0 stable claim — this tag is alpha

It does not decide whether code is correct, written by AI, or merge-worthy.

Who this is for

• Contributors, and the coding agents acting for them, who want the repository contract satisfied before a pull request is opened.
• Maintainers tired of repeating "read CONTRIBUTING" on first contributions.
• Not a fit if you want a GitHub merge gate — that is PatchGate's lane — or contributor images.

If one preflight run saved you a rejected pull request, star the repository. It helps other contributors find the check.

Release history: CHANGELOG.md.

Security

See SECURITY.md and docs/THREAT_MODEL.md.

License

Apache-2.0. See LICENSE.