# 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.

[![Cursor Doctor](assets/logo.png)](assets/logo.png)

## Install

Use directly via `npx`:

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

Or install globally:

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

## Requirements

- Node.js `>=18`
- npm (or `npx`)

## CLI commands

### Generate prescription plan (default)

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

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

```bash
cursor-doctor --project /path/to/project
```

### Audit only

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

### Read a discovered document

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

### Help

```bash
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](.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](.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](.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

```json
{
  "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`:

```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

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

### Audit-only examples

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

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

## Publishing

```bash
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.md)
- [cursor-doctor-prescription-plan.md](cursor-doctor-prescription-plan.md)

### Project docs (`docs/`)

- [docs/ACCESSIBILITY.md](docs/ACCESSIBILITY.md)
- [docs/AGENTS.md](docs/AGENTS.md)
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- [docs/DATA_MODEL.md](docs/DATA_MODEL.md)
- [docs/STYLE.md](docs/STYLE.md)
- [docs/UI_KNOWLEDGE_BASE.md](docs/UI_KNOWLEDGE_BASE.md)

### Cursor skills (`.cursor/skills/`)

- [.cursor/skills/cursor-doctor/SKILL.md](.cursor/skills/cursor-doctor/SKILL.md)
- [.cursor/skills/dependency-management/SKILL.md](.cursor/skills/dependency-management/SKILL.md)
- [.cursor/skills/generate-helium-code/SKILL.md](.cursor/skills/generate-helium-code/SKILL.md)
- [.cursor/skills/restart/SKILL.md](.cursor/skills/restart/SKILL.md)
- [.cursor/skills/ui-knowledge-base/SKILL.md](.cursor/skills/ui-knowledge-base/SKILL.md)

## License

MIT