repo-hygiene-audit-skill/README.md

repo-hygiene-audit

A Claude Code / Cowork skill that runs a repeatable, read-only hygiene audit across the homelab, pbs, and docker project domains and reports the findings, grouped by remediation phase.

It is the durable, repeatable version of the one-time 2026-05-19/20 documentation/repo audit — Phase 7 of the repo-hygiene-remediation project. The original sweep proved that a one-time pass isn't enough; this skill makes the mechanical part runnable on a cadence so the project folders don't drift back into inconsistency.

What it checks

• Git auditability & ownership — missing/empty .git, dubious ownership, .git-vs-directory owner drift, group drift.
• Secrets & permissions — world-readable / wrong-mode .env files, secrets inlined in compose files.
• Cleanups — uv init leftover stubs, docker-compose.yml → compose.yml naming, stale review docs, herbygitea SSH-alias residue, stray backup dirs.
• Git state — master-vs-main default branch, leftover docs-audit branches, dirty trees, stray worktrees, unpushed commits.
• Docs — missing README/CLAUDE.md, oversized CLAUDE.md (likely README clone).

Full catalogue: repo-hygiene-audit/references/check-catalog.md.

Usage

cd repo-hygiene-audit

# Terminal triage across all default domains:
python scripts/audit.py

# Phase-mapped markdown (pastes into the remediation plan):
python scripts/audit.py --format md -o findings-$(date +%Y%m%d).md

# Machine-readable, for week-over-week diffing:
python scripts/audit.py --format json -o findings-$(date +%Y%m%d).json

No third-party dependencies — python3 (or uv run python) is enough. The script is read-only: it never edits, commits, or pushes the repos it scans.

Useful flags

Flag	Purpose
--format {text,json,md}	Output format (default text)
-o, --output PATH	Write to a file instead of stdout
--config FILE.json	Override the domain map
--scan NAME=PATH	Ad-hoc scan of a directory's children
--only CATEGORY	Restrict to one or more categories
--fail-on SEVERITY	Non-zero exit at/above a severity (automation hook)

Layout

repo-hygiene-audit-skill/
├── README.md                       # this file (human onboarding)
├── CLAUDE.md                       # agent operating guide
├── repo-hygiene-audit/             # the skill itself
│   ├── SKILL.md                    # trigger + workflow
│   ├── scripts/audit.py            # read-only check engine
│   └── references/
│       ├── check-catalog.md        # every check + rationale
│       └── findings-format.md      # output schema + phase mapping
├── repo-hygiene-audit.skill        # packaged bundle (zip of the above)
└── sessions/                       # session notes

Cadence

Currently weekly, triggered manually by Travis (no automation yet). The --fail-on flag is the hook if/when this becomes a scheduled task.