italixcs/repo-cleaner

Repo Cleaner

Make a good project's purpose, proof, and first useful action easy to find. Improve the repository surface while preserving application behavior.

1. Establish the brief

• Identify repository, audience, desired outcome, language, and audit versus implementation. Reuse authorization already given.
• Read applicable instructions, README, linked guides, license, package/skill manifests, examples, assets, and current GitHub metadata. Inspect source only as needed to verify claims and commands.
• Inspect the worktree and preserve unrelated changes, the existing license, and attribution. Keep visibility unchanged unless a visibility change is explicitly authorized.
• Ask focused questions about missing facts or consequential choices: audience, conflicting branding, unavailable access, uncertain installation, or a meaningful rebrand. Resolve routine layout choices from the project. Continue independent work while waiting; do not invent facts to avoid asking.
• Use assets/repo-brief.md if a working brief helps; do not add it to every target repo.

2. Audit the reader's path

Read references/audit-and-validation.md. Trace discovery → first screen → evidence → installation → first success → deeper help.

List the few highest-impact gaps with evidence and priority. Separate factual problems from taste choices. Include clutter to remove. Distinguish missing information from information unavailable to your tools. For audit-only work, return findings and concrete recommendations without editing files or settings.

3. Build a coherent presentation

Read references/readme-and-visuals.md. Default to GitHub-native document styling, standard flat badges, ordinary navigation links, and project-specific proof. Do not reuse an author’s personal profile aesthetic unless requested. Read references/readme-patterns.md when choosing a structure or learning from reference repositories. Choose a direction suited to the project, then implement the smallest complete set of assets and documents that makes it understandable and usable.

• Lead with a specific promise, useful visual proof, and a clear first action. Keep essential information as real text.
• Add a banner only when useful; prefer a concrete task, actual output, or useful showcase over decorative branding; capture screenshots from actual outputs. Label concepts, fixtures, reconstructions, and local previews accurately.
• Add a restrained badge row with working destinations and substantiated claims.
• Keep the shortest verified installation and usage example in the README. Link longer platform guides, troubleshooting, and examples without duplicating them.
• Organize public docs and assets without moving application source or changing runtime/build behavior. Update links when moving documentation.
• Match documentation depth to the project. Remove generic marketing copy, repeated taglines, forced feature tables, filler sections, badge walls, decorative diagrams, and empty folder hierarchies. Keep the project’s specific voice.

For skill repos, verify the installable folder includes SKILL.md and every referenced resource. Separate that package from public marketing docs. Document exact discovery paths per host, invocation examples, prerequisites, and tool requirements. State whether each route was runtime-tested, checked against host documentation, or only manually usable. Do not infer a plugin, marketplace listing, or universal agent support from a plain skill folder.

4. Improve discovery with truthful metadata

Read references/github-discovery.md. Propose concise About text, a useful real homepage when available, evidence-backed topics, and a social preview asset. Verify current GitHub limits before applying them.

Apply authorized settings with suitable tools, preserving relevant existing values. If tools lack an operation, prepare exact values and the settings link. Separate applied, prepared, and blocked. A committed metadata file or social image does not configure GitHub. Never change visibility, contact others, or submit promotional listings without authorization.

5. Verify and hand off

Validate the reader path with the audit reference: links and anchors, images, safe quick start, truthful badges and compatibility, desktop/mobile, light/dark, final diff, and settings read-back. Report tool or network limits explicitly. Save source assets so later updates remain practical.

Commit or push only when authorized and follow the target repo's workflow. Confirm destination and final revision. Summarize changes, verification, unapplied settings, and the few remaining actions. Do not promise traffic, stars, ranking, or untested support.