Agent Context Doctor

agent-context-doctor

`agent-context-doctor` checks whether your agent instruction files are specific, safe, and usable. It catches placeholder content, risky language, contradictions, stale commands, and missing validation guidance before those instructions guide an AI coding agent.

What it is

A small, deterministic CLI (`acd`) that reads the instruction files in your repository — `AGENTS.md`, `CLAUDE.md`, Cursor rules, Copilot instructions, and similar — and reports quality and safety problems with a severity rating and a 0–100 score.

It runs locally, makes no network calls, and is meant to complement human review, not replace it.

Why it exists

AI coding agents follow whatever their instruction files tell them. A file full of `TODO` placeholders, a stray "skip tests if they're slow," or two files that contradict each other will quietly steer an agent toward unsafe or low-quality changes — and nobody notices until the diff lands.

`acd` makes those problems visible in CI or on your machine, deterministically, so you can fix the instructions before they cause trouble.

What it checks

Check	Looks for
Presence	Whether any agent context file exists at all
Placeholder content	Unfilled markers like TODO, TBD, lorem ipsum, or blank scope sections
Risky language	Directives like "skip tests", "bypass auth", or "commit secrets"
Safety boundaries	Whether primary files include ask-before / forbidden-change language for auth, billing, database, and production
Validation commands	Whether instructions tell agents to run tests, lint, or typecheck
Final reporting	Whether instructions describe what to include in a final summary
Command alignment	Commands referenced in instructions that don't match package.json scripts
Contradictions	Conflicting directives across two or more files

Severity and score

Level	Meaning
high