agents-md-lint

Audit AI agent instruction files by spawning a blind sub-agent that tries to rediscover each documented fact from code search alone. Facts it finds easily → remove. Facts it can't → keep.

This works on any file whose purpose is to give an AI agent context about a codebase: AGENTS.md, CLAUDE.md, CONVENTIONS.md, .cursorrules, or similar. The workflow refers to these collectively as "instruction files."

Modes

Default (rewrite): Produces a report and rewrites the instruction files with only the surviving facts.

Dry-run: Produces the report but does not modify any files. Use this when the user wants to see what would change before committing, or says things like "just show me," "report only," or "what's redundant." Ask which mode the user wants if it's ambiguous.

Workflow

1. Discover and normalize instruction files

Scan the repo for instruction files. Common names: AGENTS.md, CLAUDE.md, CONVENTIONS.md, .cursorrules, .github/copilot-instructions.md. Ask the user if there are others, or if any should be excluded.

CLAUDE.md → AGENTS.md normalization: If a CLAUDE.md exists but no AGENTS.md, rename CLAUDE.md to AGENTS.md and create a symlink CLAUDE.md → AGENTS.md. This keeps AGENTS.md as the canonical name while preserving compatibility with tools that look for CLAUDE.md. If both files already exist as separate files, leave them as-is and audit each independently. Skip this normalization in dry-run mode.