Open Source Playbook
The router. Your job here is diagnosis before action: figure out what stage the
project is actually in, name the one or two bottlenecks that matter, and hand off to
the specific skills. Do not attempt to do all of open source in one pass.
Step 1 — Read the repo before advising
Never advise from the prompt alone. Spend two minutes on ground truth:
ls -la # top-level hygiene files
git log --oneline -20 # commit style, cadence, bus factor
git shortlog -sn | head -20 # contributor distribution
gh repo view --json stargazerCount,forkCount,openIssues,createdAt,licenseInfo 2>/dev/null
gh issue list --limit 20 --state open 2>/dev/null
gh pr list --limit 20 --state open 2>/dev/null
Then read README.md, CONTRIBUTING.md, .github/workflows/, and the package
manifest. If gh is unavailable or unauthenticated, work from the local clone and say
so — do not fabricate repo statistics.
Step 2 — Locate the stage
| Stage |
Signal |
Bottleneck is almost always |
| 0. Pre-release |
No public repo, or code exists but no license/README |
Positioning and legal basics |
| 1. Published, unknown |
Public, <50 stars, single contributor |
The README and a working install path |
| 2. Discovered |
Traffic arriving, issues opening, nobody contributing code |
Contributor onboarding and docs |
| 3. Growing |
Multiple contributors, PR queue forming |
Automation, review throughput, triage |
| 4. Depended-upon |
Downstream users, breakage complaints |
API stability, release discipline, security |
| 5. Institutional |
Many maintainers, org-scale |
Governance, sustainability, succession |
Most projects are one stage behind where their owner thinks they are. Calibrate on
evidence (issue volume, external PRs, download counts), not ambition.
Step 3 — Route
| The user's goal |
Skill to load |
| Start a repo from nothing |
repo-bootstrap |
| Pick a license, handle CLA/DCO, vendored code |
license-and-legal |
| Nobody understands what this does |
readme-that-converts |
| Docs sprawl, users ask answered questions |
docs-architecture |
| Public interface design, stability guarantees |
api-design |
| Test suite is slow, flaky, or missing |
testing-strategy |
| Review an incoming PR |
code-review |
| Big rewrite without breaking users |
refactor-safely |
| Performance claims, benchmark suite |
performance-benchmarking |
| CI is slow, flaky, or absent |
ci-pipelines |
| Versioning, changelog, publishing |
release-engineering |
| SECURITY.md, provenance, scorecard, CVEs |
supply-chain-security |
| Dependency bloat, upgrade churn |
dependency-hygiene |
| Issue backlog is unmanageable |
issue-triage |
| No one contributes; first PRs stall |
contributor-experience |
| Launch, announce, grow adoption |
launch-and-growth |
| Decision-making, burnout, funding, succession |
governance-and-sustainability |
Load skills on demand, not preemptively. Two skills per response is usually the
ceiling before advice turns to mush.
Step 4 — Sequence, don't dump
Give the user an ordered plan with the smallest viable first step. A useful default
ordering by stage:
- Stage 0→1: license → README → install path that actually works → first release
- Stage 1→2: docs beyond the README → issue templates →
good first issue labels
- Stage 2→3: CI → contributing guide → triage rotation → release automation
- Stage 3→4: semver policy → deprecation policy → security policy → provenance
- Stage 4→5: written governance → funding → maintainer onboarding → succession
The compounding rule
Work that pays off repeatedly beats work that pays off once. Ranked by leverage:
- Automation — CI, releases, linting. Paid once, collected forever.
- Documentation — answers a question once instead of per-user.
- Contributor enablement — turns visitors into a second pair of hands.
- Marketing — real, but decays; it needs 1–3 in place to convert.
A project that grows on marketing alone with none of 1–3 collapses under its own
issue queue. Say this out loud when a user wants to skip to launch.
Honest framing
Skills encode the practices that well-run projects share. They do not manufacture
demand. If a project solves a problem nobody has, the correct advice is to change the
problem, not the README. Say that plainly when it is true — it is the single most
valuable thing a reviewer can tell a maintainer, and the hardest to hear.
Anti-patterns
- Advising without reading the repo. Generic advice is worthless and obvious.
- Boiling the ocean. An 18-point improvement plan gets zero points done.
- Vanity metrics as the goal. Stars follow usefulness; targeting stars directly
produces launch spikes and dead repos. Optimize for the second visit, not the first.
- Process before people. A governance document for a one-person project is
cosplay. Add process when the pain is real.
1---2name: open-source-playbook3description: Entry point and router for open-source work. Use when the user states an open-source goal without naming a specific task — "I want to open source this", "how do I grow this project", "make this repo look professional", "get more contributors", "prepare for v1.0" — or when a request touches several OSS concerns at once. Diagnoses which stage the project is in, then routes to the specific skill(s) that apply and sequences them. Do not use when the user already named a concrete task (writing a README, cutting a release, triaging issues) — go straight to that skill.4---56# Open Source Playbook78The router. Your job here is **diagnosis before action**: figure out what stage the9project is actually in, name the one or two bottlenecks that matter, and hand off to10the specific skills. Do not attempt to do all of open source in one pass.1112## Step 1 — Read the repo before advising1314Never advise from the prompt alone. Spend two minutes on ground truth:1516```bash17ls -la # top-level hygiene files18git log --oneline -20 # commit style, cadence, bus factor19git shortlog -sn | head -20 # contributor distribution20gh repo view --json stargazerCount,forkCount,openIssues,createdAt,licenseInfo 2>/dev/null21gh issue list --limit 20 --state open 2>/dev/null22gh pr list --limit 20 --state open 2>/dev/null23```2425Then read `README.md`, `CONTRIBUTING.md`, `.github/workflows/`, and the package26manifest. If `gh` is unavailable or unauthenticated, work from the local clone and say27so — do not fabricate repo statistics.2829## Step 2 — Locate the stage3031| Stage | Signal | Bottleneck is almost always |32|---|---|---|33| **0. Pre-release** | No public repo, or code exists but no license/README | Positioning and legal basics |34| **1. Published, unknown** | Public, <50 stars, single contributor | The README and a working install path |35| **2. Discovered** | Traffic arriving, issues opening, nobody contributing code | Contributor onboarding and docs |36| **3. Growing** | Multiple contributors, PR queue forming | Automation, review throughput, triage |37| **4. Depended-upon** | Downstream users, breakage complaints | API stability, release discipline, security |38| **5. Institutional** | Many maintainers, org-scale | Governance, sustainability, succession |3940Most projects are one stage behind where their owner thinks they are. Calibrate on41evidence (issue volume, external PRs, download counts), not ambition.4243## Step 3 — Route4445| The user's goal | Skill to load |46|---|---|47| Start a repo from nothing | `repo-bootstrap` |48| Pick a license, handle CLA/DCO, vendored code | `license-and-legal` |49| Nobody understands what this does | `readme-that-converts` |50| Docs sprawl, users ask answered questions | `docs-architecture` |51| Public interface design, stability guarantees | `api-design` |52| Test suite is slow, flaky, or missing | `testing-strategy` |53| Review an incoming PR | `code-review` |54| Big rewrite without breaking users | `refactor-safely` |55| Performance claims, benchmark suite | `performance-benchmarking` |56| CI is slow, flaky, or absent | `ci-pipelines` |57| Versioning, changelog, publishing | `release-engineering` |58| SECURITY.md, provenance, scorecard, CVEs | `supply-chain-security` |59| Dependency bloat, upgrade churn | `dependency-hygiene` |60| Issue backlog is unmanageable | `issue-triage` |61| No one contributes; first PRs stall | `contributor-experience` |62| Launch, announce, grow adoption | `launch-and-growth` |63| Decision-making, burnout, funding, succession | `governance-and-sustainability` |6465Load skills **on demand**, not preemptively. Two skills per response is usually the66ceiling before advice turns to mush.6768## Step 4 — Sequence, don't dump6970Give the user an ordered plan with the smallest viable first step. A useful default71ordering by stage:7273- **Stage 0→1**: license → README → install path that actually works → first release74- **Stage 1→2**: docs beyond the README → issue templates → `good first issue` labels75- **Stage 2→3**: CI → contributing guide → triage rotation → release automation76- **Stage 3→4**: semver policy → deprecation policy → security policy → provenance77- **Stage 4→5**: written governance → funding → maintainer onboarding → succession7879## The compounding rule8081Work that pays off repeatedly beats work that pays off once. Ranked by leverage:82831. **Automation** — CI, releases, linting. Paid once, collected forever.842. **Documentation** — answers a question once instead of per-user.853. **Contributor enablement** — turns visitors into a second pair of hands.864. **Marketing** — real, but decays; it needs 1–3 in place to convert.8788A project that grows on marketing alone with none of 1–3 collapses under its own89issue queue. Say this out loud when a user wants to skip to launch.9091## Honest framing9293Skills encode the practices that well-run projects share. They do not manufacture94demand. If a project solves a problem nobody has, the correct advice is to change the95problem, not the README. Say that plainly when it is true — it is the single most96valuable thing a reviewer can tell a maintainer, and the hardest to hear.9798## Anti-patterns99100- **Advising without reading the repo.** Generic advice is worthless and obvious.101- **Boiling the ocean.** An 18-point improvement plan gets zero points done.102- **Vanity metrics as the goal.** Stars follow usefulness; targeting stars directly103 produces launch spikes and dead repos. Optimize for the second visit, not the first.104- **Process before people.** A governance document for a one-person project is105 cosplay. Add process when the pain is real.
the-open-agent