repo-hygiene

name	repo-hygiene
description	Audit and clean up the repository — remove dead files, fix naming inconsistencies, update .gitignore, and ensure the repo is well-organized for OSS contributors. Does NOT modify source code logic.
allowed-tools	Read, Grep, Glob, Bash, Edit, Write, Agent
effort	high

Repository Hygiene

Audit and clean up the repository to keep it well-organized, contributor-friendly, and free of clutter. This skill does NOT modify source code logic — only repository structure, naming, configuration, and documentation.

Checklist

Run through each section below. For each item, check the current state, report findings, and fix issues (with user confirmation for deletions).

---

1. Dead and Generated Files

Look for files that should not be committed to the repository.

# Backup files
find . -name "*.backup" -o -name "*.bak" -o -name "*.orig" -o -name "*~" \
  | grep -v node_modules | grep -v .git/ | grep -v target/

# OS metadata
find . -name ".DS_Store" -o -name "Thumbs.db" -o -name "desktop.ini" \
  | grep -v node_modules | grep -v .git/

# Generated files at root that should be gitignored
ls -la benchmark-results.json .benchmark-files.txt 2>/dev/null

# Empty directories (excluding .git internals)
find . -type d -empty | grep -v node_modules | grep -v .git | grep -v target

Common targets:

• *.backup, *.bak, *.orig files — remove from git
• .DS_Store — add to .gitignore, remove from git
• benchmark-results.json — generated by scripts/bench/run-benchmark.mjs, should be gitignored
• .benchmark-files.txt — generated by benchmark runner, should be gitignored
• Stale fixture directories — only the current commit's fixtures are needed
• Empty npm/ or placeholder directories

Actions:

• Remove dead files: git rm <file>
• For generated files: add to .gitignore, then git rm --cached <file>

---

2. .gitignore Coverage

Read .gitignore and verify it covers all generated/temporary files.

cat .gitignore

Ensure these patterns are present:

# OS
.DS_Store
Thumbs.db

# Editor
*.swp
*.swo
*~

# Rust
/target/
**/*.rs.bk

# Generated
benchmark-results.json
.benchmark-files.txt

# Dependencies
node_modules/
.pnpm-store/

# Build output
/pkg/
/fixtures/

# Docker
.playwright-mcp/

# IDE
.idea/
.vscode/
*.code-workspace

# Backup files
*.backup
*.bak
*.orig

Compare against the actual .gitignore and add missing entries.

---

3. Unused Scripts

For each file in scripts/, verify it is referenced somewhere:

for f in scripts/*; do
  name=$(basename "$f")
  echo "=== $name ==="
  # Check package.json
  grep -l "$name" package.json 2>/dev/null || true
  # Check README
  grep -l "$name" README.md AGENTS.md CLAUDE.md 2>/dev/null || true
  # Check CI workflows
  grep -rl "$name" .github/ 2>/dev/null || true
  # Check other scripts
  grep -rl "$name" scripts/ 2>/dev/null | grep -v "$name" || true
  echo ""
done

Decision criteria:

• Referenced in package.json, CI, or README: Keep
• Useful debugging utility (e.g., compare-parsers.mjs): Keep, but document
• Completely unreferenced and undocumented: Propose removal to the user

---

4. Unused Binaries

Check if binaries declared in Cargo.toml are actually used:

# List declared binaries
grep -A1 '\[\[bin\]\]' Cargo.toml

# Check usage of each binary
for bin in test_reporter benchmark_runner profiler; do
  echo "=== $bin ==="
  grep -r "$bin" package.json .github/ scripts/ README.md AGENTS.md 2>/dev/null || echo "  (not referenced)"
done

Binaries that serve as development tools (profiler, benchmark_runner) are fine even if not in CI — they just need to be documented.

---

5. Naming Consistency

5a. Script naming

All scripts should follow kebab-case with appropriate extensions:

• Shell scripts: *.sh
• Node.js ES modules: *.mjs

ls scripts/

Flag any scripts using camelCase, snake_case, or inconsistent extensions.

5b. Source file naming

All Rust source files should follow snake_case:

# Find non-snake_case .rs files (excluding mod.rs)
find src/ -name "*.rs" | grep -v snake_case_pattern

5c. Test file naming

ls tests/*.rs

All test files should be snake_case.rs.

5d. Directory naming

Directories should be snake_case (Rust convention) or kebab-case (for non-Rust):

find src/ -type d | sort

---

6. Documentation Quality

6a. Redundancy check

Compare README.md, CLAUDE.md, and AGENTS.md:

wc -l README.md CLAUDE.md AGENTS.md 2>/dev/null
# Check if CLAUDE.md is a symlink
ls -la CLAUDE.md

• CLAUDE.md should be the canonical file for AI agent instructions
• README.md should be the canonical file for human contributors
• No information should be duplicated between them (except intentional overlap)

6b. Stale references

Check for references to files/commands that no longer exist:

# Extract referenced file paths from README and check they exist
grep -oP '`[^`]+\.(rs|mjs|sh|json)`' README.md | tr -d '`' | while read f; do
  [ ! -f "$f" ] && echo "MISSING: $f"
done

6c. Contributing guide

For an OSS project, check whether these exist:

• CONTRIBUTING.md — how to contribute
• .github/ISSUE_TEMPLATE/ — issue templates
• .github/PULL_REQUEST_TEMPLATE.md — PR template

If missing, note it but do NOT create them unless the user asks (they may want to write these themselves).

---

7. CI/CD Hygiene

ls .github/workflows/

For each workflow:

• Verify it references valid scripts and commands
• Check for pinned action versions (e.g., actions/checkout@v4, not @main)
• Look for deprecated actions or Node versions

---

8. Dependency Audit

8a. Cargo.toml

# List all dependencies
grep -E '^\w+ =' Cargo.toml | head -40

# Check for unused features
cargo clippy --all-targets --all-features 2>&1 | grep "unused"

Look for:

• Dependencies listed but never imported
• Features enabled but not used (e.g., bumpalo is in Cargo.toml but not used in code)

8b. package.json

cat package.json

Only devDependencies should be present (no dependencies needed for a Rust project). Check if all devDependencies are actually used.

---

9. Build Artifacts in Git

Check if any build artifacts are accidentally committed:

# Large files in git
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print $3, $4}' | sort -rn | head -20

# WASM files in pkg/
ls -lh pkg/*.wasm 2>/dev/null

# Check if pkg/ should be committed
# (If it's published to npm, yes. If it's only a build output, no.)

---

10. Root Directory Cleanliness

The root directory is the first thing a contributor sees. Minimize clutter:

ls -1a | grep -v '^\.\.$' | grep -v '^\.$'

Ideal root contents:

• Source: src/, tests/, benches/, examples/
• Config: Cargo.toml, Cargo.lock, package.json, pnpm-lock.yaml, build.rs
• Docs: README.md, LICENSE, CLAUDE.md
• Git: .git/, .gitignore, .gitmodules, .githooks/
• CI: .github/
• Submodules: svelte/, vite-plugin-svelte/
• Optional: Dockerfile, docker-compose.yml, .devcontainer/
• Optional: docs/, scripts/, fixtures/

Unexpected files at root should be moved or removed.

---

Workflow

When the user invokes /repo-hygiene:

1. Run through sections 1-10 above sequentially
2. For each section, report findings as a checklist:
   • [ok] — no issues found
   • [fix] — issue found and auto-fixable (describe the fix)
   • [ask] — issue found but needs user decision (e.g., delete an unused script?)
3. After the audit, summarize all findings in a table
4. Apply all [fix] items automatically
5. Ask the user about [ask] items, then apply approved fixes
6. Commit the changes: git commit -m "chore: repository cleanup"