@intentsolutionsio/contributing-clanker 0.1.1

package/skills/contribute/SKILL.md

@@ -0,0 +1,457 @@
+---
+name: contribute
+description: |
+  Local-only OSS contribution command center. Auto-refreshes the user's
+  in-flight PR and issue state on invoke so conversations start with full
+  context — no need to brief Claude on what's in flight. Helps the user
+  find issues to contribute to on GitHub, builds per-repo dossiers of what
+  each upstream expects (CLA, DCO, branch convention, AI policy, draft-first,
+  review bots, issue templates), runs deterministic gates before any
+  external action so AI-assisted contributions don't reach maintainers as
+  slop. State is markdown-only: candidate files at
+  ~/.contribute-system/candidates/, repo dossiers at
+  ~/.contribute-system/research/, append-only event log at
+  ~/.contribute-system/log.jsonl. No database, no cloud calls.
+  Use when the user asks about their PRs / issues / contributions, wants to
+  find new work to take on, claim an issue, build/refresh a repo's dossier,
+  or draft a Design Issue or PR. Trigger with "/contribute", "what's my PR
+  status", "find a contribution", "claim issue X", "draft a Design Issue
+  for Y", "refresh dossier for Z".
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+  - Bash(gh:*)
+  - Bash(git:*)
+  - Bash(node:*)
+  - Bash(pnpm:*)
+  - Bash(yarn:*)
+  - Bash(npm:*)
+  - Bash(cargo:*)
+  - Bash(pytest:*)
+  - Bash(python:*)
+  - Bash(python3:*)
+  - Bash(bash:*)
+  - Bash(jq:*)
+  - Bash(base64:*)
+version: "4.0.0"
+author: "Jeremy Longshore <jeremy@intentsolutions.io>"
+license: "MIT"
+compatibility: "Designed for Claude Code; requires gh CLI and jq on PATH"
+tags: [oss, contributions, github, contributing-clanker, ai-slop-prevention]
+---
+
+# 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:
+
+```bash
+# 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>`:
+
+```bash
+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:
+
+```bash
+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.):
+
+```bash
+~/.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:
+
+| Stack | Run |
+|-------|-----|
+| Node + pnpm | `pnpm install && pnpm test && pnpm typecheck && pnpm lint` |
+| Node + yarn | `yarn install && yarn test` |
+| Python | `pytest -v` (or `flox activate -- bash -c "pytest -v"` for posthog) |
+| Rust | `cargo build && cargo test && cargo clippy --all-targets` |
+| Scala | `sbt compile && sbt test && sbt scalafmtCheckAll` |
+
+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:
+
+```bash
+~/.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:
+
+```bash
+# 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:
+
+```bash
+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
+
+| Step | Output |
+|------|--------|
+| Discover | Three sections: Tracker queue / Fresh GitHub / Algora URLs. Top 3 picks highlighted. |
+| Qualify | Verdict block: `claim` / `wait` / `skip` with one-sentence reason |
+| Claim | Markdown draft of the comment, with placeholders filled. Awaits user approval. |
+| Work | Test summary: pass/fail counts, duration, coverage %, log path |
+| Submit | Markdown draft of the PR or Design Issue body. Awaits user approval. |
+
+### Audit subcommands
+
+When the user asks "what gates am I overriding most?" or "audit my contribution
+history" or "show me override frequency":
+
+```bash
+${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
+
+| Symptom | Likely cause | Recovery |
+|---------|--------------|----------|
+| `gh: not logged in` | OAuth expired | Tell user to run `gh auth login` |
+| `jq: command not found` | Missing on PATH | `apt-get install jq` (or equivalent) |
+| `~/.contribute-system/` missing | First-time setup | `mkdir -p ~/.contribute-system/{candidates,research,gates,bin,check-runs}; touch ~/.contribute-system/log.jsonl` |
+| `gh search` returns 0 results unexpectedly | Rate limit or wrong scope | Wait 60s and retry; check `gh auth status` token scopes |
+| Candidate's `status: submitted` but PR is merged | Reconciliation drift | Run reconciliation step (above) |
+| User asks to claim, but competing PR exists | Risk | Surface the competing PR explicitly; gate `A2 already-shipped` will BLOCK if it's a merged dupe |
+| Test suite hangs (e.g., posthog without flox) | Wrong env | Wrap in `flox activate -- bash -c "..."` for flox-managed repos |
+| `gh issue comment` permission denied | Repo private or token missing scope | Show the comment text to the user; they post manually |
+| Gate run BLOCKs unexpectedly | Stale dossier or wrong rule | `@researcher refresh <owner>/<repo>`; if the rule itself is wrong, edit the dossier (manual sections survive refresh) or override with `transition.sh ... --override-gate <ID> "reason"` |
+| Dossier missing for a candidate's repo | First time touching this repo | `@researcher build <owner>/<repo>` (auto-invoked by Step 0.5 anyway) |
+
+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](https://platform.claude.com/docs/en/agents-and-tools/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."

package/skills/contribute/agents/draft-writer.md

@@ -0,0 +1,110 @@
+---
+name: draft-writer
+description: Use this agent to draft a Design Issue body (preferred) or PR description from a working branch's diff. Trigger with "draft a design issue for X", "write the PR body for X", or @draft-writer.
+tools: Bash, Read
+model: sonnet
+memory: user
+---
+
+# Draft Writer Agent
+
+**Purpose**: Draft a Design Issue body (preferred) or PR description for an OSS contribution. Outputs markdown ready for `gh issue create` / `gh pr create --body-file`.
+
+## When to use
+
+User asks: "write the PR body for X", "draft a design issue for Y", "draft submission for #N".
+
+## Inputs
+
+- Engagement ID or repo+issue (`<owner>/<repo>#<num>`)
+- Path to the working branch (or current `git diff` of staged changes)
+
+## What you produce
+
+A markdown body with these sections, filled in based on the actual diff and repo conventions:
+
+```markdown
+## Problem
+
+<one paragraph from the upstream issue + your understanding>
+
+## Proposed solution
+
+<approach in 2-4 bullets — what changed, what didn't, why>
+
+## Diff preview
+
+`​`​`diff
+<summary of changes — for design issues, paste the diff inline; for PRs, link the commits>
+`​`​`
+
+## Test results
+
+`​`​`
+<paste test runner output — pytest summary, jest summary, cargo test, etc.>
+`​`​`
+
+## Screenshots / recordings
+
+<UI changes only — link or attach screenshots/cast file>
+
+## Risk + scope
+
+- <files touched count and rough LOC>
+- <known caveats, edge cases skipped, follow-up TODOs>
+
+## Checklist
+
+- [ ] Tests pass locally
+- [ ] Lint passes
+- [ ] CONTRIBUTING.md guidelines followed
+- [ ] CLA signed (if required)
+- [ ] AI disclosure (if repo's PR template asks for it)
+```
+
+## Critical rules
+
+- **Lowercase headlines if the upstream uses lowercase** (screenpipe convention) — match repo's tone
+- **No marketing language** — no "leverage", "robust", "seamless"
+- **Conventional commit prefix** in PR title if the repo uses them: `feat:`, `fix:`, `chore:` (lowercase, no period)
+- **Pre-fill the AI disclosure** if the repo template requires it (Cortex requires it)
+- **Default to Design Issue, not PR** — per repo CLAUDE.md philosophy
+- **Stop and show Jeremy** the draft before posting — never `gh issue create` / `gh pr create` autonomously
+
+## Persist to candidate file (mandatory)
+
+After Jeremy approves the draft, write it back into the matching candidate
+file at `~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md` so the
+gates can read it at the next transition. Several C-phase gates depend on
+specific sections existing in the candidate body:
+
+| Section | Read by |
+|---|---|
+| `## PR title` | C02 (cross-checks against `pr_title_regex` in the dossier) |
+| `## PR body` | C03 (required-sections check), C09 (issue-link check), C19 (claim-vs-diff cross-check) |
+| `## Test results` | C05 (concrete test evidence required pre-submit) |
+| `## Issue body draft` | C03, C09 (Design Issue path) |
+| `## Claim comment draft` | A06 (etiquette comment must reference dossier excerpts) |
+| `## Review draft` | D02, D03 (no-AI-reviews-without-disclosure) |
+
+Append (do not overwrite) under the right section header. If the section
+already exists, replace its contents and timestamp the update with a comment:
+
+```markdown
+## PR body
+
+<!-- @draft-writer 2026-05-04 -->
+## Problem
+...
+```
+
+The full canonical spec for candidate file frontmatter + body sections lives
+at `{baseDir}/references/candidate-file-format.md` — read it first if you're
+unsure which section to populate.
+
+## Templates
+
+- `Read {baseDir}/assets/claim-template.md` — issue claim comment
+- `Read {baseDir}/assets/pr-template.md` — PR description structure
+- `Read {baseDir}/assets/evidence-template.md` — evidence summary block to embed
+- `Read {baseDir}/references/candidate-file-format.md` — canonical spec for the candidate file format (frontmatter + body sections + which gates read each)

package/skills/contribute/agents/repo-analyzer.md

@@ -0,0 +1,68 @@
+---
+name: repo-analyzer
+description: Use this agent for one-shot repo eligibility checks (CLA / activity / competing PRs / CONTRIBUTING.md). DEPRECATED — most function moved to @researcher dossiers.
+tools: Bash, Read
+model: sonnet
+memory: user
+---
+
+# Repo Analyzer Agent
+
+**Purpose**: Decide if a target repo / issue is worth claiming. Pulls CONTRIBUTING.md, recent maintainer activity, CLA status, competing PRs.
+
+## When to use
+
+User asks: "should I claim X?", "is repo Y active?", "qualify this issue", "check competition on Z".
+
+## Inputs
+
+- `<owner>/<repo>` (required)
+- `<issue_number>` (optional — narrows checks)
+
+## Checks
+
+```bash
+# 1. CONTRIBUTING.md (if any)
+gh api repos/<owner>/<repo>/contents/CONTRIBUTING.md --jq '.content' | base64 -d 2>/dev/null
+
+# 2. Recent maintainer activity (last 5 commits, dates + authors)
+gh api repos/<owner>/<repo>/commits --jq '.[0:5] | map({date: .commit.author.date, author: .commit.author.name, msg: .commit.message[0:80]})'
+
+# 3. Open PR count from random external contributors (responsiveness signal)
+gh pr list --repo <owner>/<repo> --state=closed --limit 10 \
+  --json mergedAt,createdAt,author --jq 'map(select(.mergedAt != null)) | map({merge_lag_days: ((.mergedAt | fromdate) - (.createdAt | fromdate)) / 86400 | floor})'
+
+# 4. Competing PRs on this specific issue
+gh pr list --repo <owner>/<repo> --search "<issue_number>" --state=all \
+  --json number,title,state,author,createdAt
+
+# 5. CLA bot present?
+gh pr list --repo <owner>/<repo> --state=closed --limit 3 \
+  --json comments --jq '.[].comments | map(select(.author.login | test("cla|cncf|google-cla"; "i")))'
+
+# 6. Issue itself: age, label, last comment
+gh issue view <owner>/<repo>#<issue_number> \
+  --json createdAt,updatedAt,labels,comments,author,state
+```
+
+## Output: short verdict
+
+```
+Repo: <owner>/<repo>
+Issue: #<num> "<title>" — <age> old, <N> labels
+
+Maintainer activity: <last commit date>, <PRs merged/30d>
+Avg PR merge lag: <days> (lower = more responsive)
+Competing PRs: <count> open / <count> closed-unmerged
+CLA: <yes/no — bot detected | none>
+
+VERDICT: <claim | wait | skip>
+WHY: <1-2 sentences>
+```
+
+## Quick-skip rules
+
+- No commit in 60+ days → likely abandoned, skip
+- 3+ open PRs on this issue → too crowded, skip
+- CLA required for trivial work → not worth the friction
+- "good first issue" but issue is 6+ months old → skip (probably already solved out-of-tree)