Make AI-assisted open-source contributions land cleanly — caught by deterministic gates before they reach maintainers as slop.
A local-only Claude Code skill plus workspace for contributing to open-source projects you don't own. It runs 51 deterministic safety gates over every claim comment, design issue, and pull request, so AI-generated work never reaches an upstream maintainer as low-quality "slop." State is plain markdown — greppable, git-trackable, no database, no cloud calls.
Links: GitHub · Latest release
AI can write a pull request in seconds — and that is exactly the problem. The maintainers who keep open source alive are now drowning in plausible-looking, low-quality AI contributions: PRs that just restate the issue, "fixes" with tests that never actually ran, comments that leak internal or private context, changes aimed at the wrong layer of the system entirely.
Every one of those costs a human maintainer real review time. And the contributor pays too: open-source communities run on trust, and a few sloppy submissions quietly burn a reputation that takes months to earn back. The same tools that made opening a contribution effortless have made receiving one worse.
There is no layer that stops the slop at the source — before it ever lands in a maintainer's inbox.
contributing-clanker sits between an AI assistant and the upstream repository as a gauntlet. Before any claim, design issue, or PR can go out, it runs 51 deterministic checks and blocks anything that fails — with the reason written to an append-only log. Has a fix for this issue already merged? Does the PR description actually match the diff? Is the contributor over-reaching the trust they've earned at this specific repo? Is engagement or maintainer-internal context leaking into a public change? If a check fails, the action does not happen.
It learns each upstream's rules exactly once — CLA, DCO, commit-message format, AI-disclosure policy, review bots, issue templates — into a per-repo "dossier," then enforces them on every future contribution there. A trust ladder ties contribution scope to merges already earned, so a first-timer cannot fire a 900-file umbrella PR at a project that has never seen their work. The whole system is local markdown and shell: no daemon, no database, no cloud — a VP can read the candidate file, and an engineer can grep the gate that blocked them.
| Aspect | Details |
|---|---|
| Who | Developers using AI assistants to contribute to OSS repositories they don't own or maintain |
| What | A Claude Code skill + a 51-gate anti-slop safety harness + a per-repo rules dossier system |
| Where | Runs locally inside Claude Code; all state in ~/.contribute-system/ as markdown + JSONL |
| When | Any time you discover, claim, comment on, or open a PR against an upstream repo |
| Why | It's the only layer that stops AI-slop at the source — before a maintainer ever sees it |
| Layer | Technology | Purpose |
|---|---|---|
| Orchestration | Claude Code skill (SKILL.md + 5 subagents) |
discovery, per-repo research, drafting, test-running |
| Safety gates | 51 Bash scripts, phases A–G | deterministic pre-action checks with logged verdicts |
| Enforcement hook | precheck-hook.sh (PreToolUse) |
intercepts gh calls so nothing bypasses the gates |
| State | Markdown + JSONL | candidate files, per-repo dossiers, append-only event log |
| Integration | gh CLI + jq |
live GitHub state, never a cached API layer |
| Deploy | install.sh → ~/.contribute-system/bin/ + doctor.sh |
runtime mirror of the repo scripts, drift-checked |
- Deterministic, not vibes — 51 shell gates with logged PASS/WARN/BLOCK verdicts, not an LLM saying "looks fine."
- Trust ladder — a contributor's (N+1)th PR scope is governed by their N prior merges at that repo (gates A07 + B13).
- Per-repo dossiers — learns each upstream's rules once (CLA/DCO/commit-format/AI-policy/templates), enforces them every time.
- Local + markdown-only — greppable, git-trackable, survives any tool; no database, no daemon, no cloud calls.
- Anti-slop catalog — 62 enumerated AI-failure modes mapped to concrete gates, so coverage is auditable.
contributing-clanker is a filesystem-only safety system for AI-assisted open-source contribution. The product is a Claude Code skill (/contribute) backed by a workspace repo that holds the skill's source, its spec, and its tests. At runtime, the skill orchestrates five subagents and routes every externally-visible action through transition.sh, which invokes gate-runner.sh over 51 gates grouped into seven phases (A discovery → G infrastructure). Gates are plain Bash; a BLOCK verdict halts the action and is written to an append-only log.jsonl.
What's built is the entire Phase-1 system: 51 gates, 5 subagents, the per-repo dossier builder, the lifecycle state machine, the trust-ladder discipline, and a self-maintaining runtime-mirror deploy with a drift checker. What's scaffolded/deferred is Phase-2 marketplace packaging (epic 25c) and a future Phase-3 MCP service — both intentionally gated behind real dogfood signal.
The technology foundation is deliberately boring: Bash + gh + jq, with markdown and JSONL as the only persistence. There is no database, no server, and no cloud dependency — a design choice that makes the whole system inspectable by hand and recoverable from git.
Biggest risks are modest and tracked: a handful of moderate advisories in the dev-only PDF tooling (not in the shipped surface), and no CI wiring yet (gates run via local pre-commit + bats). Neither touches the contribution-safety path.
| Category | Technology | Version | Purpose |
|---|---|---|---|
| Orchestration | Claude Code skill | SKILL.md v4.0.0 | /contribute entry point + 5 subagents |
| Gates / hooks | Bash | 5.x | 51 deterministic gates + PreToolUse hook |
| GitHub I/O | gh CLI + jq |
latest | live PR/issue state, JSON shaping |
| State | Markdown + JSONL | — | candidates, dossiers, event log |
| Tests | bats + shellcheck | — | 48 unit cases, 5 regression suites |
| Dev tooling | Node (md-to-pdf, puppeteer) |
in tools/ |
PDF rendering (not in shipped surface) |
Claude Code session ──/contribute──┐
▼
┌─────────────────────────┐ spawns ┌──────────────────────────────┐
│ SKILL.md (orchestrator) │──────────→ │ subagents: scout · researcher │
└────────────┬─────────────┘ │ draft-writer · test-runner · │
│ every external action │ repo-analyzer │
▼ └──────────────────────────────┘
gh call ──intercept──→ ┌────────────────────┐ runs ┌────────────────────────────────┐
(precheck-hook.sh) │ transition.sh │─────────→ │ gate-runner.sh → 51 gates A–G │
└─────────┬──────────┘ └────────────────────────────────┘
│ verdict: PASS / WARN / BLOCK (logged)
▼
┌──────────────────────────────────────────────────────────┐
│ ~/.contribute-system/ (markdown state, NOT in repo) │
│ candidates/ research/ (dossiers) log.jsonl profile │
└──────────────────────────────────────────────────────────┘
│ only after gates PASS + human approval
▼
upstream GitHub repo
| Decision | Chosen | Over | Why | Revisit When |
|---|---|---|---|---|
| State store | Markdown + JSONL | SQLite / DB | greppable, git-trackable, no daemon, survives any tool | candidate volume hits many thousands |
| Topology | Filesystem-only | MCP service | zero infra, runs in any Claude Code session | multi-user / cross-machine coordination needed |
| Gate logic | Deterministic Bash | LLM-judge | reproducible, logged, zero per-check token cost | a check needs genuine semantic judgment |
| Runtime deploy | Symlinked mirror | packaged copy | edits go live instantly, zero drift | distributing to non-dev users (then copy mode) |
A prior SQLite tracker (32 tables) and a Next.js dashboard were deleted in 2026-04 because they were never used — the markdown-only rewrite is the deliberate replacement. The filesystem-only choice trades away cross-machine coordination for inspectability and zero ops.
contributing-clanker/
├── skills/contribute/ # the skill — single source of truth
│ ├── SKILL.md # /contribute orchestrator
│ ├── agents/ # 5 subagents
│ ├── scripts/ # 17 top-level + gates/ (51) + gates/lib/
│ ├── references/ # candidate / dossier / workflow specs
│ └── assets/ # 3 generic templates
├── bin/install.sh # deploys skill + runtime mirror, with doctor smoke-check
├── 000-docs/ # spec (10 epics) + release AARs
├── tests/ # bats unit + L4 regression
├── features/ # Gherkin BDD acceptance
└── <upstream clones>/ # where contributions land
~/.contribute-system/ # runtime state (candidates, dossiers, log) — NOT in repo
| Capability | Command | Notes |
|---|---|---|
| Install skill + runtime mirror | bin/install.sh --symlink |
dev: ~/.contribute-system/bin/ → repo scripts, zero drift |
| Verify runtime mirror | scripts/doctor.sh |
exit 1 on drift / missing |
| Gate-checked transition | transition.sh <action> <candidate> |
runs the A–G gates for that action |
| Unit tests | bats tests/unit/gates/ |
48 cases |
| Regression suites | scripts/test-*.sh |
5 suites (known-traps, override-audit, plug-in, stale-dossier, scout-refresh) |
| Lint | scripts/lint-bash.sh |
shellcheck (--severity=warning) |
- v0.2.0 released (2026-06-16); 51 gates across phases A=8 / B=10 / C=20 / D=3 / E=2 / F=3 / G=5
- 5 subagents, per-repo dossier system, trust-ladder discipline (gates A07 + B13)
- Self-maintaining runtime-mirror deploy +
doctor.shdrift checker - 48 bats unit cases + 5 regression suites green; real upstream merges landed (e.g. kobiton/automate: 9 merged)
- Medium — 3 moderate
js-yamladvisories in the dev-onlytools/PDF utility; breaking fix deferred (trackedi4y.5). Not in the shipped contribution-safety surface. - Low — no CI configured yet; gates run via local pre-commit + bats. CI wiring rides with Phase-2 packaging.
- Low — Phase-2 marketplace packaging (epic 25c) deferred pending dogfood signal.
- Repo: https://github.com/jeremylongshore/contributing-clanker
- CI: not configured (local pre-commit + bats
tests/unit/gates/) - License: MIT
- Last Release: v0.2.0 (2026-06-16)
- Test Coverage: 48 bats unit cases + 5 regression suites (passing)
Minor release. 43 days of dogfood-driven hardening since v0.1.2: a trust-ladder discipline, ten new gates (C20–C27 + A07/B13), a self-maintaining runtime-mirror deploy with a drift checker, surgical scout targeting, and a batch of researcher-build correctness fixes — all surfaced by real contribution round-trips. No breaking changes.
- Added: trust-ladder gates A07/B13; content-fidelity gates C20–C27;
/contribute <url>onboarding;scout --repossurgical mode + fix-locality drop; researcher smart-refresh +semantic.ymldetection (activates gate C02); runtime-mirror deploy +doctor.sh. - Fixed:
ai_disclosure_requiredfalse-positives; emptypolicy_filesset -ubug; precheck-hook three-path lookup; doctor symlink resolution; test/agent realignment with the builder interface. - Security:
npm audit fixintools/(ip-address XSS, ws memory disclosure).
Patch — three runtime-correctness bugs in researcher-build.sh, transition.sh, and gate a09 surfaced by a real qualifying flow.
Patch — scoped Step-0 PR queries to upstream-only (own-org exclusion).
First marketplace release — 41 gates, dossier system, lifecycle workflow, 5 subagents.
Full changelog: https://github.com/jeremylongshore/contributing-clanker/blob/master/CHANGELOG.md