Cursor Doctor

A Node.js/TypeScript CLI that audits a project for documentation, rules, skills, and related knowledge artifacts. It compares what exists against a reference concept catalog and generates a prescription plan (cursor-doctor-prescription-plan.md) with frontmatter todos for missing or incomplete elements.

Install

Use directly via npx:

npx -y @ajgreyling/cursor-doctor@latest generate

Or install globally:

npm install -g @ajgreyling/cursor-doctor
cursor-doctor generate

Related MCP server: ProofGate

Requirements

• Node.js >=18

• npm (or npx)

CLI commands

Generate prescription plan (default)

cursor-doctor generate [--project <path>] [--out <filename>]

If no command is provided, generate is used by default:

cursor-doctor --project /path/to/project

Audit only

cursor-doctor audit [--project <path>] [--json]

Read a discovered document

cursor-doctor read --file <path> [--project <path>]

Help

cursor-doctor help

Features

• Audits discovered artifacts against a 23-concept catalog across six tiers.

• Detects found, incomplete, and missing concepts with reason details.

• Generates a markdown prescription plan with machine-readable YAML todos.

• Supports read-only JSON audits for CI/reporting workflows.

• Reads project files directly for quick artifact inspection (read command).

README completeness checklist

• project name or title

• setup/install steps

• features or capabilities

• how to run or use

Operational workflow

Use this sequence for a full doctor cycle:

1. Run cursor-doctor generate (or npx -y @ajgreyling/cursor-doctor@latest generate).

2. Open cursor-doctor-prescription-plan.md and work through frontmatter todos in order.

3. Create/update missing artifacts from each todo prompt.

4. Complete the final artifact-sync todo by updating affected docs/rules/skills.

5. Re-run cursor-doctor generate to confirm gaps are resolved.

Doctor command in Cursor

If you want a doctor / cursor doctor skill in Cursor, point that skill to run the CLI (npx -y @ajgreyling/cursor-doctor@latest generate) and then work from the frontmatter todos in the generated plan.

Tracked Cursor artifacts

These files are committed in this repo so the doctor workflow stays consistent:

Concept catalog

The tool checks for 23 concepts in 6 tiers. Artifacts are matched by file patterns (for example README.md, .cursor/rules/*.mdc) and by content signals so differently named files can still satisfy a concept.

• Tier 1 – Foundation: README, project-overview rule, file-locations rule, agent-workflow rule.

• Tier 2 – Architecture: Architecture doc, data model doc, API spec (for example OpenAPI).

• Tier 3 – Development conventions: Backend, frontend, database, and lessons-learnt rules.

• Tier 4 – AI knowledge and skills: AGENTS doc, knowledge-base skill, code-generation skill, operational skills, dependency-management skill.

• Tier 5 – Quality and documentation: Testing spec, accessibility doc, style guide, UI documentation.

• Tier 6 – Infrastructure: MCP config, container config, CI/CD config.

• Final – Artifact sync: “Update Artifacts” is always the final todo.

Project-specific concept profiles

cursor-doctor supports per-project concept customization with this precedence:

1. package.json field: cursorDoctor

2. fallback file: .cursor/cursor-doctor.concepts.yaml

3. built-in default catalog

This makes it possible to enforce domain-specific docs (for example, custom architecture/data-workflow docs) without changing the CLI code.

package.json profile example

{
  "cursorDoctor": {
    "includeDefaultCatalog": true,
    "concepts": [
      {
        "id": "domain-workflows-doc",
        "name": "Domain Workflows",
        "tier": 2,
        "intent": "Domain workflow coverage and execution paths",
        "filePatterns": ["docs/WORKFLOWS.md"],
        "contentSignals": ["workflow", "flowchart", "sequence"],
        "completenessChecks": ["mermaid", "actors", "happy path", "failure path"],
        "generationPrompt": "Create docs/WORKFLOWS.md with mermaid diagrams and workflow coverage."
      }
    ]
  }
}

YAML fallback example (non-Node repos)

Create .cursor/cursor-doctor.concepts.yaml:

includeDefaultCatalog: true
concepts:
  - id: domain-state-machines-doc
    name: Domain State Machines
    tier: 2
    intent: Lifecycle status transitions and guards
    filePatterns:
      - docs/STATE_MACHINES.md
    contentSignals:
      - state machine
      - transition
      - status
    completenessChecks:
      - mermaid
      - states
      - transitions
    generationPrompt: Create docs/STATE_MACHINES.md with mermaid state diagrams.

Override behavior

• Concept IDs are unique keys.

• A project profile concept with an existing ID overrides the built-in concept.

• A new ID appends a new concept.

• The final artifact-sync todo is always enforced.

Build and local run

npm install
npm run build
node dist/index.js generate

Audit-only examples

# Human-readable summary
node dist/index.js audit

# JSON output for automation
node dist/index.js audit --json

Publishing

npm login                # once, if needed
./publish.sh             # build + npm publish
./publish.sh --dry-run   # test without publishing

Documentation index

Core docs

• CURSOR-DOCTOR-PRESCRIPTION.md

• cursor-doctor-prescription-plan.md

Project docs (docs/)

• docs/ACCESSIBILITY.md

• docs/AGENTS.md

• docs/ARCHITECTURE.md

• docs/DATA_MODEL.md

• docs/STYLE.md

• docs/UI_KNOWLEDGE_BASE.md

Cursor skills (.cursor/skills/)

• .cursor/skills/cursor-doctor/SKILL.md

• .cursor/skills/dependency-management/SKILL.md

• .cursor/skills/generate-helium-code/SKILL.md

• .cursor/skills/restart/SKILL.md

• .cursor/skills/ui-knowledge-base/SKILL.md

License

MIT