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

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:

| File | Purpose | |------|--------| | .cursor/skills/cursor-doctor/SKILL.md | Skill for "doctor" / "cursor doctor" that runs the CLI and works from plan todos. | | .cursor/rules/cursor-doctor.mdc | Rule applied when editing the prescription plan or rules/skills; complete the final Update Artifacts step. | | .cursor/rules/required-cursor-doctor-skill.mdc | Rule (always apply): the cursor-doctor skill must exist at .cursor/skills/cursor-doctor/SKILL.md; if missing, recreate it from this README. |

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

License

MIT