batteryshark Publish ready
Turn a working repository into a coherent public artifact for a stranger deciding whether to trust and use it.
Guardrails
Work from version control on a reviewable branch or equivalent recovery point. If the workspace has no version control, stop and establish one before an aggressive cleanup.
Verify before deleting an ambiguous file. Fixtures, generated inputs, and data files can resemble junk. Run relevant checks after each meaningful batch of removals.
Process
1. Orient
Run bin/publish-ready <repo> and treat the output as leads. Read the README, manifests, entry points, tests, and release machinery. Write a one-sentence private answer to: what is this, and who uses it?
Identify the load-bearing surface before editing: shipped code, real tests and fixtures, license, CI, lockfiles, and any document that defines a public contract.
2. Cut
Remove development detritus, dead code, abandoned scaffolding, redundant docs, stale references, and generated output that belongs in ignore rules. Search for references before deleting anything ambiguous.
Keep one source of truth per topic. Remove obsolete compatibility paths only when repository evidence or explicit scope makes the break safe.
3. Make the layout legible
A new reader should understand the project, audience, quickstart, and directory map in about a minute. Use conventional locations and names. Prefer one strong root README over overlapping orientation documents.
4. Humanize prose
Read references/prose-humanizer.md. Tighten every surviving public document and comment: cut hedges, marketing adjectives, fake contrasts, repetitive summaries, decorative emphasis, and comments that narrate syntax.
5. Prove the repository
- Run the build, tests, linters, formatters, and repository-specific validation that actually exist.
- Execute quickstart commands and documentation examples as written.
- Include an install-by-name command only when the exact package is already published in that registry under an owner-controlled account. Otherwise omit the command; if setup instructions are needed, use the checked-out source. Never document a hypothetical future registry install.
- Check for secrets, environment files, absolute local paths, debt markers, and references to deleted files.
- Confirm that README claims match current behavior.
- Move aspirations to the project's issue tracker instead of presenting them as shipped features.
6. Report
Summarize what was removed, what was rewritten, checks that passed, skipped checks with reasons, and decisions left to the owner. Keep the change reversible and reviewable.
Use agents/reviewer.md for an independent final pass.
Preserve by default
Do not remove licenses, meaningful history, genuine tests and fixtures, CI, ignore rules, lockfiles, or the actual design specification merely to shrink the repository. A smaller broken repository is not publish-ready.