agent-hygiene-linter

Quick start

npx agent-hygiene-linter .

# or install globally
npm install -g agent-hygiene-linter
agent-hygiene-linter /path/to/your/repo

# JSON output for CI pipelines
agent-hygiene-linter . --format json

# Fail CI if score drops below 80
agent-hygiene-linter . --min-score 80

Example output

Agent hygiene score: 92/100
Repo: my-project
Good: 6 | Warning: 1 | Fix now: 0

[warning] Docs directory is thin
  Add a small docs/ tree or module
  notes so the repo is easier to
  navigate.
[good] Agent instructions exist
  Found repo-level instructions.
[good] Commit style is consistent
  14 of 14 commits are conventional.

What it checks

README exists at repo root
AGENTS.md or CLAUDE.md for agent onboarding
docs/ directory has at least one .md file
CHANGELOG.md or docs/changelog.md
build / test / lint / ci npm scripts
Conventional Commits ratio over last 25 commits
Obvious entrypoint (src/index.ts etc.)

Checks and scoring

Finding code	What it looks for	Bucket	Cost
`readme-missing`	Top-level README.md	fix now	−18
`agent-doc-missing`	AGENTS.md or CLAUDE.md	fix now	−18
`docs-shape-missing`	At least one .md under docs/	warning	−8
`changelog-missing`	CHANGELOG.md or docs/changelog.md	warning	−8
`package-scripts-missing`	build / test / lint / ci scripts	warning	−8
`commit-style-weak`	<40% conventional commits (last 25)	fix now	−18
`entrypoint-missing`	src/index.ts, index.ts, or main.ts	warning	−8

CI integration

# .github/workflows/hygiene.yml
- name: Hygiene check
  run: npx agent-hygiene-linter . --min-score 75

Exit 0 when score ≥ threshold. Exit 1 when below. Use --format json to pipe results into a dashboard.