claude-prism 0.1.0

package/lib/installer.mjs

@@ -0,0 +1,439 @@
+/**
+ * claude-prism — Installer
+ * Handles init, check, update, uninstall
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync, readdirSync, renameSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { tmpdir } from 'os';
+import { detectOmc } from './omc.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+
+/**
+ * Initialize prism in a project
+ * @param {string} projectDir - Project root
+ * @param {Object} options
+ * @param {string} options.language - 'en' | 'ko'
+ * @param {boolean} options.hooks - Install enforcement hooks
+ */
+export async function init(projectDir, options = {}) {
+  const { language = 'en', hooks = true } = options;
+
+  // 1. Create directories
+  const claudeDir = join(projectDir, '.claude');
+  const hooksDir = join(claudeDir, 'hooks');
+
+  // 2. Copy namespaced slash commands
+  const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
+  mkdirSync(nsCommandsDir, { recursive: true });
+
+  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md'];
+  for (const cmd of commandFiles) {
+    copyFileSync(
+      join(TEMPLATES_DIR, 'commands', 'claude-prism', cmd),
+      join(nsCommandsDir, cmd)
+    );
+  }
+
+  // 3. Copy hooks (optional)
+  if (hooks) {
+    mkdirSync(hooksDir, { recursive: true });
+
+    // Copy runner scripts (executable wrappers Claude Code calls)
+    const runnersDir = join(TEMPLATES_DIR, 'runners');
+    copyFileSync(join(runnersDir, 'commit-guard.mjs'), join(hooksDir, 'commit-guard.mjs'));
+    copyFileSync(join(runnersDir, 'debug-loop.mjs'), join(hooksDir, 'debug-loop.mjs'));
+    copyFileSync(join(runnersDir, 'test-tracker.mjs'), join(hooksDir, 'test-tracker.mjs'));
+    copyFileSync(join(runnersDir, 'scope-guard.mjs'), join(hooksDir, 'scope-guard.mjs'));
+
+    // Copy rule logic files
+    const rulesDestDir = join(claudeDir, 'rules');
+    mkdirSync(rulesDestDir, { recursive: true });
+    const hooksSourceDir = join(__dirname, '..', 'hooks');
+    copyFileSync(join(hooksSourceDir, 'commit-guard.mjs'), join(rulesDestDir, 'commit-guard.mjs'));
+    copyFileSync(join(hooksSourceDir, 'debug-loop.mjs'), join(rulesDestDir, 'debug-loop.mjs'));
+    copyFileSync(join(hooksSourceDir, 'test-tracker.mjs'), join(rulesDestDir, 'test-tracker.mjs'));
+    copyFileSync(join(hooksSourceDir, 'scope-guard.mjs'), join(rulesDestDir, 'scope-guard.mjs'));
+
+    // Copy lib dependencies (adapter + state + config + utils)
+    const libDestDir = join(claudeDir, 'lib');
+    mkdirSync(libDestDir, { recursive: true });
+    const libSourceDir = join(__dirname);
+    for (const file of ['adapter.mjs', 'state.mjs', 'config.mjs', 'utils.mjs']) {
+      copyFileSync(join(libSourceDir, file), join(libDestDir, file));
+    }
+
+    // Merge settings.json
+    mergeSettings(claudeDir);
+  }
+
+  // 4. Inject rules into CLAUDE.md
+  injectRules(projectDir, language);
+
+  // 5. Create .claude-prism.json config
+  const configPath = join(projectDir, '.claude-prism.json');
+  if (!existsSync(configPath)) {
+    writeFileSync(configPath, JSON.stringify({
+      language,
+      hooks: {
+        'commit-guard': { enabled: true, maxTestAge: 300 },
+        'debug-loop': { enabled: true, warnAt: 3, blockAt: 5 },
+        'test-tracker': { enabled: true },
+        'scope-guard': { enabled: true, warnAt: 4, blockAt: 7, agentWarnAt: 8, agentBlockAt: 12 }
+      }
+    }, null, 2) + '\n');
+  }
+}
+
+/**
+ * Check installation status
+ * @param {string} projectDir
+ * @returns {{ commands: boolean, rules: boolean, hooks: boolean, config: boolean, ok: boolean }}
+ */
+export function check(projectDir) {
+  const claudeDir = join(projectDir, '.claude');
+
+  const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
+  const commands = existsSync(join(nsCommandsDir, 'prism.md'))
+    && existsSync(join(nsCommandsDir, 'checkpoint.md'))
+    && existsSync(join(nsCommandsDir, 'plan.md'))
+    && existsSync(join(nsCommandsDir, 'help.md'));
+
+  const claudeMdPath = join(projectDir, 'CLAUDE.md');
+  const rules = existsSync(claudeMdPath)
+    && readFileSync(claudeMdPath, 'utf8').includes('<!-- PRISM:START -->');
+
+  const hooks = existsSync(join(claudeDir, 'hooks', 'commit-guard.mjs'))
+    && existsSync(join(claudeDir, 'hooks', 'debug-loop.mjs'))
+    && existsSync(join(claudeDir, 'hooks', 'test-tracker.mjs'))
+    && existsSync(join(claudeDir, 'hooks', 'scope-guard.mjs'));
+
+  const config = existsSync(join(projectDir, '.claude-prism.json'));
+
+  return {
+    commands,
+    rules,
+    hooks,
+    config,
+    ok: commands && rules && config
+  };
+}
+
+/**
+ * Uninstall prism from a project
+ * @param {string} projectDir
+ */
+export function uninstall(projectDir) {
+  const claudeDir = join(projectDir, '.claude');
+
+  // 1. Remove PRISM block from CLAUDE.md
+  const claudeMdPath = join(projectDir, 'CLAUDE.md');
+  if (existsSync(claudeMdPath)) {
+    const content = readFileSync(claudeMdPath, 'utf8');
+    const startMarker = '<!-- PRISM:START -->';
+    const endMarker = '<!-- PRISM:END -->';
+    if (content.includes(startMarker) && content.includes(endMarker)) {
+      const before = content.slice(0, content.indexOf(startMarker));
+      const after = content.slice(content.indexOf(endMarker) + endMarker.length);
+      writeFileSync(claudeMdPath, (before + after).replace(/\n{3,}/g, '\n\n').trim() + '\n');
+    }
+  }
+
+  // 2. Remove namespaced commands directory
+  const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
+  if (existsSync(nsCommandsDir)) rmSync(nsCommandsDir, { recursive: true });
+
+  // 2b. Remove legacy flat commands (migration cleanup)
+  for (const cmd of ['prism.md', 'checkpoint.md']) {
+    const p = join(claudeDir, 'commands', cmd);
+    if (existsSync(p)) rmSync(p);
+  }
+
+  // 3. Remove prism hooks
+  for (const hook of ['commit-guard.mjs', 'debug-loop.mjs', 'test-tracker.mjs', 'scope-guard.mjs']) {
+    const p = join(claudeDir, 'hooks', hook);
+    if (existsSync(p)) rmSync(p);
+  }
+
+  // 4. Remove rules/ and lib/ directories
+  const rulesDir = join(claudeDir, 'rules');
+  if (existsSync(rulesDir)) rmSync(rulesDir, { recursive: true });
+  const libDir = join(claudeDir, 'lib');
+  if (existsSync(libDir)) rmSync(libDir, { recursive: true });
+
+  // 5. Clean prism hooks from settings.json
+  const settingsPath = join(claudeDir, 'settings.json');
+  if (existsSync(settingsPath)) {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    if (settings.hooks) {
+      for (const [event, hookList] of Object.entries(settings.hooks)) {
+        settings.hooks[event] = hookList.filter(
+          h => !h.hooks?.some(hh => hh.command?.includes('commit-guard') || hh.command?.includes('debug-loop') || hh.command?.includes('test-tracker') || hh.command?.includes('scope-guard'))
+        );
+        if (settings.hooks[event].length === 0) delete settings.hooks[event];
+      }
+    }
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  // 6. Remove .claude-prism.json and legacy .prism.json
+  const configPath = join(projectDir, '.claude-prism.json');
+  if (existsSync(configPath)) rmSync(configPath);
+  const legacyConfigPath = join(projectDir, '.prism.json');
+  if (existsSync(legacyConfigPath)) rmSync(legacyConfigPath);
+}
+
+/**
+ * Update prism — re-install using existing config
+ * @param {string} projectDir
+ */
+export async function update(projectDir) {
+  // Migration: rename .prism.json to .claude-prism.json
+  const oldConfigPath = join(projectDir, '.prism.json');
+  const newConfigPath = join(projectDir, '.claude-prism.json');
+  if (existsSync(oldConfigPath) && !existsSync(newConfigPath)) {
+    renameSync(oldConfigPath, newConfigPath);
+  }
+
+  const configPath = newConfigPath;
+  let language = 'en';
+  let hooks = true;
+
+  if (existsSync(configPath)) {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    language = config.language || 'en';
+    hooks = config.hooks?.['commit-guard']?.enabled !== false;
+  }
+
+  // Migration: remove legacy flat commands before re-init
+  const claudeDir = join(projectDir, '.claude');
+  for (const cmd of ['prism.md', 'checkpoint.md']) {
+    const p = join(claudeDir, 'commands', cmd);
+    if (existsSync(p)) rmSync(p);
+  }
+
+  // Migration: remove deprecated namespaced commands
+  for (const cmd of ['understand.md']) {
+    const p = join(claudeDir, 'commands', 'claude-prism', cmd);
+    if (existsSync(p)) rmSync(p);
+  }
+
+  // Remove old config so init creates a fresh one
+  if (existsSync(configPath)) rmSync(configPath);
+
+  await init(projectDir, { language, hooks });
+}
+
+/**
+ * Diagnose installation issues with actionable fix suggestions
+ * @param {string} projectDir
+ * @param {Object} [options]
+ * @param {string} [options.homeDir] - Override home dir (for testing)
+ * @returns {{ healthy: boolean, issues: string[], fixes: string[], omc: Object }}
+ */
+export function doctor(projectDir, options = {}) {
+  const claudeDir = join(projectDir, '.claude');
+  const issues = [];
+  const fixes = [];
+
+  // Check namespaced commands
+  const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
+  const expectedCommands = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md'];
+  for (const cmd of expectedCommands) {
+    if (!existsSync(join(nsCommandsDir, cmd))) {
+      issues.push(`Missing command: claude-prism/${cmd}`);
+      fixes.push('Run `prism update` to restore missing files');
+    }
+  }
+
+  // Check for legacy flat commands (need migration)
+  for (const cmd of ['prism.md', 'checkpoint.md']) {
+    if (existsSync(join(claudeDir, 'commands', cmd))) {
+      issues.push(`Legacy command found: ${cmd} (needs migration to namespace)`);
+      fixes.push('Run `prism update` to migrate to namespaced commands');
+    }
+  }
+
+  // Check hooks
+  for (const hook of ['commit-guard.mjs', 'debug-loop.mjs', 'test-tracker.mjs', 'scope-guard.mjs']) {
+    if (!existsSync(join(claudeDir, 'hooks', hook))) {
+      issues.push(`Missing hook: ${hook}`);
+      fixes.push('Run `prism update` to restore missing files');
+    }
+  }
+
+  // Check CLAUDE.md
+  const claudeMdPath = join(projectDir, 'CLAUDE.md');
+  if (!existsSync(claudeMdPath)) {
+    issues.push('CLAUDE.md not found');
+    fixes.push('Run `prism update` to regenerate CLAUDE.md rules');
+  } else {
+    const content = readFileSync(claudeMdPath, 'utf8');
+    if (!content.includes('<!-- PRISM:START -->')) {
+      issues.push('CLAUDE.md missing PRISM rules block');
+      fixes.push('Run `prism update` to re-inject rules');
+    }
+  }
+
+  // Check config
+  if (!existsSync(join(projectDir, '.claude-prism.json'))) {
+    issues.push('Missing .claude-prism.json config');
+    fixes.push('Run `prism init` to create config');
+  }
+
+  // Check for legacy .prism.json
+  if (existsSync(join(projectDir, '.prism.json'))) {
+    issues.push('Legacy .prism.json found (needs migration to .claude-prism.json)');
+    fixes.push('Run `prism update` to migrate');
+  }
+
+  // Check rules/ and lib/
+  if (!existsSync(join(claudeDir, 'rules'))) {
+    issues.push('Missing .claude/rules/ directory');
+    fixes.push('Run `prism update` to restore');
+  }
+  if (!existsSync(join(claudeDir, 'lib'))) {
+    issues.push('Missing .claude/lib/ directory');
+    fixes.push('Run `prism update` to restore');
+  }
+
+  // Deduplicate fixes
+  const uniqueFixes = [...new Set(fixes)];
+
+  // Detect OMC
+  const omc = detectOmc(options.homeDir);
+
+  return {
+    healthy: issues.length === 0,
+    issues,
+    fixes: uniqueFixes,
+    omc
+  };
+}
+
+/**
+ * Show installation statistics
+ * @param {string} projectDir
+ * @param {Object} [options]
+ * @param {string} [options.homeDir] - Override home dir (for testing)
+ * @returns {{ version: string, language: string, hooks: Object, planFiles: number, omc: Object }}
+ */
+export function stats(projectDir, options = {}) {
+  // Read version from package.json
+  const pkgPath = join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+
+  // Read config
+  const configPath = join(projectDir, '.claude-prism.json');
+  let language = 'en';
+  let hookConfig = {};
+
+  if (existsSync(configPath)) {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    language = config.language || 'en';
+    if (config.hooks) {
+      for (const [name, cfg] of Object.entries(config.hooks)) {
+        hookConfig[name] = cfg.enabled !== false;
+      }
+    }
+  }
+
+  // Count plan files
+  let planFiles = 0;
+  const plansDir = join(projectDir, 'docs', 'plans');
+  if (existsSync(plansDir)) {
+    planFiles = readdirSync(plansDir).filter(f => f.endsWith('.md')).length;
+  }
+
+  // Detect OMC
+  const omc = detectOmc(options.homeDir);
+
+  return {
+    version: pkg.version,
+    language,
+    hooks: hookConfig,
+    planFiles,
+    omc
+  };
+}
+
+/**
+ * Reset hook state (clear edit counters, test timestamps)
+ * @returns {boolean}
+ */
+export function reset() {
+  const stateRoot = join(tmpdir(), '.prism');
+  if (existsSync(stateRoot)) {
+    rmSync(stateRoot, { recursive: true });
+  }
+  return true;
+}
+
+// ─── internal helpers ───
+
+function injectRules(projectDir, language) {
+  const claudeMdPath = join(projectDir, 'CLAUDE.md');
+  const rulesFile = `rules.${language}.md`;
+  const rulesPath = join(TEMPLATES_DIR, rulesFile);
+
+  if (!existsSync(rulesPath)) {
+    // Fallback to English
+    const fallback = join(TEMPLATES_DIR, 'rules.en.md');
+    if (!existsSync(fallback)) return;
+  }
+
+  const rules = readFileSync(existsSync(rulesPath) ? rulesPath : join(TEMPLATES_DIR, 'rules.en.md'), 'utf8');
+
+  let existing = '';
+  if (existsSync(claudeMdPath)) {
+    existing = readFileSync(claudeMdPath, 'utf8');
+  }
+
+  // Replace existing PRISM block or append
+  const startMarker = '<!-- PRISM:START -->';
+  const endMarker = '<!-- PRISM:END -->';
+
+  if (existing.includes(startMarker) && existing.includes(endMarker)) {
+    const before = existing.slice(0, existing.indexOf(startMarker));
+    const after = existing.slice(existing.indexOf(endMarker) + endMarker.length);
+    writeFileSync(claudeMdPath, before + rules + after);
+  } else {
+    writeFileSync(claudeMdPath, existing + '\n' + rules);
+  }
+}
+
+function mergeSettings(claudeDir) {
+  const settingsPath = join(claudeDir, 'settings.json');
+  const templatePath = join(TEMPLATES_DIR, 'settings.json');
+
+  const template = JSON.parse(readFileSync(templatePath, 'utf8'));
+
+  if (existsSync(settingsPath)) {
+    const existing = JSON.parse(readFileSync(settingsPath, 'utf8'));
+
+    // Merge hooks arrays by event type
+    if (!existing.hooks) existing.hooks = {};
+    for (const [event, hookList] of Object.entries(template.hooks)) {
+      if (!existing.hooks[event]) {
+        existing.hooks[event] = hookList;
+      } else {
+        // Add prism hooks that don't already exist
+        for (const hook of hookList) {
+          const alreadyExists = existing.hooks[event].some(
+            h => h.hooks?.[0]?.command === hook.hooks?.[0]?.command
+          );
+          if (!alreadyExists) {
+            existing.hooks[event].push(hook);
+          }
+        }
+      }
+    }
+
+    writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n');
+  } else {
+    writeFileSync(settingsPath, JSON.stringify(template, null, 2) + '\n');
+  }
+}

package/lib/omc.mjs

@@ -0,0 +1,38 @@
+/**
+ * claude-prism — OMC (oh-my-claudecode) Detection
+ * Detects OMC installation and extracts version info
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+/**
+ * Detect oh-my-claudecode installation
+ * @param {string} [homeDir] - Override home directory (for testing)
+ * @returns {{ detected: boolean, version: string|null }}
+ */
+export function detectOmc(homeDir) {
+  const home = homeDir || homedir();
+  const claudeMdPath = join(home, '.claude', 'CLAUDE.md');
+
+  if (!existsSync(claudeMdPath)) {
+    return { detected: false, version: null };
+  }
+
+  try {
+    const content = readFileSync(claudeMdPath, 'utf8');
+
+    if (!content.includes('<!-- OMC:START -->')) {
+      return { detected: false, version: null };
+    }
+
+    // Extract version from "Unified Agents (vX.Y.Z)" pattern
+    const versionMatch = content.match(/\(v(\d+\.\d+\.\d+)\)/);
+    const version = versionMatch ? versionMatch[1] : null;
+
+    return { detected: true, version };
+  } catch {
+    return { detected: false, version: null };
+  }
+}

package/lib/state.mjs

@@ -0,0 +1,52 @@
+/**
+ * claude-prism — State Management
+ * File-based state storage for hook evaluation
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+const STATE_ROOT = join(tmpdir(), '.prism');
+
+export function getStateDir(sessionId, agentId) {
+  const key = agentId && agentId !== 'default' ? `${sessionId}-${agentId}` : sessionId;
+  const dir = join(STATE_ROOT, key);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+export function readState(stateDir, key) {
+  const file = join(stateDir, key);
+  if (!existsSync(file)) return null;
+  try {
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(stateDir, key, value) {
+  writeFileSync(join(stateDir, key), value, { mode: 0o600 });
+}
+
+export function readJsonState(stateDir, key) {
+  const raw = readState(stateDir, key);
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function writeJsonState(stateDir, key, value) {
+  writeState(stateDir, key, JSON.stringify(value));
+}
+
+export function incrementCounter(stateDir, key) {
+  const current = parseInt(readState(stateDir, key) || '0', 10) || 0;
+  const next = current + 1;
+  writeState(stateDir, key, String(next));
+  return next;
+}

package/lib/utils.mjs

@@ -0,0 +1,8 @@
+/**
+ * claude-prism — Shared Utilities
+ */
+
+export function sanitizeId(id) {
+  if (!id || typeof id !== 'string') return 'default';
+  return id.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 128) || 'default';
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "claude-prism",
+  "version": "0.1.0",
+  "description": "AI coding problem decomposition tool — Understand, Decompose, Execute, Checkpoint.",
+  "type": "module",
+  "bin": {
+    "prism": "./bin/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "claude-code",
+    "tdd",
+    "decomposition",
+    "methodology"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "hooks/",
+    "templates/",
+    "README.md",
+    "README.ko.md"
+  ],
+  "author": "lazysaturday91",
+  "license": "MIT"
+}

package/templates/commands/claude-prism/checkpoint.md

@@ -0,0 +1,34 @@
+# /claude-prism:checkpoint — Progress Check
+
+When this command is invoked:
+
+1. **Read the plan file** from `docs/plans/` (most recent matching file)
+2. **Check completed tasks** (marked with [x] in the plan)
+3. **Report current status** using this standard format:
+
+   ### Changes
+
+   | Item | Before | After |
+   |------|--------|-------|
+   | [what changed] | [old behavior/state] | [new behavior/state] |
+
+   ### Verification
+
+   | Check | Result |
+   |-------|--------|
+   | TypeScript | ✅/❌ [details] |
+   | Tests | ✅/❌ [pass count] |
+   | Lint | ✅/❌ or N/A |
+
+   ### Progress
+
+   - Batches complete: N/M
+   - Current batch: [name] — [X/Y tasks done]
+   - Remaining: [batch names]
+   - Blockers: [any issues encountered]
+
+4. **Show summary**:
+   - Files created/modified so far
+   - Tests added and their status
+   - Commits made
+5. **Ask**: "Continue with the current plan, adjust, or stop?"

package/templates/commands/claude-prism/doctor.md

@@ -0,0 +1,42 @@
+# /claude-prism:doctor — Installation Diagnostics
+
+When this command is invoked, check all components of the prism installation:
+
+## Checks
+
+1. **CLAUDE.md**: Does it contain `<!-- PRISM:START -->` marker?
+2. **Config**: Does `.claude-prism.json` exist? Is it valid JSON?
+3. **Commands**: Do these files exist in `.claude/commands/claude-prism/`?
+   - prism.md, checkpoint.md, plan.md, doctor.md, stats.md, help.md
+4. **Hooks**: Do these files exist in `.claude/hooks/`?
+   - commit-guard.mjs, debug-loop.mjs, test-tracker.mjs, scope-guard.mjs
+5. **Rules**: Do these files exist in `.claude/rules/`?
+   - commit-guard.mjs, debug-loop.mjs, test-tracker.mjs, scope-guard.mjs
+6. **Lib**: Do these files exist in `.claude/lib/`?
+   - adapter.mjs, state.mjs, config.mjs, utils.mjs
+7. **Settings**: Does `.claude/settings.json` contain prism hook registrations?
+8. **Legacy**: Are there old flat commands (`/prism`, `/checkpoint`) that need migration?
+
+## Report Format
+
+```
+🌈 claude-prism doctor
+
+  CLAUDE.md:   ✅ PRISM rules present
+  Config:      ✅ .claude-prism.json valid
+  Commands:    ✅ 7/7 installed
+  Hooks:       ✅ 4/4 installed
+  Rules:       ✅ 4/4 installed
+  Lib:         ✅ 4/4 installed
+  Settings:    ✅ Hooks registered
+  Legacy:      ✅ No old commands found
+
+  Status: ✅ Healthy
+```
+
+## Fix Suggestions
+
+For each issue found, suggest the fix:
+- Missing files → "Run `prism update` to restore"
+- Legacy commands → "Run `prism update` to migrate to namespaced commands"
+- Missing PRISM block → "Run `prism update` to re-inject rules"

package/templates/commands/claude-prism/help.md

@@ -0,0 +1,42 @@
+# /claude-prism:help — Command Reference
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/claude-prism:prism` | Start full UDEC workflow (Understand → Decompose → Execute → Checkpoint). Also handles analysis-only requests — stops after U phase when no code change is needed. |
+| `/claude-prism:checkpoint` | Check current batch progress, show next batch preview |
+| `/claude-prism:plan` | List, create, or view plan files in `docs/plans/` |
+| `/claude-prism:doctor` | Diagnose installation health and suggest fixes |
+| `/claude-prism:stats` | Show project statistics, hook status, and plan progress |
+| `/claude-prism:help` | This reference |
+
+## Quick Start
+
+1. Before any task (code or analysis): `/claude-prism:prism`
+2. Mid-project progress check: `/claude-prism:checkpoint`
+3. Create a new plan: `/claude-prism:plan`
+
+## CLI Commands
+
+These are also available from the terminal:
+
+```bash
+prism init [--lang=XX] [--no-hooks]   # Install prism
+prism check [--ci]                     # Verify installation
+prism doctor                           # Diagnose issues
+prism stats                            # Show summary
+prism reset                            # Clear hook state
+prism update                           # Re-install / migrate
+prism uninstall                        # Remove prism
+```
+
+## UDEC Framework
+
+```
+U — Understand: Assess sufficiency, ask questions, confirm alignment
+     (analysis-only requests stop here with findings report)
+D — Decompose: Break into 2-5 min units, create plan file
+E — Execute: Batch (3-4 tasks), TDD each unit, scope guard
+C — Checkpoint: Report with before/after table, get confirmation
+```