Repo Upgrade
Apply the ten "repo to product" tips to a repository. Companion to repo-audit, which identifies what's missing.
Guiding constraint from the talk: don't implement all ten at once — start with one this week and try the next a month from now. Repo to product is a journey, not a sprint. Default to a focused change, not a 10-item sweep.
Workflow
- Scope it. If the user named a tip (
/repo-upgrade 6, /repo-upgrade devcontainer, "add issue templates"), do that one. If they said "apply the tips" broadly, run repo-audit first — or read an existing REPO-AUDIT.md — and propose the top three. Do not start writing files across all ten.
- Detect the ecosystem before writing anything. Read
../repo-audit/references/ecosystems.md if reachable; otherwise infer from marker files. Every asset in assets/ is a starting point that must be adapted — a Python repo gets a Python CI matrix, not the C++ one.
- Read before writing. Never overwrite
README.md, CONTRIBUTING.md, CHANGELOG.md, or any CI workflow without reading it first and preserving what's there. These files usually contain project-specific content worth keeping.
- Implement using
references/playbooks.md — per-tip steps, decisions, and pitfalls.
- Verify. Lint YAML you generate. If you touched CI, at minimum check the workflow parses. If you touched packaging, run the install-verification test you added.
- Summarize what changed, what the user must fill in (placeholders), and what to do next month.
Safety rules
- Scaffolding new files: go ahead. Issue templates,
devcontainer.json, CONTRIBUTORS.md, docs skeletons, PR templates — these are additive and safe.
- Editing existing CI, build, or packaging files: show the diff and get agreement first. A broken
CMakeLists.txt, pyproject.toml, or workflow costs the user real time. Propose, don't surprise.
- Never invent facts about the project. Don't write a value proposition claiming performance or standards compliance you haven't verified. Leave a clearly marked
<!-- TODO --> and ask.
- Never fabricate contributor names, testimonials, adoption claims, or badge states. Populate
CONTRIBUTORS.md from git log, not from imagination. A badge must point at a workflow that actually exists.
- Don't commit or push unless asked. If the repo has no git history yet, say so rather than running
git init uninvited.
- Respect existing conventions. If the repo uses
.rst, don't switch it to Markdown. If it uses GitLab CI, don't scaffold GitHub Actions.
Assets
assets/ holds templates to copy and adapt:
| Path |
For |
github/ISSUE_TEMPLATE/bug_report.yml |
Tip 3 — repro-link-first bug reports |
github/ISSUE_TEMPLATE/feature_request.yml |
Tip 3 |
github/ISSUE_TEMPLATE/docs_issue.yml |
Tip 3 |
github/ISSUE_TEMPLATE/production_experience.yml |
Tip 10 — surface the silent happy users |
github/ISSUE_TEMPLATE/config.yml |
Tip 3 — route questions to Discussions |
github/pull_request_template.md |
Tip 9 — the "why" field |
github/workflows/matrix-fuzz.yml |
Tip 2 — randomized matrix with reproducible seed |
devcontainer.json |
Tip 6 |
CONTRIBUTING.md |
Tips 6 + 9, includes the AI policy |
CONTRIBUTORS.md |
Tip 9 |
RELEASE_TEMPLATE.md |
Tip 8 |
README_SKELETON.md |
Tip 1 |
Placeholders are written as {{LIKE_THIS}} — every one must be resolved or explicitly raised with the user. Do not ship a file containing an unresolved placeholder without saying so.
Reference
Source notes: TIPS.md in the repo-to-product repo (talk: https://www.youtube.com/watch?v=DWXlyOd_z88).
1---2name: repo-upgrade3description: Implement the 10 "repo to product" tips (Mateusz Pusz) in a repository — scaffold issue templates, dev containers, CONTRIBUTING/CONTRIBUTORS, README pitch, CI matrix with reproducible seeds, Diátaxis docs structure, release announcements, AI-contribution policy, and zero-install demos. Use when the user asks to improve, fix, upgrade, professionalize, or productize a repo's onboarding, docs, packaging, CI, or contributor experience; or says "repo upgrade", "apply the tips", "fix my README", "add issue templates", "add a devcontainer", "make my repo contributor-friendly". Accepts a tip number or name to apply just one. Pair with repo-audit to find what's missing first.4---56# Repo Upgrade78Apply the ten "repo to product" tips to a repository. Companion to `repo-audit`, which identifies what's missing.910**Guiding constraint from the talk:** *don't implement all ten at once — start with one this week and try the next a month from now. Repo to product is a journey, not a sprint.* Default to a focused change, not a 10-item sweep.1112## Workflow13141. **Scope it.** If the user named a tip (`/repo-upgrade 6`, `/repo-upgrade devcontainer`, "add issue templates"), do that one. If they said "apply the tips" broadly, run `repo-audit` first — or read an existing `REPO-AUDIT.md` — and propose the top three. Do not start writing files across all ten.152. **Detect the ecosystem** before writing anything. Read `../repo-audit/references/ecosystems.md` if reachable; otherwise infer from marker files. Every asset in `assets/` is a starting point that must be adapted — a Python repo gets a Python CI matrix, not the C++ one.163. **Read before writing.** Never overwrite `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, or any CI workflow without reading it first and preserving what's there. These files usually contain project-specific content worth keeping.174. **Implement** using `references/playbooks.md` — per-tip steps, decisions, and pitfalls.185. **Verify.** Lint YAML you generate. If you touched CI, at minimum check the workflow parses. If you touched packaging, run the install-verification test you added.196. **Summarize** what changed, what the user must fill in (placeholders), and what to do next month.2021## Safety rules2223- **Scaffolding new files: go ahead.** Issue templates, `devcontainer.json`, `CONTRIBUTORS.md`, docs skeletons, PR templates — these are additive and safe.24- **Editing existing CI, build, or packaging files: show the diff and get agreement first.** A broken `CMakeLists.txt`, `pyproject.toml`, or workflow costs the user real time. Propose, don't surprise.25- **Never invent facts about the project.** Don't write a value proposition claiming performance or standards compliance you haven't verified. Leave a clearly marked `<!-- TODO -->` and ask.26- **Never fabricate contributor names, testimonials, adoption claims, or badge states.** Populate `CONTRIBUTORS.md` from `git log`, not from imagination. A badge must point at a workflow that actually exists.27- **Don't commit or push** unless asked. If the repo has no git history yet, say so rather than running `git init` uninvited.28- **Respect existing conventions.** If the repo uses `.rst`, don't switch it to Markdown. If it uses GitLab CI, don't scaffold GitHub Actions.2930## Assets3132`assets/` holds templates to copy and adapt:3334| Path | For |35|---|---|36| `github/ISSUE_TEMPLATE/bug_report.yml` | Tip 3 — repro-link-first bug reports |37| `github/ISSUE_TEMPLATE/feature_request.yml` | Tip 3 |38| `github/ISSUE_TEMPLATE/docs_issue.yml` | Tip 3 |39| `github/ISSUE_TEMPLATE/production_experience.yml` | Tip 10 — surface the silent happy users |40| `github/ISSUE_TEMPLATE/config.yml` | Tip 3 — route questions to Discussions |41| `github/pull_request_template.md` | Tip 9 — the "why" field |42| `github/workflows/matrix-fuzz.yml` | Tip 2 — randomized matrix with reproducible seed |43| `devcontainer.json` | Tip 6 |44| `CONTRIBUTING.md` | Tips 6 + 9, includes the AI policy |45| `CONTRIBUTORS.md` | Tip 9 |46| `RELEASE_TEMPLATE.md` | Tip 8 |47| `README_SKELETON.md` | Tip 1 |4849Placeholders are written as `{{LIKE_THIS}}` — every one must be resolved or explicitly raised with the user. Do not ship a file containing an unresolved placeholder without saying so.5051## Reference5253Source notes: `TIPS.md` in the repo-to-product repo (talk: https://www.youtube.com/watch?v=DWXlyOd_z88).
breed