Super Init

super-init

Initialize or audit a project's CLAUDE.md. Less is more — a 50-line CLAUDE.md that Claude actually follows beats a 300-line one it ignores.

Announce at start: "I'm using super-init to scan your project and generate or audit your CLAUDE.md."

Branch Detection

if [ -f ./CLAUDE.md ]; then
  echo "branch=AUDIT"
else
  echo "branch=GENERATE"
fi

GENERATE runs the 9-step generate flow below. AUDIT runs the 8-step audit flow below.

The Golden Rule

For every line you generate, ask: "Would removing this cause Claude to make a mistake?"

If Claude would figure it out from the code anyway — don't include it. CLAUDE.md is for things Claude can't infer.

What to Include vs Exclude

GENERATE branch (no CLAUDE.md present)

Step 1: Detect Tech Stack

cat package.json 2>/dev/null        # Node.js
cat requirements.txt 2>/dev/null     # Python
cat pyproject.toml 2>/dev/null       # Python (PEP 621 / poetry)
cat Cargo.toml 2>/dev/null           # Rust
cat go.mod 2>/dev/null               # Go
cat pom.xml 2>/dev/null              # Java

Extract: language, framework, key dependencies. Only note what's non-obvious.

Step 2: Discover Commands

# Prefer jq when available; fall back to plain-text grep otherwise.
if command -v jq >/dev/null 2>&1; then
  cat package.json 2>/dev/null | jq '.scripts' 2>/dev/null
else
  # jq missing — grep the scripts block as plain text.
  awk '/"scripts"[[:space:]]*:/{flag=1} flag{print} /^[[:space:]]*\}/{if(flag){flag=0; exit}}' package.json 2>/dev/null
fi

# Check for Makefile
cat Makefile 2>/dev/null | grep '^[a-z].*:' | head -10

# Check for justfile, taskfile, etc.
ls Makefile justfile Taskfile.yml .taskfile 2>/dev/null

Only include commands Claude can't guess. If the test command is npm test, skip it. If it's npm run test:unit -- --coverage --bail, include it.

Step 3: Detect Non-Obvious Conventions

Read 3-5 source files to spot patterns:

• Import style (named exports vs default, absolute vs relative paths).
• Component patterns (functional vs class, co-located tests vs separate).
• Naming conventions (if non-standard).
• Any .eslintrc, .prettierrc, tsconfig.json enforcing unusual rules.

Only note conventions that differ from language/framework defaults.

Step 4: Check for Gotchas

# Monorepo?
ls packages/ apps/ modules/ 2>/dev/null

# Custom tooling?
ls scripts/ tools/ bin/ 2>/dev/null

# Environment requirements?
cat .env.example 2>/dev/null
cat .tool-versions 2>/dev/null
cat .nvmrc 2>/dev/null

# Commit message convention.
git log --oneline -10 2>/dev/null

Skip the git log step silently if git is missing or there are no commits.

Step 5: Detect Layout + Pick Template

Apply the auto-detection rules in references/templates.md (monorepo signals → monorepo; package signals → package; minimal-root signals → minimal-root; otherwise → comprehensive-root).

State the chosen template with a one-line rationale, e.g.:

Detected pnpm-workspace.yaml + packages/ at root → using monorepo template.

The user can override at step 7.

Step 6: Draft + Self-Score

Fill the chosen template with scan results. Apply the Golden Rule and the "What NOT to Add" list from references/update-guidelines.md.

Self-score the draft against references/quality-criteria.md (6 criteria, weights 20/20/15/15/15/15, total 100, grade A≥85 / B≥70 / C≥55 / F<55).

Step 7: User Review + Write

Present the draft, the score, and the grade.

Line-budget warning (AT-4). If the draft is over 100 lines:

"Draft is N lines, target is <=100. This is usually a sign of including too much. Type override to proceed anyway, or cut to revise."

The skill does not proceed to write until the user types override (or revises and re-scores under 100). No silent overwrite of the budget.

Approval prompt:

"Here's the generated CLAUDE.md (N lines, grade X). Review it — I've tried to include only things I can't infer from the code. Apply, override-template (minimal-root / comprehensive-root / package / monorepo), or cancel?"

On approval, write ./CLAUDE.md. On cancel, exit cleanly without writing or scaffolding.

Step 8: .claude/rules/ Scaffold (monorepo + opt-in only)

Run this step only if the chosen template was monorepo. On any other template, skip silently.

Prompt:

"This is a monorepo. Want me to scaffold .claude/rules/ with one starter rule per package or app directory? (y/n)"

On y: create .claude/rules/ and one starter rule file per directory directly under any monorepo workspace root. A directory is "detected" when it lives directly under packages/, apps/, or any directory matched by a workspaces glob in package.json / pnpm-workspace.yaml / lerna.json. Both packages/* and apps/* are scaffolded when both exist.

On n: skip; continue to step 9.

Step 9: Onboarding Panel (one-shot, GENERATE-first-run only)

This step runs only on GENERATE (./CLAUDE.md was absent at the start of the run). It is never printed on AUDIT or on any subsequent re-run.

Print:

==========================================
super-init complete
==========================================
File:     ./CLAUDE.md
Lines:    <N>
Template: <template-name>
Grade:    <grade> (<score>/100)
<.claude/rules/ summary, only if scaffolded>

Tips for getting more out of CLAUDE.md:

1. The `#` shortcut: typing `#` at the start of a message stages a memory addition.
2. Organic correction persistence: when Claude is corrected on a project convention, it will offer to persist the correction to the Gotchas section.
3. Hooks vs CLAUDE.md compliance reality: research suggests CLAUDE.md rules are followed roughly 70% of the time. This plugin's hooks (already shipped) provide the deterministic enforcement layer for the rules that need to be hard rules.
4. Re-run /super-init: running the command again later enters AUDIT mode and refreshes the file against the current state of the project.
==========================================

AUDIT branch (existing CLAUDE.md present)

Step 1: Read existing CLAUDE.md

Read ./CLAUDE.md into memory.

Unparseable existing CLAUDE.md. If the read fails or markdown parsing yields no recognizable section structure, present:

"Existing ./CLAUDE.md couldn't be parsed cleanly. Options: (a) back it up to ./CLAUDE.md.bak and re-route to GENERATE, (b) exit. Pick a or b."

On a: cp ./CLAUDE.md ./CLAUDE.md.bak, then rm ./CLAUDE.md, then re-enter the skill (which now sees no CLAUDE.md and routes to GENERATE). On b: exit cleanly.

Step 2: Re-run scan

Run GENERATE steps 1-4 (Detect Tech Stack, Discover Commands, Detect Non-Obvious Conventions, Check for Gotchas).

Step 3: Score against rubric

Score the existing file against references/quality-criteria.md. Report the score and grade.

Step 4: Compute diff

Compute the section-keyed unified-diff per references/update-guidelines.md:

• Stale lines: commands or conventions in the file that no longer match the scan.
• Missing additions: non-obvious commands or gotchas the scan surfaced that aren't in the file.

If the diff is empty:

"No patches needed. Score: /100, Grade: . Exiting."

Exit without writing.

Step 5: Present score + patches

Show the score, grade, and the diff hunks (one per touched section).

Step 6: Per-patch or bulk approval

Per the approval prompt format in references/update-guidelines.md:

• Per-section: [y/n/skip-all] for each touched section.
• Bulk: [Y] to apply every hunk.

Unapproved hunks are dropped.

Step 7: Apply approved patches in place

Apply the approved hunks. Sections the diff did not touch remain untouched. No whole-file overwrite.

Step 8: .claude/rules/ Bootstrap (monorepo + missing + opt-in)

Run this step only if the layout signals monorepo AND ./.claude/rules/ does not exist. On any other layout, or if the directory exists, skip silently.

Prompt:

"This is a monorepo and .claude/rules/ is missing. Want me to scaffold it? (y/n)"

On y: same scaffold as GENERATE step 8. On n: skip.

Do not print the onboarding panel on AUDIT. AT-8 requires it to be GENERATE-first-run only.

Forbidden Writes (AT-10)

The skill writes only to:

• ./CLAUDE.md
• ./.claude/rules/ (only on opt-in monorepo paths)
• ./CLAUDE.md.bak (only on the AUDIT unparseable-fallback path)

The skill never writes to:

• ~/.claude/settings.json
• ./.claude/settings.json (the settings file)
• ./.claude.local.md
• ./.claude/settings.local.json

Configuring the harness is out of scope. The plugin's existing hooks/hooks.json PostToolUseFailure Bash matcher already ships pre-wired; no user-side .claude/settings.json change is required for organic growth to work.

Organic Growth

Persisting Corrections

When the user corrects you about a project convention during normal work (e.g., "No, we use pnpm here, not npm"), offer to persist it:

"Got it — want me to add this to CLAUDE.md so I remember next time?"

Proposed addition to ## Gotchas: - Use pnpm, not npm (no package-lock.json in this project)

If the user agrees, append the line to the Gotchas section of CLAUDE.md. If no Gotchas section exists, create one.

This is a behavioral instruction for all skills, not just super-init. Any time Claude is corrected about something project-specific, it should offer to persist the correction.

Auto-Detecting Failures

A PostToolUseFailure hook fires when commands fail. The hook prompts Claude to consider whether the failure was caused by a project-specific convention that should be recorded:

"PostToolUseFailure": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "prompt",
        "prompt": "A command failed. If this failure was caused by a project-specific convention, setup requirement, or non-obvious configuration that Claude should know about for future sessions, suggest adding a rule to CLAUDE.md's Gotchas section. Only suggest this if the failure reveals something non-obvious — don't suggest adding rules for typos or standard errors."
      }
    ]
  }
]

This block already ships in this plugin's hooks/hooks.json. No user-side .claude/settings.json change is required. This creates a feedback loop: failures → rules → fewer failures.

Anti-Rationalizations

Red Flags

• Generated CLAUDE.md over 100 lines — too verbose, cut ruthlessly.
• Including standard conventions (functional components, ES modules) that Claude knows.
• Including file-by-file descriptions of the codebase.
• No Gotchas section — this is where organic growth happens.
• Never updating CLAUDE.md after generating it — it should be a living document.

Verification

After generating or auditing CLAUDE.md:

• File is under 100 lines
• Every line passes the "would removing this cause a mistake?" test
• Commands section only has non-obvious commands
• Conventions section only has things that differ from defaults
• Gotchas section exists (even if empty) for organic growth
• User has reviewed and approved the content
• Rubric grade >= B for the generated/audited file