pm-kit — one place for CI, templates, rules, and Claude commands across all repos

Repos don't copy this kit; they point at it. Change something here, and it reaches every repo:

What	Lives in pm-kit	In each repo	How updates propagate
CI steps (lint, typecheck, test, build)	.github/workflows/ci-*.yml (reusable, workflow_call)	12-line caller .github/workflows/ci.yml → uses: celo-org/pm-kit/...@main	Instantly — callers run whatever is on main here
Preview smoke (Vercel-hosted apps)	.github/workflows/ci-e2e-smoke.yml + e2e-smoke/ (the smoke spec, once)	caller .github/workflows/e2e-smoke.yml on each Preview deployment	Instantly — callers run whatever is on main here
Issue forms, PR template, shared rules, money-path checklist, renovate.json	templates/	.github/…, .claude/shared/…	sync-templates.yml opens a PR in every repo listed in sync/sync.yml
Claude commands /file-issue /write-pr /review-pr /post-merge /close-pr /weekly-status /board-audit	claude-plugin/ (plugin marketplace)	installed plugin	claude plugin update pm-kit
Branch protection	protection/org-ruleset-main.json — one org-level ruleset targeting the 8 repos by name	—	edit the include list, re-run apply-org-ruleset.sh
Merge settings (squash-only, title=commit, auto-merge) + labels	protection/apply-protection.sh, create-labels.sh	per-repo settings via API	re-run (idempotent)
CLAUDE.md	templates/CLAUDE.md.template (starter only)	repo-owned — imports the synced shared rules with @.claude/shared/engineering-rules.md	manual; only project-specific content lives there

Setup (once)

1. Create this as celo-org/pm-kit. All target repos are in celo-org, so it can be internal or private — just enable Settings → Actions → General → Access: "Accessible from repositories in the organization" so the reusable workflows can be called. Caveat: PUBLIC repos cannot call reusable workflows in an internal/private pm-kit (GitHub restriction, the access setting cannot override it) — if any target repo is public, pm-kit must be public too, or that repo keeps a self-contained CI workflow.
2. Wire the template-sync GitHub App (org-owned, no expiry): add repository variable TEMPLATE_SYNC_APP_CLIENT_ID and repository secret TEMPLATE_SYNC_APP_PRIVATE_KEY (the app's full PEM). The app needs Contents RW + Pull requests RW and must be installed on the target repos.
3. Pin the reusable workflow ref: @main is convenient; for stability tag releases (v1) and point callers at @v1.

Team setup (each person, ~2 min)

Everything in this kit is repo-level except one thing: the Claude commands are installed per person.

1. Prereqs: Claude Code and the GitHub CLI (gh auth login).
2. Install the commands:

   claude plugin marketplace add celo-org/pm-kit
   claude plugin install pm-kit@pm-kit

3. Download the headless browser once (the plugin bundles a Playwright MCP server that /write-pr and /review-pr use to click through changed UI; works on macOS, Linux, Windows):

   npx playwright install chromium

4. Verify: run claude in any repo and type / — you should see /file-issue, /write-pr, /review-pr, /post-merge, /close-pr, /weekly-status, /board-audit; /mcp lists playwright as connected.
5. Later updates: claude plugin update pm-kit.

That's it — CI, templates, shared rules, and branch protection are already wired into the repos and need no per-person configuration.

The commands

Each one turns a section of engineering-rules.md into procedure. Every command shows you its output and waits for your confirmation before touching GitHub — they propose, you decide.

Command	What it does	Rules
/file-issue <description>	Verifies the claim by running it, clusters by fix boundary (same-diff / different-schedule tests), drafts title + body + labels against the issue form	§1
/write-pr [issue]	Fills the PR template from the branch: what it does and what it does not do, mutation count, Closes vs Refs decided from the acceptance boxes. UI touched → drives the headless browser over the changed surface (desktop + phone), fixes until the console is clean, attaches screenshots as evidence	§2–3
/review-pr <PR>	Tiers the review by risk, checks the branch out and runs it, clicks through changed UI on the Vercel preview with the browser tools, attempts to refute every claim in the body. No approve-with-nits	§4
/post-merge <PR>	Compares what GitHub actually closed against what the body said, catches sidebar-link closures, drafts reopens and successor issues	§6
/close-pr <PR> <reason>	Closes without merging while capturing what the work proved, with links pinned to the head SHA	§6
/weekly-status [since]	Drafts the Friday per-product status from merged PRs and closed issues — evidence not impressions, under 300 words, printed in chat and written nowhere	§1
/board-audit [repo|all]	Sorts an open backlog into buckets (stale, missing metadata, duplicates, sprawling, stale PRs), then closes / relabels / reassigns one confirmed bucket at a time. The only command that writes in batch — so deletion is never batched, and anything priority:critical stops the run	§1

The first five work on one issue or PR; the last two work on the whole board. /board-audit resumes across sessions from .claude/board-audit.md.

Bootstrap a repo

cd ~/code/<repo> && git checkout -b <handle>/pm-kit-bootstrap
bash ~/code/pm-kit/apply.sh

Then: fill in CLAUDE.md, ensure lint/test/typecheck scripts exist, open the PR. Then labels + protection:

bash pm-kit/protection/create-labels.sh owner/repo
bash pm-kit/protection/apply-org-ruleset.sh          # once, org-level (needs org admin)
bash pm-kit/protection/apply-protection.sh owner/repo   # per-repo merge settings

And the plugin: claude plugin marketplace add celo-org/pm-kit && claude plugin install pm-kit@pm-kit.

Files

• .github/workflows/ — reusable CI (ci-node, ci-hardhat, ci-foundry, ci-python, ci-docs-mintlify), ci-e2e-smoke (preview smoke), verify-release-version, sync-templates
• callers/ — thin per-repo workflows (ci-*, e2e-smoke on deployment_status, issue-priority-label)
• e2e-smoke/ — the preview smoke spec, kept once here and checked out by ci-e2e-smoke (see its header for what green means)
• templates/ — everything synced into repos, plus CLAUDE.md.template
• templates/.claude/shared/engineering-rules.md — the merged playbook (issues, PRs, tests, reviews, merging, closing, contradictions log)
• templates/.claude/shared/money-path-checklist.md — 18 recurring defects for money/security diffs
• templates/.claude/shared/tester-mode-pattern.md — run real-money paths in production behind a restricted audience; porting checklist
• claude-plugin/ — commands; .claude-plugin/marketplace.json — marketplace manifest
• protection/ — org-ruleset-main.json + apply-org-ruleset.sh (one org ruleset), ruleset-main.json + apply-protection.sh (per-repo fallback + merge settings), create-labels.sh
• testing/ — Vitest scaffold for repos with zero tests
• SETUP-GUIDE.md — the step-by-step walkthrough

Why not celo-org/.github?

It exists and is the org-wide default for ~300 repositories (Code of Conduct, CONTRIBUTING, SECURITY, Renovate preset). Anything placed there — issue forms, PR template — becomes the default for every celo-org repo without its own. Our templates are team conventions, so they're synced into our eight repos instead. Two things from the org repo we should reuse rather than duplicate: its renovate-config.json preset (extend it in our renovate.json instead of config:recommended if the org preset fits) and SECURITY.md/CONTRIBUTING.md, which repos inherit automatically.