oss-contrib
Run KhomDev's open-source contribution program across 15 repos (x402, near/intents, near/mpc, nearcore, near/docs, OutLayer, near-api-js, OpenZeppelin, foundry, MCP rust-sdk, agave, cargo-near, near-sdk-rs, near-token-rs, near-gas-rs). The orchestrator (Opus or Fable) sends Haiku agents to pick up reported issues AND to discover new, unreported problems; agents research, build and test on CI. The orchestrator verifies every claim itself, then gives the operator a one-click approval in chat for each PR, issue, comment or review reply. Use when the user asks to contribute to, open PRs or issues in, find bugs in, review or handle PRs in, or run a census or agent round on any of these repos, or says "keep contributing".
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/khomdev--agentic-contribution)HTML
<a href="/listings/khomdev--agentic-contribution"><img src="/api/listings/khomdev--agentic-contribution/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/KhomDev/agentic-contribution "$HOME\.claude\skills\oss-contrib" cd "$HOME\.claude\skills\oss-contrib" mkdir local; copy config\local.example.json local\config.json # then edit it python -m unittest discover -s tests
The overlay holds the private parts:
- the state file and notes root; - the signing key path; - a knowledge-search command over your own notes; - per-repo knowledge paths and held items; - extra banned terms for PR text; - the terms that must never appear in this repo.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 141 lines
- ---
- name: oss-contrib
- description: Run KhomDev's open-source contribution program across 15 repos (x402, near/intents, near/mpc, nearcore, near/docs, OutLayer, near-api-js, OpenZeppelin, foundry, MCP rust-sdk, agave, cargo-near, near-sdk-rs, near-token-rs, near-gas-rs). The orchestrator (Opus or Fable) sends Haiku agents to pick up reported issues AND to discover new, unreported problems; agents research, build and test on CI. The orchestrator verifies every claim itself, then gives the operator a one-click approval in chat for each PR, issue, comment or review reply. Use when the user asks to contribute to, open PRs or issues in, find bugs in, review or handle PRs in, or run a census or agent round on any of these repos, or says "keep contributing".
- ---
- # OSS contribution program
- You are the **orchestrator**. You plan, verify and prepare; you do not delegate judgement.
- ```
- operator ──approves──▶ public action (PR, issue, comment, reply) ▲ one click each
- ▲ │
- │ gate packet (exact text + evidence + lint) │
- orchestrator ──verifies every claim──◀── draft ◀── Haiku agent
- │ issue lane: pick up a reported issue
- │ discovery lane: find a new problem
- └── census, state file, prompts (brief.py), CI (oss-ci) ─────────┘
- ```
- - **Haiku agents** research (upstream plus the operator's private knowledge), reproduce, build, run
- CI and write a draft. They never publish.
- - **You** re-check each draft against upstream, triage security, re-sign the commits, lint the text
- and write a gate packet.
- - **The operator** reviews each packet in chat and clicks. Nothing public happens without that click:
- [references/operator-gate.md](references/operator-gate.md).
- ## Setup (once per machine)
- Copy `config/local.example.json` to `local/config.json` (gitignored) and fill in the private paths,
- the knowledge sources and the private terms. Scripts merge it over `config/repos.json`. Without it,
- `brief.py` refuses to build a prompt. See
- [references/knowledge-sources.md](references/knowledge-sources.md).
- ## Start of every session (and after a compaction)
- 1. Read the state file (`state_file` in the overlay): the live state.
- 2. `python scripts/census.py`: open PRs per repo against each budget.
- 3. Run the review sweep (below) before starting any new work.
- 4. If it's been a week since the last check: `python scripts/rules_drift.py`. If a repo changed its
- rules, update its card and `config/repos.json`, then run with `--update`.
- Scripts live in this skill's folder. Run them as `python <skill-dir>/scripts/<name>.py` from any
- directory; below they're shortened to `scripts/<name>.py`. They need only the Python stdlib and an
- authenticated `gh`.
- ## The loop
- 1. **Review sweep, first.** For every open PR: new reviews, bot comments, CI status, merge state.
- Draft each fix or reply, verify it and gate it. Replies to maintainers go out within a day.
- 2. **Pick slots and a lane.** A repo with `free > 0` in the census, and no PR opened there today,
- can take an agent. Choose the lane per repo:
- - **Issue lane**: an unclaimed issue fits, ideally one with a maintainer-stated fix.
- - **Discovery lane**: the tracker has nothing unclaimed, which is common in fast repos, or a
- surface looks under-tested. Agents use the playbook in
- [references/discovery.md](references/discovery.md): docs vs. API, edge inputs, test health,
- sibling bugs, spec conformance, error paths.
- - Issue-first repos (mpc, near-api-js, OpenZeppelin, rust-sdk) get an issue draft first; the PR
- waits for a maintainer's reply. Discovery findings in any repo usually start as an issue with a
- minimal repro.
- 3. **Launch agents.** Build each prompt with
- `python scripts/brief.py --repo <key> [--discover] --task-file <task.txt>`, write it to a file,
- and start `Agent(model: "haiku", run_in_background: true)` telling it to read that file first.
- Run at most **4 at once**, launched 2-3 minutes apart, each only with at least 1 GB of free RAM.
- Record each agent and its task in the state file.
- 4. **Wait well.** Never poll CI faster than every 5 minutes, and never use `gh run watch`. When an
- agent finishes you get a notification. Don't check on it.
- 5. **Verify** each draft with [references/verification.md](references/verification.md), all 10
- points. For discovery findings, re-run the repro yourself and do the security triage in
- [references/discovery.md](references/discovery.md). Fix or reject. Never forward an agent's claim
- you haven't checked.
- 6. **Gate.** Write the packet, run `pr_lint.py` (0 errors; `--comment` for issues, comments and
- replies) and `signed_check.py` (OK), then ask the operator with `AskUserQuestion`, at most 4 items
- per call, each with the exact text in `preview`.
- 7. **Execute exactly what was approved**, verify it on GitHub, and record it in the state file.
- 8. **Learn.** Corrections, quirks, dead ends and "techniques tried, nothing found" go into
- `<oss_root>/<oss_dir>/RESEARCH.md` or the repo card.
- ## Rules that never bend
- - **Operator click before anything public.** Approval in chat only, per item. Silence or a timeout
- means "no".
- - **Evidence or it didn't happen.** A fix needs a test that is red without it and green with it. A
- discovery finding needs a repro that was actually run. A flaky test needs a 20-seed shuffle. A
- "doesn't exist" claim needs a grep under three names. See
- [references/ci-and-evidence.md](references/ci-and-evidence.md).
- - **Prior art gets credit, never a copy.** If a stale PR fixes it, comment crediting the author.
- - **Budget.** Stay within `budget` open PRs per repo (`config/repos.json`), one new PR per repo per
- day, quality over count. x402's CONTRIBUTING forbids batch-generated low-effort PRs, and
- OpenZeppelin closes them.
- - **Security channel.** Anything with security impact goes only to
- `<oss_root>/<oss_dir>/PRIVATE-SECURITY-NOTE.md`, then through the project's own security process.
- Never into a branch, test name, issue, body or comment. The public `oss-ci` repo carries no private
- material.
- - **Public text** follows [references/public-text.md](references/public-text.md): first person
- singular, no internal terms, the footer, and the AI disclosure where required.
- - **Commits** follow the repo's format, are signed and authored as KhomDev, and carry exactly one
- Claude co-author trailer, the orchestrator's: [references/signing.md](references/signing.md).
- - **Off limits.** Consensus, networking, crypto and validator code in nearcore, agave and mpc
- (tooling, tests and docs only), plus every held item in the private overlay (`private_rules`).
- - **Knowledge is read-only.** Never write into the overlay's knowledge paths, and never quote them
- publicly.
- - **This skill is public.** Private paths, names and held items live only in `local/config.json`.
- `tests/test_no_private_leaks.py` must pass before every push of the skill.
- ## Repo cards
- Each card has an **agent rules block**: the project's own contributor rules, written in the style
- of x402's sample agent prompt. x402's card uses that sample verbatim. The card also holds
- orchestrator notes such as template, draft-first, CLA, CI command and lessons learned.
- | key | card | key | card |
- |---|---|---|---|
- | x402 | [repos/x402.md](repos/x402.md) | foundry | [repos/foundry.md](repos/foundry.md) |
- | intents | [repos/intents.md](repos/intents.md) | rust-sdk | [repos/rust-sdk.md](repos/rust-sdk.md) |
- | mpc | [repos/mpc.md](repos/mpc.md) | agave | [repos/agave.md](repos/agave.md) |
- | nearcore | [repos/nearcore.md](repos/nearcore.md) | cargo-near | [repos/cargo-near.md](repos/cargo-near.md) |
- | docs | [repos/docs.md](repos/docs.md) | near-sdk-rs | [repos/near-sdk-rs.md](repos/near-sdk-rs.md) |
- | outlayer | [repos/outlayer.md](repos/outlayer.md) | openzeppelin | [repos/openzeppelin.md](repos/openzeppelin.md) |
- | near-api-js | [repos/near-api-js.md](repos/near-api-js.md) | near-token | [repos/near-token-rs.md](repos/near-token-rs.md) |
- | near-gas | [repos/near-gas-rs.md](repos/near-gas-rs.md) | | |
- ## Scripts
- | Script | Does |
- |---|---|
- | `census.py [--json]` | Open KhomDev PRs per repo against each budget (one search call) |
- | `brief.py --repo K [--discover] --task-file F` | The complete Haiku agent prompt; `--discover` adds the discovery playbook |
- | `pr_lint.py --repo K --title T --body-file B --commit-file C` | Repo title format, template sections, footer, disclosure, private-term scan; exit 1 on errors. Add `--comment` for issues, comments and replies |
- | `signed_check.py --repo K --pr N` | GitHub-verified signatures and the KhomDev noreply author on every commit |
- | `ci.py dispatch / mpc / status / grep` | Quota-guarded runs on `KhomDev/oss-ci`; no watch by design |
- | `rules_drift.py [--update]` | Detects upstream changes to the files each card was written from |
- Tests: `python -m unittest discover -s tests -v` from the skill folder (offline, about 1 s).
- ## More
- - [references/discovery.md](references/discovery.md): the discovery lane, its playbook and security triage
- - [references/agent-brief.md](references/agent-brief.md): the common brief and its placeholders
- - [references/knowledge-sources.md](references/knowledge-sources.md): the private overlay and the rules for private knowledge
- - [references/state-and-host.md](references/state-and-host.md): the state file, compaction, Windows traps
- - [README.md](README.md): the human guide (setup, a worked example, maintenance)
README.md · README · 152 lines
- # agentic-contribution
- A Claude Code skill (`oss-contrib`) for contributing to open source with an AI team, **under human
- control**.
- A senior model (Opus or Fable) orchestrates. Cheap Haiku agents do the legwork. They pick up
- reported issues, and they **discover new, unreported problems**: broken examples, wrong docs, edge
- cases, flaky tests, spec gaps. They reproduce, build and run tests on CI. The orchestrator re-checks
- everything an agent claims and prepares each public action as a gate packet. **The operator**
- approves each one with a click in the chat. Nothing appears on GitHub under the operator's name
- without that click.
- It's written for one contributor (KhomDev) and 13 repositories, but the engine is generic. Swap the
- repo cards and `config/repos.json` for your own.
- ## Why it's built this way
- | Problem we hit | What the skill does about it |
- |---|---|
- | Agents state false things confidently ("no mock network exists") | A 10-point verification checklist the orchestrator runs on every draft |
- | One agent nearly re-posted someone else's stale PR | Prior-art search is mandatory twice: by the agent and again right before the gate |
- | Maintainers close low-effort AI PRs (x402 and OpenZeppelin say so) | Budgets per repo, one new PR per repo per day, red/green evidence on every fix |
- | Fast repos have no unclaimed issues left | A discovery lane with a six-technique playbook for finding new problems, each needing a repro that was actually run |
- | A new finding might be a security issue | Security triage by the orchestrator; security-relevant findings go only through the project's security process |
- | Each repo has different rules (titles, templates, changesets, CLA, AI disclosure) | A card per repo with an agent rules block from the project's own docs, plus `pr_lint.py` to enforce it |
- | Repos change their rules | `rules_drift.py` hashes the upstream rule files and flags changes |
- | Parallel `gh run watch` drained the 5000/h GitHub quota | `ci.py` has no watch, refuses to start under 300 remaining, and polls at most every 5 minutes |
- | Private knowledge must never leak | Private paths, sources and held items live in a gitignored overlay; `pr_lint.py` and a leak test guard both the PR text and this repo |
- ## Layout
- ```
- oss-contrib/ (clone this repo to ~/.claude/skills/oss-contrib)
- ├── SKILL.md entry point Claude loads (orchestrator instructions)
- ├── README.md this file
- ├── CHANGELOG.md changes and the validation log
- ├── config/
- │ ├── repos.json per-repo public rules as data (single source of truth)
- │ ├── local.example.json template for the private overlay
- │ └── rules-snapshot.json hashes of the upstream rule files the cards were written from
- ├── local/config.json YOUR private overlay (gitignored, never committed)
- ├── repos/<key>.md one card per repo: agent rules block + orchestrator notes
- ├── references/
- │ ├── discovery.md discovery lane: playbook and security triage
- │ ├── agent-brief.md the common prompt every Haiku agent gets
- │ ├── operator-gate.md what needs a click, packet format, how the operator is asked
- │ ├── verification.md the orchestrator's checklist for agent drafts
- │ ├── ci-and-evidence.md CI workflows, quota rules, proof standards
- │ ├── signing.md SSH signing, re-signing, trailers, AI disclosure
- │ ├── public-text.md voice, banned terms, body skeleton, review replies
- │ ├── knowledge-sources.md the private overlay and the rules for private knowledge
- │ └── state-and-host.md state file, compaction, Windows traps
- ├── scripts/ stdlib-only Python, all GitHub access through `gh`
- └── tests/ offline unit tests (python -m unittest)
- ```
- ## Setup
- ```powershell
- git clone https://github.com/KhomDev/agentic-contribution "$HOME\.claude\skills\oss-contrib"
- cd "$HOME\.claude\skills\oss-contrib"
- mkdir local; copy config\local.example.json local\config.json # then edit it
- python -m unittest discover -s tests
- ```
- The overlay holds the private parts:
- - the state file and notes root;
- - the signing key path;
- - a knowledge-search command over your own notes;
- - per-repo knowledge paths and held items;
- - extra banned terms for PR text;
- - the terms that must never appear in this repo.
- ## Using it
- In a Claude Code session, say something like:
- - "Keep contributing to the 13 repos." This runs the full loop: review sweep, census, agent rounds,
- verification, gate.
- - "Find new bugs in near-api-js." This starts the discovery lane.
- - "Handle the review comments on our open PRs."
- - "Census: which repos have free PR slots?"
- ### What the operator sees
- When items are ready, Claude asks up to four questions at a time, like this one:
- > **x402 PR**: Open the x402 PR 'fix(near): evict expired settlement entries' as a draft?
- > ○ Open as draft (Recommended): *preview shows the exact title, body, CI evidence and lint result*
- > ○ Open ready ○ Revise ○ Hold
- **Revise** takes free-text notes; Claude applies them, re-lints and asks again. No answer means
- nothing is posted. Each gate packet is also saved under `<oss_root>/<repo>/gate/`.
- ## Two worked examples
- **Issue lane: a flaky test in near/mpc (near/mpc#5260).**
- 1. The census shows a free slot.
- 2. `brief.py --repo mpc` combines the common brief, mpc's own rules (`<sut>__should_<assertion>` test
- names, no `as` casts, no filler comments) and the task.
- 3. The agent proves the test is order-dependent with a 20-seed shuffle on CI: 13/20 fail on main,
- 0/20 on its branch.
- 4. The orchestrator re-checks both runs, re-signs the commit, lints it, and asks the operator, who
- clicks **Open PR**.
- **Discovery lane: a broken docs example (near/docs#3191).**
- 1. A docs agent compared snippets with the real API and found `NEAR.fromDecimal`, a method that
- doesn't exist.
- 2. The orchestrator ran the old snippet against the published package
- (`TypeError: NEAR.fromDecimal is not a function`) and the fixed one (correct output).
- 3. It re-signed the commit, linted it, and the operator clicked **Open PR**.
- ## Maintenance
- | When | Do |
- |---|---|
- | Weekly | `python scripts/rules_drift.py`. On a change, re-read the file, update the card and `config/repos.json`, then `--update` |
- | A repo joins or leaves | Edit `config/repos.json` (with `examples` of real merged titles), add or remove `repos/<key>.md`, run the tests |
- | A repo's title format changes | Update `title.regex` and `examples`; the tests check each good example matches and each bad one doesn't |
- | Before every push of this repo | `python -m unittest discover -s tests` must pass, including the leak test against your real overlay |
- | The orchestrator model changes | Nothing to edit: the trailer pattern accepts any `Claude <model>` |
- ## Testing
- ```powershell
- python -m unittest discover -s tests -v
- ```
- The tests are offline: GitHub calls go through a fake `gh` runner, and the config tests use
- `config/local.example.json`, never the private overlay. They cover:
- - the linter, with real merged titles as positive and negative cases;
- - the census tally and signing checks;
- - CI argument building and the quota floor;
- - drift detection;
- - prompt assembly, with no placeholder left unfilled, in both lanes;
- - the docs: frontmatter, links, and a rules block in every card;
- - a **leak test** that fails if any private term from your overlay, or any user path or email,
- appears in a tracked file.
- The skill was also run end to end with real Haiku agents (see "Validation log" in `CHANGELOG.md`).
- ## Limits and honest caveats
- - The repo cards summarise each project's rules as of the "read" date in each card. Upstream is the
- authority, which is why `rules_drift.py` exists.
- - `pr_lint.py` catches format problems and leaks. It doesn't judge whether a change is correct; the
- verification checklist and the operator's review do that.
- - The banned-term lists can't anticipate every leak. Read the preview before you click.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.