🩺 clauctor

Standardize, audit, and sync your CLAUDE.md files against industry best practices.

One command installs a Claude Code skill + slash commands into any project. All intelligence runs through your existing Claude Pro/Max plan — no API key needed.

---

The Problem

Every project's CLAUDE.md gets generated differently — different models, different moods, different structures. You end up with one project calling it "Tech Stack", another calling it "Technology", and a third burying the info inside "Project Overview." Your CLAUDE.md files drift, get stale, and stop following the practices that actually make Claude Code effective.

The Solution

clauctor codifies the industry standard for CLAUDE.md files (compiled from Anthropic's official docs, Builder.io, HumanLayer, and top community patterns) and gives you three commands to enforce it:

• /clauctor:standardize — Retrofit any existing CLAUDE.md to comply with best practices. Normalizes terminology, reorders sections, flags gaps, removes filler.

• /clauctor:sync — Reads your CLAUDE.md plus all project docs (README, specs, PRDs) and updates the CLAUDE.md to reflect your project's current reality.

• /clauctor:audit — Scores your CLAUDE.md against the spec (35-point scale) and outputs a compliance report. Read-only.

---

Quick Start

# In any project directory:
npx clauctor init

That's it. Open Claude Code and the commands are available.

---

What It Installs

your-project/
├── .claude/
│   ├── skills/
│   │   └── clauctor/
│   │       ├── SKILL.md                    # Skill definition
│   │       └── references/
│   │           └── best-practices-spec.md  # The codified standard
│   └── commands/
│       ├── clauctor_standardize.md
│       ├── clauctor_sync.md
│       └── clauctor_audit.md
├── CLAUDE.md  ← snippet appended
└── ...

All files are local to your project. Nothing runs remotely. The skill and commands are just markdown files that Claude Code reads — all reasoning happens on your Pro/Max plan.

---

Commands

npx clauctor init

Installs the skill, commands, and appends an awareness snippet to your root CLAUDE.md. Safe to run multiple times (idempotent).

npx clauctor update

Updates the skill and command files to the latest version. Preserves your CLAUDE.md content — only replaces the doctor's own files.

npx clauctor uninstall

Removes all clauctor files and strips the snippet from your CLAUDE.md. Clean exit.

---

The Standard

The best practices spec enforces:

8 canonical sections in a specific order:

1. Project Overview (1-3 sentences, no filler)
2. Tech Stack (with versions)
3. Architecture (real paths, not aspirations)
4. Development Commands (exact, runnable)
5. Coding Conventions (specific, not duplicating linter rules)
6. Important Context (gotchas that prevent real mistakes)
7. Constraints (hard rules, not preferences)
8. Current Status (optional, kept fresh or removed)

Meta-rules:

• Under 200 lines (ideally under 60)
• Progressive disclosure — reference detailed docs, don't inline them
• No vague instructions ("follow best practices" → rejected)
• No duplication of linter/formatter rules
• Terminology normalized (e.g., "Technology" → "Tech Stack")

The full spec is at templates/references/best-practices-spec.md.

---

Updating