repo-polish
Repo Polish
A repository's public face is seven artefacts, and they are one job because they all answer the same question for a stranger: what is this, may I use it, and where do I go next. Written separately they contradict each other — a README that says MIT beside a LICENSE that says Apache-2.0, a forge description two rewrites behind the first line of the README.
Every pass runs by default. With any of --readme, --banner, --license, --security, --contributing, --description, --topics, only those. --audit reports without writing. --dry-run stops after the plan table.
| Pass | Artefact | Reference |
|---|---|---|
--readme |
README.md |
readme.md, skeleton.md |
--banner |
the hero image the README opens with | banner.md |
--license |
LICENSE, and the SPDX id agreeing everywhere |
community-files.md |
--security |
SECURITY.md |
community-files.md |
--contributing |
CONTRIBUTING.md |
community-files.md |
--description |
the forge's one-line About text | forge-metadata.md |
--topics |
GitHub topics · GitLab project topics | forge-metadata.md |
One sentence, said once
Before any pass writes, settle the sentence: what this is and what it runs on, in one line under about 120 characters. It is the same text in the README's centred block, in the forge's About field, and in the description of package.json, pyproject.toml, Cargo.toml, or a plugin manifest. Not paraphrases of each other — the same sentence.