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. Test descriptive facts for practical discovery cost. Preserve normative instructions even when examples of compliance are visible in code.

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.

Rename or symlink instruction files only when separately requested; trimming does not change their discovery paths.