Contribute

Contribute Command Center

Overview

Local-only OSS contribution workflow. The skill itself is the system — there is no separate CLI binary, dashboard, or cloud backend. State lives in three places:

1. GitHub itself — fetched live via gh for any PR/issue state question. Never cached long-term.
2. Markdown candidate files at ~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md — one per issue we're tracking. Frontmatter is the queryable layer (status, scout_score, repo, research_path, overrides). Body holds claim drafts, PR drafts, scope notes.
3. Markdown repo dossiers at ~/.contribute-system/research/<owner>__<repo>.md — one per upstream repo we contribute to. Built by the @researcher subagent. Frontmatter is canonical for every gate (CLA, DCO, branch convention, AI policy, draft-first, review bots, issue templates). Body holds curated knowledge: pet peeves, failure log, free-form notes that survive refresh.
4. Append-only event log at ~/.contribute-system/log.jsonl — every gate run, transition attempt, override, scout/researcher invocation lands here with a UTC timestamp. Filterable via jq.

Use this skill when the user wants to:

• Know what's in flight (open PRs, claimed issues, candidate queue)
• Find a new issue to contribute to on GitHub
• Build or refresh a per-repo dossier (delegates to @researcher)
• Run gate-checked transitions (claim, work, submit) — every external action passes through transition.sh first
• Draft a claim comment, Design Issue, or PR description (default: Design Issue, NOT a PR)
• Run an upstream repo's test suite

The pre-2026-04-30 version of the skill used a SQLite tracker (~/.contribute-system/contribute.db, 32 tables) plus a separate contribute-system/ monorepo (Next.js dashboard, TS CLI, Cloud Functions). Both were deleted because they were never used in practice. The skill now reads markdown directly. That tradeoff is deliberate: human-readable, greppable, git-trackable, survives any tool, no daemon process.

Prerequisites

• gh CLI, authenticated as the user (gh auth status should show "Logged in")
• jq on PATH (used by gates + log filtering)
• Workspace at ~/000-projects/contributing-clanker/ containing upstream clones (each clone has its own CLAUDE.md for project conventions)
• Runtime state dir at ~/.contribute-system/ — created on first scout/researcher run if missing

Run this DCI check at activation (output is auto-injected into the prompt):

gh auth status >/dev/null 2>&1 && echo "gh: ok" || echo "gh: NOT logged in"
[ -d ~/.contribute-system/gates ] && echo "gates: $(ls ~/.contribute-system/gates/*.sh 2>/dev/null | wc -l) installed" || echo "gates: not yet installed"
[ -d ~/.contribute-system/candidates ] && echo "candidates: $(ls ~/.contribute-system/candidates/*.md 2>/dev/null | wc -l) tracked" || echo "candidates: empty"
[ -d ~/.contribute-system/research ] && echo "dossiers: $(ls ~/.contribute-system/research/*.md 2>/dev/null | wc -l) built" || echo "dossiers: empty"
[ -f ~/.contribute-system/profile.md ] && echo "profile: ok" || echo "profile: missing — edit ~/.contribute-system/profile.md"
[ -f ~/.contribute-system/log.jsonl ] && echo "log: $(wc -l < ~/.contribute-system/log.jsonl) events" || echo "log: empty"

Instructions

Step 0 — Refresh state (run first, every time)

Before answering anything contribution-related, surface current state. Run these in parallel with the Bash tool:

# Upstream PRs in flight (filtered to outside-org repos only —
# the system tracks contributions INTO repos the user does not own;
# own-repo PRs are out of scope and must be excluded).
#
# OWN_ORGS is the prefix list of repos to exclude. Update if the user
# adds a new org. (Discoverable via `gh api user/orgs --jq '.[].login'`
# plus the user's own login from `gh api user --jq '.login'`.)
OWN_ORGS='jeremylongshore/ intent-solutions-io/'
gh search prs --author=@me --state=open --limit=50 \
  --json number,title,url,repository,isDraft,createdAt | \
  jq --arg own "$OWN_ORGS" '
    ($own | split(" ")) as $excl |
    map(select(.repository.nameWithOwner as $r |
               ($excl | map(. as $p | $r | startswith($p)) | any) | not))
  '

# Recently-merged + closed upstream PRs (last 30, same scope filter)
gh search prs --author=@me --state=closed --limit=30 \
  --json number,title,url,repository,closedAt,createdAt | \
  jq --arg own "$OWN_ORGS" '
    ($own | split(" ")) as $excl |
    map(select(.repository.nameWithOwner as $r |
               ($excl | map(. as $p | $r | startswith($p)) | any) | not))
  '

# Local candidate tracker — markdown frontmatter is the queryable layer.
# Candidates are upstream-only by construction (scout never enqueues
# own-repo issues), so no scope filter needed here.
for f in ~/.contribute-system/candidates/*.md; do
  awk -v f="$(basename "$f" .md)" '
    /^---$/ { fm = !fm ? 1 : 2; next }
    fm == 1 && /^(repo|issue_number|status|scout_score|research_path|pr_number):/ { print f, $0 }
  ' "$f"
done 2>/dev/null

# Recent activity from the event log
tail -50 ~/.contribute-system/log.jsonl 2>/dev/null \
  | jq -c "select(.event | test(\"transition_|gate_|researcher_|scout_\"))" 2>/dev/null

Scope rule (non-negotiable): this skill applies only to contributions made INTO repos the user does not own. Own-org PRs (jeremylongshore/*, intent-solutions-io/*) are out of scope — they are personal-project work, not anti-slop OSS contributions. The whole architecture (gates, dossiers, lifecycle) exists because upstream maintainers need protection from low-quality AI work; that concern doesn't apply to the user's own repos. If a candidate file ever references an own-org repo, it's a scout bug — flag it.

Then summarize for the user:

• N open / draft PRs (and any blocked on review)
• N candidates in claimed or working status but not yet submitted
• N candidates in open / shortlist status (sorted by scout_score desc)
• Any contradictions between gh (PR state) and the candidate's status: field (e.g., PR merged but candidate still says submitted) — flag for cleanup
• N candidates whose research_path: is empty or stale (>14d) — flag for @researcher build/refresh
• Recent events worth surfacing (gate BLOCKs, overrides, dossier refreshes)

Skip Step 0 only when the user asks about something unrelated to their own contributions.

Step 0.5 — Ensure dossier exists for any repo we'll touch

Every repo we contribute to needs a dossier at ~/.contribute-system/research/<owner>__<repo>.md — that's where every gate in ~/.contribute-system/gates/ reads its rules from (branch convention, CLA/DCO, AI policy, draft-first preference, review bots, etc.).

Before any lifecycle transition (claim, work, submit) for a candidate at repo <owner>/<repo>:

DOSSIER=~/.contribute-system/research/$(echo <owner>/<repo> | tr '/' '_').md
DOSSIER=${DOSSIER/__/__}    # ensure double underscore
if [[ ! -f "$DOSSIER" ]]; then
  echo "no dossier — invoking @researcher"
  # delegate to the researcher subagent
fi
# Also check staleness — refresh if >14 days old
LAST=$(awk '/^last_refreshed:/{print $2; exit}' "$DOSSIER")
if [[ -n "$LAST" ]]; then
  AGE_DAYS=$(( ( $(date +%s) - $(date -d "$LAST" +%s) ) / 86400 ))
  [[ "$AGE_DAYS" -gt 14 ]] && echo "stale ($AGE_DAYS d) — invoking @researcher refresh"
fi

Delegate dossier build/refresh to the @researcher subagent (defined at ${CLAUDE_SKILL_DIR}/agents/researcher.md). It runs in its own context window so the verbose CONTRIBUTING.md fetch + depth-1 link follows stay out of your main conversation. It writes the dossier to disk and reports back a one-paragraph summary.

If the user already invoked @researcher earlier in the session for this repo, skip — don't re-build.

Step 1 — Discover

Find issues worth contributing to. Sources, in priority order:

• Existing candidates with status: open or status: shortlist already in ~/.contribute-system/candidates/ — already discovered + vetted, ranked by scout_score: frontmatter field
• Fresh GitHub label searches scoped to repos / languages in ~/.contribute-system/profile.md: gh search issues "label:'good first issue' state:open language:<lang>" --limit 50

Delegate discovery to the @scout subagent (defined at ${CLAUDE_SKILL_DIR}/agents/scout.md). It runs in its own context window so the verbose gh search output stays out of your main conversation. Pass it a mode: baseline (full per-tier sweep), refresh (re-evaluate existing candidates for momentum), or an ad-hoc query like "TypeScript repos at mainstream tier with no competing PRs." Scout writes ranked candidate markdown files to ~/.contribute-system/candidates/ and appends events to ~/.contribute-system/log.jsonl. Summarize the top picks for the user from those files; do not re-run the search yourself.

Step 2 — Qualify

Before claiming any issue, run these in parallel against the target repo:

gh pr list --repo <owner>/<repo> --search "<issue#>" --state=all
gh api repos/<owner>/<repo>/commits --jq '.[0:3] | map({date: .commit.author.date, msg: .commit.message[0:60]})'
gh api repos/<owner>/<repo>/contents/CONTRIBUTING.md --jq '.content' | base64 -d 2>/dev/null

Quick-reject signals:

• 2+ active PRs already on the issue
• Issue >90 days old with maintainer silence
• CLA required for trivial work
• Stack mismatch with the user's strengths

Use the bundled agents/repo-analyzer.md for the structured eligibility / CLA / rules check.

Step 3 — Claim

Draft a claim comment from assets/claim-template.md. Adapt to the upstream's tone (lowercase if they use lowercase). Show the draft to the user for approval. Never gh issue comment autonomously.

Gate-checked transitions — before showing the claim draft to the user, run the gate-runner via transition.sh to catch traps (already-assigned, already-shipped, stale labels, AI-policy strikes, etc.):

~/.contribute-system/bin/transition.sh shortlist→claimed \
  ~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md

If gates BLOCK, surface the blockers + fix hints to the user. They can fix the underlying issue, pick a different candidate, or use --override-gate <ID> "reason" if they have a specific justification (the reason is logged to ~/.contribute-system/log.jsonl).

After the user posts the claim and gates pass, the candidate's status: field is bumped automatically by transition.sh (atomic write). No manual SQLite update needed — the markdown candidate file IS the tracker.

Step 4 — Work

Each clone in ~/000-projects/contributing-clanker/ has its own CLAUDE.md. Read it first. Run the project's native test suite — common patterns:

Use agents/test-runner.md for the structured runner that tees output to ~/.contribute-system/test-logs/.

Step 5 — Submit

Default to a Design Issue, not a PR. Auto-opening PRs creates "whack-a-mole slopfests" for maintainers (per the repo's CLAUDE.md philosophy).

Order:

1. Open a Design Issue using assets/pr-template.md reshaped for an issue body — include problem, proposed solution, diff preview, test results
2. Wait for maintainer approval of the approach
3. Open the PR using assets/pr-template.md

Use agents/draft-writer.md for the body drafter. Always show the draft to the user for approval before posting.

Gate-checked submission — before opening the PR / Design Issue, run:

~/.contribute-system/bin/transition.sh working→submitted \
  ~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md

This runs phase B (pre-PR), C (PR submission), E (identity), F (legal), and G (infrastructure) gates against the local diff + dossier rules. BLOCK gates refuse the transition; WARN gates surface in the briefing for the user to acknowledge before proceeding.

After successful submission, transition.sh bumps the candidate's status: to submitted atomically. Manually add the PR number to the candidate's frontmatter:

# After PR is opened
sed -i "s/^pr_number:.*/pr_number: <num>/; s|^pr_url:.*|pr_url: <url>|" \
  ~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md

Reconciliation

Periodically (or on user request "reconcile candidates"), check candidates with a pr_number: field against live GitHub state:

for f in ~/.contribute-system/candidates/*.md; do
  PR=$(awk '/^pr_number:/{print $2; exit}' "$f")
  REPO=$(awk '/^repo:/{print $2; exit}' "$f")
  [[ -z "$PR" || "$PR" == "null" ]] && continue
  gh pr view "$PR" --repo "$REPO" --json state,merged,closedAt
done

For each candidate whose actual PR state has moved on:

• PR merged → set status: merged in the candidate (atomic write)
• PR closed unmerged → set status: dropped and append a row to the dossier's ## Failure log section so we learn from it
• PR still open → no change (status: submitted)

Mandatory: human approval before external submission

Copied verbatim from the repo's CLAUDE.md:

Before submitting ANYTHING to external repos:

1. Run all tests — ALL must pass
2. Run project-specific linters — no errors
3. ASK JEREMY FOR APPROVAL with test summary, file list, proposed body
4. Default to Design Issue, NOT a PR

NEVER auto-submit PRs. NEVER bypass human approval. Design issues > PRs.

Output

After Step 0, output a status block. After each subsequent step, output structured progress.

State summary (after Step 0)

PRs in flight: <N> open, <M> draft
  - <repo>#<num>: <title> (state, age)
  ...

Claimed but not submitted: <N>
  - <id>: <repo>#<issue> ($value)
  ...

Tracked opportunities: <N> (top 5 by value)
  - <id>: <repo>#<issue> ($value, <competition flag>)
  ...

Drift: <N> rows where tracker disagrees with GitHub
  - <id>: tracker says <X>, gh says <Y> — suggest <Z>

Per-step output

Audit subcommands

When the user asks "what gates am I overriding most?" or "audit my contribution history" or "show me override frequency":

${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh                       # all-time
${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --since=30             # last 30 days
${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --scope=org:posthog    # one org
${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --gate=A05             # one gate
${CLAUDE_SKILL_DIR}/scripts/audit-overrides.sh --json                 # JSON

Output is a per-gate table with [overrides, blocks, override_rate, top_reason], sorted by override_rate desc. Gates overridden ≥50% of the time get flagged for investigation — either the gate is too strict (false-positive heavy) or it's catching real risk that's being consistently dismissed. Either way, surface it.

Error Handling

If any external submission would happen without human approval, stop and ask. This is non-negotiable.

Examples

Example 1: "What's my PR status?"

User invokes /contribute or asks "what's in flight?"

1. Run Step 0 (parallel gh pr list + gh issue list + candidate-frontmatter scan + recent log events)
2. Output the State Summary block
3. Stop. The user can drill into any PR with a follow-up question.

Example 2: "Find me a new contribution to work on"

User asks "what should I work on next?" or "scout opportunities."

1. Run Step 0 first (state summary)
2. Delegate to @scout (the user-scope subagent at ${CLAUDE_SKILL_DIR}/agents/scout.md)
3. Output Tracker / Fresh GitHub / Algora sections, top 3 highlighted
4. Optional: per top pick, run Step 2 (Qualify) to surface CLA / competing-PR signals

Example 3: "Draft a claim for screenpipe#1234"

User asks to claim a specific issue.

1. Run Step 2 (Qualify) on mediar-ai/screenpipe#1234
2. If verdict is claim, read assets/claim-template.md
3. Fill placeholders (approach in 1-2 bullets, ETA, CLA status)
4. Show draft to user
5. On user approval, post via gh issue comment AND update tracker (Step 3 SQL)

Example 4: "Reconcile the tracker"

User asks to sync local state with GitHub.

1. Read all tracker rows where pr_number IS NOT NULL
2. For each, run gh pr view <repo> <pr_number> --json state,merged
3. Update tracker rows whose status disagrees with GitHub state
4. Output a diff summary: N rows updated, M unchanged

Example 5: "Run tests on cortex"

User asks to verify a working branch.

1. Read agents/test-runner.md
2. Detect cortex stack (Python + pyproject.toml)
3. cd ~/000-projects/contributing-clanker/cortex && pytest -v 2>&1 | tee ~/.contribute-system/test-logs/$(date +%Y%m%d-%H%M%S)-cortex.log
4. Output test summary block (pass/fail counts, log path)

Resources

Bundled subagents (load with Read agents/<name>.md)

• @scout (user-scope subagent at ${CLAUDE_SKILL_DIR}/agents/scout.md) — discovery sweep, GitHub-only, ranked by star-tier brackets. Each candidate it writes carries a research_path: frontmatter field pointing at the matching dossier (or empty if not yet built).
• @researcher (user-scope subagent at ${CLAUDE_SKILL_DIR}/agents/researcher.md) — build / refresh the per-repo dossier at ~/.contribute-system/research/<owner>__<repo>.md. Auto-invoked when a candidate's dossier is missing or older than 14 days.
• agents/repo-analyzer.md — DEPRECATED. Most of its function is now in the dossier system. Keep until Slice 3 retires it.
• agents/draft-writer.md — draft a Design Issue or PR body from a working branch's diff
• agents/test-runner.md — detect upstream stack and run the native test suite, log to disk

Bundled templates (read for fill-in)

• assets/claim-template.md — issue claim comment
• assets/pr-template.md — PR description structure
• assets/evidence-template.md — test/lint evidence summary block

References

• references/workflow-guide.md — long-form narrative of the 5-step workflow with project-specific gotchas

External

• Anthropic Agent Skills overview
• The repo's own CLAUDE.md at ~/000-projects/contributing-clanker/CLAUDE.md for project conventions and per-clone build commands

Old patterns (deprecated, do not reintroduce)

• The pre-2026-04-30 skill referenced a contribute CLI binary, EV scoring, judge gates, slack notifications, asciinema work-session recording, evidence bundles, and competition risk scoring. The underlying contribute-system/ monorepo was deleted because it was never used.
• The pre-2026-05-03 skill used a SQLite tracker at ~/.contribute-system/contribute.db (32 tables, bounties-keyed schema) plus an Algora/Gumroad/Cortex bounty-board framing. That DB was wiped; the framing is gone. The system is now markdown-only: candidate files + dossiers + JSONL event log. The skill is a contribution tool — not a tracker, not a payouts system, not a portfolio.

If a feature from those eras is wanted back, recover code from git log in ~/000-projects/contributing-clanker/. The bar to re-add is "Jeremy actually uses it daily."

Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/contribute/SKILL.md

Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/community/contributing-clanker/skills/contribute/SKILL.md