Agent Rules Doctor

One-command audit for whether your repo is ready for AI coding agents.

Before you hand a repo to Codex, Claude Code, Cursor, or Copilot, run:

npx agent-rules-doctor audit

AI coding agents often fail because the repo never told them the boring details: setup commands, test commands, generated files, safety boundaries, and project conventions.

agent-rules-doctor checks whether your repo tells agents:

• how to install dependencies
• which tests, build, lint, or typecheck commands matter
• what files are generated or unsafe to touch
• which instruction files exist: AGENTS.md, CLAUDE.md, .cursorrules, and Copilot instructions

Useful when agents keep running the wrong test command, editing generated files, missing project conventions, or failing CI because repo context was scattered.

If this saved you one bad agent run, consider starring the repo so other AI-coding users can find it.

Works With

| Agent surface | Instruction file | | --- | --- | | Codex and agent-compatible CLIs | AGENTS.md | | Claude Code | CLAUDE.md | | Cursor | .cursorrules | | GitHub Copilot | .github/copilot-instructions.md |

Quick Demo

Agent Rules Doctor
==================

Score: 56/100 (2 pass, 6 warn, 1 fail)
Root: /your/repo

Supported instruction files:
  - none found

Detected project evidence:
  - package.json: scripts: build, test

Inferred commands:
  - setup: npm install (package.json)
  - test: npm test (package.json)
  - build: npm run build (package.json)

Checks:
  [fail] Agent instruction file present
        No supported agent instruction file was found.
        Fix: Run `agent-rules-doctor init` to create a starter AGENTS.md.

Then generate a starter file:

npx agent-rules-doctor init
npx agent-rules-doctor audit

Score: 100/100 (9 pass, 0 warn, 0 fail)

Why

AI coding agents are much better when a repo tells them:

• how to install dependencies
• which tests and build checks matter
• where source and generated files live
• what coding conventions to follow
• which commands and files are unsafe to touch

Most repos have this knowledge scattered across README files, package scripts, CI, and human memory. This CLI turns those gaps into a quick report.

Install

No install needed:

npx agent-rules-doctor audit

Or install globally:

npm install -g agent-rules-doctor
agent-rules-doctor audit

Commands

agent-rules-doctor audit
agent-rules-doctor audit --json
agent-rules-doctor audit --markdown
agent-rules-doctor init

audit exits with code 1 when a failing check is present, so it can be used in CI.

init creates AGENTS.md only when it does not already exist. Version 1 never overwrites existing instruction files.

Copy/Paste Into Your Repo

npx agent-rules-doctor audit

If the report says you are missing agent instructions:

npx agent-rules-doctor init
git add AGENTS.md
git commit -m "Add agent instructions"

For CI:

- name: Check agent readiness
  run: npx agent-rules-doctor audit

What It Checks

• Agent instruction file presence
• Package or language metadata
• Setup command documentation
• Test command documentation
• Build, lint, or typecheck guidance
• Project shape evidence
• Coding conventions
• Safety constraints
• Missing context across the above areas

It currently infers common evidence from:

• package.json
• pyproject.toml
• Cargo.toml
• go.mod
• .github/workflows/*.yml
• .github/workflows/*.yaml

Before and After

Before:

No supported agent instruction file was found.

Run:

npx agent-rules-doctor init

After:

# AGENTS.md

## Setup
- Run `npm install` before making changes that need dependencies.

## Test
- Run `npm test` before handing work back.

## Safety
- Do not run destructive git commands unless explicitly requested.

JSON Output

npx agent-rules-doctor audit --json

The JSON shape is stable for scripts:

{
  "schemaVersion": 1,
  "root": "/your/repo",
  "supportedFiles": [],
  "manifests": [],
  "inferredCommands": [],
  "checks": [],
  "score": {
    "passed": 0,
    "warned": 0,
    "failed": 0,
    "total": 0,
    "percent": 100
  }
}

Markdown Output

npx agent-rules-doctor audit --markdown

Use Markdown output when you want to paste the report into a GitHub issue, pull request comment, release note, or CI summary.

## Agent Readiness Report

Score: 56/100 (2 pass, 6 warn, 1 fail)

### Failed Checks
- **Agent instruction file present**: No supported agent instruction file was found.
  - Fix: Run `agent-rules-doctor init` to create a starter AGENTS.md.

Try The Example

npm install
npm run build
node dist/cli.js audit examples/sample-node

The sample intentionally starts at 56/100 because it has package scripts but no agent instruction file. Copy it to a temp directory and run init to see the after state reach 100/100.

Roadmap

• More instruction files for Gemini CLI, Windsurf, Continue, and OpenCode
• Optional doctor fix --dry-run
• CI annotation output
• init --target for Claude, Cursor, and Copilot
• Rule presets for libraries, apps, and monorepos

License

MIT