repo-hygiene-action

Imported from rmartz/repo-hygiene-action (AGENTS.md). Install upstream with npx skills add rmartz/repo-hygiene-action. Copyright stays with the author.

Agent guide — repo-hygiene-action

This repo is the composite GitHub Action that runs the @rmartz/repo-hygiene checks in a consuming repo's CI. It holds the CLI as a pinned package.json dependency, wraps it in action.yml, and re-releases itself via semantic-release whenever Dependabot bumps that pin — the chain that ships new check logic to the fleet. It dogfoods itself: CI runs uses: ./ against this repo's own tree. See README.md and the documentation.

Documentation — read it first, maintain it every task

The docs/ bundle is a first-class part of this repo, not an afterthought. On every task:

• Read first. Before changing action.yml, a workflow, or a config, read the relevant docs/ page(s) and this file, so your change stays consistent with what is already documented.
• Extend, correct, and remove in the same PR. If your change adds, alters, or contradicts anything a doc says — an input, the CLI invocation, the release cadence, a consumer step — fix that doc in the same PR. If a doc describes something that no longer exists, delete it. An outdated doc is worse than none.
• Close gaps you find. If you notice an undocumented behavior or a stale page while doing something else, fix it (or, if truly out of scope, note it) — do not leave known-wrong or missing documentation in place.
• Docs follow OKF. Pages under docs/ use Open Knowledge Format frontmatter (type / title / description required) and stay reachable from docs/index.md under the nested-index rule — an index links only same-directory files and a direct child directory's index.md. The okf, okf-index, and docs-links checks enforce this in CI (they run in the Self-hygiene dogfood job). See docs/okf-format.md.

Repository conformance

This repo is held to the shared repository checklist and self-manages its own config: fix conformance gaps directly here, in a PR. Bootstrap (ai-ensure-*) is a one-time new-repo starter, not an ongoing manager — do not defer a fix to a bootstrap re-run, and do not treat a .github/ file as off-limits because bootstrap once seeded it.

• Updates arrive the self-updating way: the merge-safety and bot-automerge callers and (once consumers migrate) this Action's own pin are bumped by Dependabot; CI (incl. PR-title lint + the commit-convention tripwire), labels, the hardened dependabot.yml, and the squash-merge setting are owned here.
• ai-ensure-labels / ai-verify-squash-setting are useful one-shot helpers, but this repo owns its .github/ config going forward.

Common commands

npm ci                 # install deps (needs GitHub Packages auth for @rmartz/*)
npm run format:check   # prettier --check .
npm run format         # prettier --write .

There is no build/test suite — the check logic lives in @rmartz/repo-hygiene. This repo's real test is the CI Self-hygiene (dogfood) job, which runs the local action (uses: ./) against this tree; run the checks the same way the job does, or open a PR, to verify a change.

Releases

Automated via semantic-release (.releaserc.json): a merge to main cuts the git tag + GitHub Release. It publishes nothing and commits nothing back (no @semantic-release/npm, no @semantic-release/git), so the built-in GITHUB_TOKEN suffices — no PAT. chore(deps) maps to a patch release so a Dependabot bump of @rmartz/repo-hygiene ships a new Action version. PR titles are Conventional Commits and the repo squash-merges using the PR title, so a non-conventional title makes semantic-release skip the release.

Worktrees & PRs

• Work in a dedicated worktree under .git-worktrees/ (ai-new-worktree), never on main in the root checkout. Run npm ci in a fresh worktree.
• PR titles must be Conventional Commits (feat:, fix:, docs:, chore:, ci:, …). Render PR/issue numbers as full Markdown links in chat and agent output (e.g. [#12](https://github.com/rmartz/repo-hygiene-action/pull/12)), never a bare #12.

Agent directive files

• AGENTS.md is the single source of truth for a directory's agent instructions — author directives here, never in CLAUDE.md.
• Every AGENTS.md has a companion CLAUDE.md in the same directory (a bare wrapper whose only content is @AGENTS.md), enforced by the md-pairing check. These live at the repo root, outside docs/, so they are not pulled into the OKF bundle.