repository-hygiene

Breaking change: v1.0.0 uses English configuration keys. See docs/MIGRATION.md to rename your auditoria.yaml.

Audit hygiene for Git repositories. Checks for secrets, broken links, missing references, untracked artifacts, GitHub Actions workflow security, and more.

Installation

# ephemeral (recommended — no global install)
uvx repository-hygiene install .

# persistent
uv tool install repository-hygiene
# or
pip install repository-hygiene

Note: after pip install, run repository-hygiene install . in the target repository to provision configuration, CI workflow, and the agent-hygiene-flow skill for the agent roots used by that repository.

To install directly from GitHub (versions not published on PyPI):

pip install git+https://github.com/frederico-mello/repository-hygiene.git

Usage

Initialize repository (install)

repository-hygiene install .             # create auditoria.yaml + workflow + skills
repository-hygiene install --force .     # overwrite existing files
repository-hygiene install --dry-run .   # preview without writing
repository-hygiene install --agents opencode,kilo .  # restrict skill destinations
repository-hygiene install-skill .       # provision skills only

install creates:

• auditoria.yaml — rule configuration and exceptions
• .github/workflows/repository-hygiene.yml — weekly CI workflow
• <agent>/skills/agent-hygiene-flow/ — agent skill for each selected agent root

Skill provisioning is agent-agnostic: by default the skill goes to every supported agent root present in the target repository (.opencode, .kilocode, .kilo, .omp, .hermes), falling back to .opencode when none exists. --agents (comma-separated, with or without the leading dot) restricts the selection explicitly, and --dry-run lists every planned destination. Each destination is evaluated on its own: an existing skill is skipped unless --force, while missing destinations are still provisioned.

Audit

repository-hygiene .                        # text report (stdout) + JSON (.repository-hygiene/)
repository-hygiene . --format json          # JSON only
repository-hygiene . --format sarif         # SARIF only
repository-hygiene . --output audit.txt     # write to file

Pre-commit hook

repository-hygiene install --install-hook .   # install hook on first run

Blocks commits with error-severity findings in staged content. Warnings (warning) are displayed but do not block. To skip:

git commit --no-verify

Exit codes

Configuration

auditoria.yaml at the repository root:

config_version: 1

rules:
  tracked_secrets:
    enabled: true
    severity: error
  broken_internal_links:
    enabled: true
    severity: error
  missing_references:
    enabled: true
    severity: error
  untracked_artifacts:
    enabled: true
    severity: error
  empty_gitkeep_directories:
    enabled: true
    severity: warning
  unreferenced_files:
    enabled: true
    severity: warning
  outdated_documentation:
    enabled: true
    severity: warning
  unintegrated_configurations:
    enabled: true
    severity: warning
  stale_openspec_changes:
    enabled: true
    severity: warning
  insecure_workflows:
    enabled: true
    severity: warning

exceptions:
  tracked_secrets:
    - .secrets.baseline
    - .env.example
  untracked_artifacts:
    - .git
  unreferenced_files:
    - .gitignore
    - Makefile

Rules

GitHub Actions

The generated workflow (repository-hygiene.yml):

• Runs weekly and on push/PR to relevant paths, including every supported agent root (.opencode/, .kilocode/, .kilo/, .omp/, .hermes/)
• Publishes the report to $GITHUB_STEP_SUMMARY
• Creates/updates a consolidated issue with findings (error); closes when clean

Minimum permissions:

permissions:
  contents: read
  issues: write
  pull-requests: read

Migration v0.1 to v0.2

Development

uv pip install -e . pytest
uv run pytest tests_package/

License

MIT