A DevRel kit for growing a devtool repo, built the unusual way: its advice was tested against a control group. A 300-repo outcome-blind study found that most "README best practices" don't discriminate winners from losers — and that author reach (corr +0.58 with star velocity) beats every README feature measured (best: +0.35). So this kit scores copy as hygiene, treats distribution as the engine, and ships the study + scripts so you can re-run the method on your own category instead of trusting ours.
The study's own lift table, rendered from data/analysis.json (n=299, no CIs — directional).
- Winner-only "best practices" are survivorship folklore: the bold one-liner value prop appears in 85% of winners — and 97% of losers (lift −0.12). The "open-source X alternative" formula: 0% of both groups.
- What discriminates (AI/LLM devtools, 2025 cohort): an image above the fold (+0.31), a live community (+0.29), a maintained compat matrix (+0.25 for low-follower authors) — mostly symptoms of a seriously-built project, so build the project, don't fake the symptom.
- Full method, lift tables, and limits: STUDY-empirical-validation.md. Every number's source: RESEARCH-CORPUS.md.
| You want to… | Run |
|---|---|
| Check the mechanics that outrank copy (description, topics, homepage, license, npm, mcpName, dead links, star-begging) | python3 tools/preflight.py owner/repo [--npm pkg] |
| Score a README against the 300-repo baseline | python3 tools/score_repo.py owner/repo |
| Publish an npm package without the classic tarball failures | bash tools/npm_preflight.sh /path/to/checkout --require <runtime-path> |
| Track a launch honestly (weekly vitals vs your own baseline) | bash tools/capture_outcomes.sh owner/repo npm-pkg outcomes.jsonl |
| Run a full manual rep (score → fix → gate → log) | run.md — the playbook |
| Actually move stars | distribution.md — wave, warm-up, launch window, cadence, anti-fraud line |
| Re-run the study for YOUR category | study-scripts/ — change Q_BASE, one afternoon, free GitHub API |
Works with (every cell file-verified):
| Piece | Needs |
|---|---|
CLI tools (preflight, score_repo) |
any terminal — gh (authenticated) + Python 3 stdlib |
Study re-run (study-scripts/) |
same — gh + Python 3 stdlib |
| npm pre-flight / outcome capture | adds npm / curl respectively |
| The plugin | Claude Code only — no Cursor, Codex, or Copilot port exists |
| Demo-video generator | Node ≥ 20 + ffmpeg + Playwright (in the target repo) |
No frameworks, no services.
- rubric-v2-empirical.md — the lift-weighted scoring rubric (ceiling-adjusted; anti-fraud disqualifiers). rubric.md is the winner-frequency v1, kept as the worked example of survivorship bias.
- run.md — the manual playbook: mechanics pre-flight → score → improve-or-early-exit → human gate → log (template).
- distribution.md — the half that moves the metric.
- automation-spec.md — the gated ladder (loop → skills → workflow → hooks → measurement), each stage locked behind manual reps. hook-fixtures.md holds the pre-install test cases.
- overlays/instrument/ — a reference brand overlay (voice constraints, lexicon, audience). Bring your own brand by implementing the same three files; overlays tighten, never loosen.
- data/analysis.json — the study's aggregate results (row-level data excluded: it carries repo/author identifiers).
- platform-profile.github.json — a GitHub platform profile (norms, timing, anti-patterns) for content-pipeline use.
One control study: n=299, one category (AI/LLM devtools created 2025), no confidence intervals, tool quality unmeasured — a better hypothesis than folklore, not a law. The strong signals are maturity proxies; gaming them games the detector, not the outcome. Stars are the vanity metric — weight forks/contributors/downloads, classify launches against your own baseline curve, and never buy, beg, or bot a star (the study's fraud-detection sources are in the corpus).
Built by Dikshant Joshi with Claude (the study, the correction of its own survivorship bias, and the adversarial verification passes are documented in the study report). MIT.
The kit is also a Claude Code plugin — same rubric, same tools, wrapped in skills and commands so a rep runs from chat instead of a terminal checklist:
# from a local checkout (works today):
claude plugin marketplace add /path/to/github-growth-kit && claude plugin install github-growth@github-growth
# from GitHub (works after this repo is published):
claude plugin marketplace add joshidikshant/github-growth-kit && claude plugin install github-growth@github-growthFour skills. Two-role discipline is structural: the scorer never rewrites in the same invocation, and the writers never score their own output — each hands off to the other by name.
| Skill | Role |
|---|---|
github-copy-scorer |
Editor — runs the mechanics pre-flight first (mechanics outrank copy), then scores against the 300-repo baseline with a ceiling-adjusted read-out (raw /100 and % of the ceiling the repo can honestly reach — Discord/badge gaps named, never gamed); refuses to rewrite |
readme-first-screen |
Copywriter — above-the-fold only (H1, one-line value prop, badges, hero image, install proximity); a number needs a linked source or it ships as TODO(evidence); never adds a star CTA or an empty Discord |
launch-title-forge |
Title writer — [Name] – one literal sentence, under 80 chars, no outcome-claims the software doesn't deliver |
devrel-rep |
Orchestrator — a full rep per run.md: pre-flight → score → early-exit or improve (max 3 passes) → human gate (the writer never signs their own work) → log |
Four commands. /github-growth:score (pre-flight + score, no rewriting), /github-growth:preflight (mechanics only), /github-growth:capture (weekly vitals snapshot — traffic needs push access, 14-day window), /github-growth:demo-video (drives the generator below).
Hooks. hooks/hooks.json wires the kit's guardrails into tool use; the pre-install test cases live in hook-fixtures.md.
Demo-video generator. demo-video/ is the Playwright + ffmpeg pipeline that recorded the loopback demo clip (this kit's rep-1 target): cue-file choreography so an agent can act mid-recording, a hard network assert so a missed click can't fake success, freeze-detection to cut dead air, optional voiceover mux. Shot-script contract in demo-video/README.md.
Honesty note. This kit scored its own README — first pass failed its own method (28% of ceiling, missing LICENSE); fixed and re-scored to ~86%. This is version 0.1.0, and Gate 2 of the kit's own automation ladder (automation-spec.md) was opened early — at 1 of the 3 manual reps Gate 1 requires, with Gate 2's own loop-run criterion unmet — expect the skills to be revised after reps 2 and 3. The evidence base is unchanged: one control study, n=299, one category (AI/LLM devtools, 2025), no confidence intervals; author reach (corr +0.58) still beats every copy feature measured (+0.35 best). The plugin polishes the hygiene; distribution.md remains the engine.