claude-prism 0.1.0

package/README.md

@@ -0,0 +1,500 @@
+```
+                         ╱╲
+            ━━━━━━━━━▶  ╱  ╲  ──── U  Understand
+            complex    ╱    ╲ ──── D  Decompose
+            problem   ╱ PRISM╲──── E  Execute
+                     ╱________╲─── C  Checkpoint
+                                     spectrum
+```
+
+# claude-prism
+
+An AI coding problem decomposition tool for Claude Code. Installs the **UDEC** methodology — Understand, Decompose, Execute, Checkpoint — directly into your project's Claude Code environment.
+
+**The biggest failure mode of AI coding isn't bad code — it's building the wrong thing.** AI agents skip understanding, skip decomposition, and run autonomously for 30 minutes only to produce something nobody wanted. Prism fixes this by injecting discipline into how Claude thinks.
+
+**Core philosophy:** Never implement what you haven't understood. Never execute what you haven't decomposed.
+
+- Zero dependencies
+- Node >= 18
+- MIT License
+- Repository: https://github.com/lazysaturday91/claude-prism
+
+## The Problem
+
+Without structure, Claude does this:
+
+| Without Prism | With Prism |
+|---|---|
+| Reads request → assumes understanding | Reads request → assesses sufficiency |
+| Starts coding immediately | Asks 1-2 clarifying questions first |
+| Builds one 30-minute mega-feature | Decomposes into 2-5 minute verifiable units |
+| Runs autonomously (no checkpoints) | Batches execution: 3-4 tasks → checkpoint → ask permission |
+| Produces working code that's wrong | Produces code that's correct *and* wanted |
+
+## Installation
+
+```bash
+npx claude-prism init              # English, with hooks
+npx claude-prism init --lang=ko    # Korean
+npx claude-prism init --lang=ja    # Japanese
+npx claude-prism init --lang=zh    # Chinese
+npx claude-prism init --no-hooks   # Rules only, no hooks
+prism check                        # Verify installation
+```
+
+### What Gets Installed
+
+After running `prism init`, your project gains:
+
+**UDEC Rules** — Injected into `CLAUDE.md` between `PRISM:START` and `PRISM:END` markers. Explains the four-phase methodology:
+- **U** — Assess information sufficiency before acting. Ask one question at a time, multiple choice, max 3 rounds.
+- **D** — Decompose complex problems into 2-5 minute units with TDD. Create a plan file for 6+ file changes.
+- **E** — Execute in batches (3-4 tasks per batch). Apply TDD Iron Law: failing test → implementation → verify → commit.
+- **C** — Checkpoint after each batch. Report progress, show next batch preview, get confirmation before continuing.
+
+**Slash Commands** — Added to `.claude/commands/claude-prism/`:
+- `/claude-prism:prism` — Full UDEC workflow (understand → decompose → execute → checkpoint). Also handles analysis-only requests.
+- `/claude-prism:checkpoint` — Check batch progress, show next batch preview
+- `/claude-prism:plan` — List, create, or view plan files
+- `/claude-prism:doctor` — Diagnose installation health via Claude
+- `/claude-prism:stats` — Show project statistics, hook status, and plan progress
+- `/claude-prism:help` — Command reference
+
+**Hooks** (optional, unless `--no-hooks` is set) — Four CLI guards that enforce discipline:
+- `commit-guard` — Prevents commits when tests haven't run recently
+- `debug-loop` — Warns at 3 edits, blocks at 5 edits to same file (catches infinite debugging loops)
+- `test-tracker` — Detects test command execution (npm test, jest, vitest, pytest, etc.) and records pass/fail state
+- `scope-guard` — Warns at 4 unique files modified, blocks at 7 (agent-aware: warns at 8, blocks at 12)
+
+**Configuration** — `.prism.json` stores language preference and hook settings. Includes OMC (oh-my-claudecode) detection.
+
+## File Structure After Installation
+
+```
+your-project/
+├── CLAUDE.md                 # (modified) UDEC rules injected
+├── .claude-prism.json       # claude-prism config
+├── .claude/
+│   ├── commands/
+│   │   └── claude-prism/        # Namespaced commands
+│   │       ├── prism.md         # /claude-prism:prism
+│   │       ├── checkpoint.md    # /claude-prism:checkpoint
+│   │       ├── plan.md          # /claude-prism:plan
+│   │       ├── doctor.md        # /claude-prism:doctor
+│   │       ├── stats.md         # /claude-prism:stats
+│   │       └── help.md          # /claude-prism:help
+│   ├── hooks/               # (optional, if --no-hooks not set)
+│   │   ├── commit-guard.mjs
+│   │   ├── debug-loop.mjs
+│   │   ├── test-tracker.mjs
+│   │   └── scope-guard.mjs
+│   ├── rules/               # Hook logic modules
+│   │   ├── commit-guard.mjs
+│   │   ├── debug-loop.mjs
+│   │   ├── test-tracker.mjs
+│   │   └── scope-guard.mjs
+│   ├── lib/                 # Hook dependencies
+│   │   ├── adapter.mjs
+│   │   ├── state.mjs
+│   │   ├── config.mjs
+│   │   └── utils.mjs
+│   └── settings.json        # Claude Code hook registration
+└── docs/plans/
+    └── YYYY-MM-DD-topic.md  # Plan files (created during /claude-prism:prism execution)
+```
+
+## The UDEC Cycle
+
+```
+        START
+          |
+          v
+    [ UNDERSTAND ]  ← Assess sufficiency, ask clarifying questions
+          |
+          v
+    [ DECOMPOSE ]   ← Break into 2-5 min units, create plan file
+          |
+          v
+    [ EXECUTE ]     ← Run batch (3-4 tasks), TDD each unit
+          |
+          v
+    [ CHECKPOINT ]  ← Report, show next batch, ask to continue
+          |
+       [LOOP or STOP]
+```
+
+## Commands
+
+### Command Reference
+
+| Command | When to Use | Purpose |
+|---------|-------------|---------|
+| `/claude-prism:prism` | Any task (code or analysis) | Run full UDEC cycle; stops at U phase for analysis-only requests |
+| `/claude-prism:plan` | Manage plan files | List, create, or view plans |
+| `/claude-prism:checkpoint` | Mid-project | Check batch progress, preview next batch |
+| `/claude-prism:doctor` | Installation issues | Diagnose health, suggest fixes |
+| `/claude-prism:stats` | Check current state | Version, hooks, language, plan progress |
+| `/claude-prism:help` | Forgot commands | Quick reference |
+
+### Workflow
+
+```
+User request arrives
+       │
+       ▼
+  Vague? ──Yes──▶ /claude-prism:prism  (U phase clarifies, then proceeds or stops)
+       │
+       No
+       ▼
+  Complex? ──Yes──▶ /claude-prism:prism     (full UDEC cycle)
+       │
+       No
+       ▼
+  Just execute
+       │
+       ▼
+  Mid-check ──────▶ /claude-prism:checkpoint (between batches)
+       │
+       ▼
+  Plan mgmt ──────▶ /claude-prism:plan       (list/create)
+```
+
+### Use Case Patterns
+
+**Pattern 1: Feature Implementation**
+```
+/claude-prism:prism → "Add login functionality"
+                    → Claude asks: "JWT or sessions?" "OAuth needed?"
+                    → Plan created: docs/plans/2026-02-16-auth.md
+                    → Batch 1 executes (3 tasks)
+/claude-prism:checkpoint  → "Batch 1 done. Continue to batch 2?"
+```
+
+**Pattern 2: Clarify a Vague Request**
+```
+/claude-prism:prism → "Improve performance"
+                    → Claude: [Insufficient] "What kind?"
+                      1. Build time (next build)
+                      2. Runtime (page load/render)
+                      3. Bundle size (recommended)
+                    → Agreement reached → proceeds to D/E/C or stops if analysis-only
+                         → /claude-prism:prism to start execution
+```
+
+**Pattern 3: Resume Previous Work**
+```
+/claude-prism:plan        → List existing plans, show progress
+/claude-prism:checkpoint  → "Plan X: 5/12 tasks done. Batch 3 next."
+                          → "Continue" → Resume execution
+```
+
+**Pattern 4: Quick Troubleshooting**
+```
+/claude-prism:doctor → Check installation health
+/claude-prism:stats  → Verify hooks, language, OMC status
+```
+
+### Before & After
+
+**Before (AI agent's default behavior)**
+1. User: "Refactor auth module"
+2. AI: (no thinking) 30 minutes autonomous execution
+3. Result: Completed structure nobody wanted
+
+**After (Prism applied)**
+1. User: "Refactor auth module"
+2. Claude (automatic questions):
+   - "Goal: Keep existing API and only improve internal structure? (Yes/No)"
+   - "Scope: Authentication/authorization both? Or authentication only?"
+   - "Tests: Keep existing tests as-is?"
+3. User confirms → decomposition starts
+4. Result: Completed as intended
+
+## Hooks
+
+Hooks are optional CLI guards that enforce discipline during development. Install with `prism init`, skip with `--no-hooks`.
+
+### commit-guard
+
+Blocks commits if tests haven't been run in the last 5 minutes (configurable via `maxTestAge` in `.claude-prism.json`). Works with `test-tracker` to know when tests last ran.
+
+```json
+{
+  "hooks": {
+    "commit-guard": {
+      "enabled": true,
+      "maxTestAge": 300
+    }
+  }
+}
+```
+
+**Behavior:**
+- Detects test run via `test-tracker`
+- Blocks commit if: (current time - last test run) > maxTestAge
+- Prevents shipping untested code
+
+### debug-loop
+
+Warns when the same file is edited 3 times in a row, blocks at 5 edits. Catches infinite debugging cycles.
+
+```json
+{
+  "hooks": {
+    "debug-loop": {
+      "enabled": true,
+      "warnAt": 3,
+      "blockAt": 5
+    }
+  }
+}
+```
+
+**Behavior:**
+- Tracks consecutive edits to same file within a session
+- Warns at 3 edits: "Consider stepping back to understand the problem"
+- Blocks at 5 edits: Forces reassessment before continuing
+
+### test-tracker
+
+Detects test command execution and records the timestamp and pass/fail state. Used by `commit-guard` to verify tests ran recently.
+
+**Detects:**
+- `npm test`, `npm run test`
+- `jest`, `vitest`
+- `node --test`
+- `npx mocha`, `mocha`
+- `pytest`
+- `cargo test`
+- `go test`
+- `make test`
+
+**Configuration:**
+```json
+{
+  "hooks": {
+    "test-tracker": {
+      "enabled": true
+    }
+  }
+}
+```
+
+**Behavior:**
+- Runs on every Bash command
+- If command matches test pattern, records timestamp
+- Records result (pass/fail based on exit code)
+- `commit-guard` reads this state to allow/block commits
+
+### scope-guard
+
+Tracks unique source files modified per session. Warns when scope grows without a plan (catches scope creep). Agent-aware: sub-agents get higher thresholds.
+
+```json
+{
+  "hooks": {
+    "scope-guard": {
+      "enabled": true,
+      "warnAt": 4,
+      "blockAt": 7,
+      "agentWarnAt": 8,
+      "agentBlockAt": 12
+    }
+  }
+}
+```
+
+**Behavior:**
+- Tracks unique source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.c`, `.cpp`, `.h`, `.svelte`, `.vue`)
+- Excludes test files (`.test.`, `.spec.`, `_test.`)
+- Standard thresholds: warns at 4 files, blocks at 7
+- Agent thresholds (when OMC sub-agents running): warns at 8, blocks at 12
+- Warning: "Consider running /claude-prism:prism to decompose the task"
+- Block: "Run /claude-prism:prism to decompose before continuing"
+
+## Configuration
+
+Edit `.claude-prism.json` to customize behavior:
+
+```json
+{
+  "language": "en",
+  "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 }
+  }
+}
+```
+
+**Settings:**
+- `language` — Rule language: `en` (English), `ko` (Korean), `ja` (Japanese), `zh` (Chinese)
+- `hooks.*` — Enable/disable individual hooks or customize thresholds
+- `hooks.commit-guard.maxTestAge` — Seconds before test is considered stale (default: 300)
+- `hooks.debug-loop.warnAt/blockAt` — Edit counts that trigger warnings/blocks
+- `hooks.scope-guard.warnAt/blockAt` — File counts for standard mode
+- `hooks.scope-guard.agentWarnAt/agentBlockAt` — File counts for OMC agent mode
+
+## CLI Commands
+
+### prism check
+
+Verify installation after `prism init`:
+
+```bash
+prism check
+```
+
+Output:
+```
+  Commands:  ✅
+  Rules:     ✅
+  Hooks:     ✅
+  Config:    ✅
+
+  Status:    ✅ All good
+```
+
+For CI integration, use `--ci` flag for JSON output:
+
+```bash
+prism check --ci
+```
+
+### prism doctor
+
+Diagnose installation issues with actionable fix suggestions. Also detects oh-my-claudecode (OMC) presence.
+
+```bash
+prism doctor
+```
+
+Output:
+```
+  ✅ Installation is healthy. No issues found.
+
+  OMC:       ✅ v4.1.1
+```
+
+If issues are found:
+```
+  Issues found:
+
+  ❌ CLAUDE.md rules not found
+  ❌ /claude-prism:prism command not installed
+
+  Suggested fixes:
+
+  💡 Run: npx claude-prism init
+  💡 Check: .claude/commands/claude-prism/prism.md exists
+```
+
+### prism stats
+
+Show installation summary including version, language, hook status, plan file count, and OMC detection:
+
+```bash
+prism stats
+```
+
+Output:
+```
+  Version:   v0.1.0
+  Language:  en
+  Plans:     2 file(s)
+  OMC:       ✅ v4.1.1
+  Hooks:
+    ✅ commit-guard
+    ✅ debug-loop
+    ✅ test-tracker
+    ✅ scope-guard
+```
+
+### prism reset
+
+Clear all hook state (edit counters, test timestamps, scope tracking). Use when starting a fresh task or after major refactor:
+
+```bash
+prism reset
+```
+
+Output:
+```
+  ✅ Hook state cleared (edit counters, test timestamps)
+
+  🌈 Fresh start. All hooks reset.
+```
+
+## Uninstall
+
+```bash
+npx claude-prism uninstall
+```
+
+This removes CLAUDE.md rules, slash commands, and hooks.
+
+## Languages
+
+Supported languages for UDEC rules:
+
+- **en** — English (default)
+- **ko** — Korean
+- **ja** — Japanese
+- **zh** — Chinese
+
+Change language (or re-install with different language):
+
+```bash
+npx claude-prism init --lang=ko    # Install Korean rules
+npx claude-prism init --lang=ja    # Install Japanese rules
+npx claude-prism init --lang=zh    # Install Chinese rules
+```
+
+## OMC (oh-my-claudecode) Integration
+
+Prism auto-detects if [oh-my-claudecode](https://github.com/raidenppl/oh-my-claudecode) is installed in your environment. When OMC is present:
+
+- **Higher scope thresholds for agents** — Sub-agents get `agentWarnAt: 8, agentBlockAt: 12` instead of standard `warnAt: 4, blockAt: 7`
+- **Visible in status commands** — `prism stats` and `prism doctor` show OMC detection with version
+- **No configuration needed** — Detection happens automatically
+
+Check OMC status:
+
+```bash
+prism stats       # Shows "OMC: ✅ v4.1.1" or "OMC: ⏭️ not detected"
+prism doctor      # Shows OMC detection in diagnostics
+```
+
+This allows OMC agents (executor, architect, etc.) to modify more files per task without triggering scope warnings, recognizing that coordinated multi-agent work has different constraints than single-agent development.
+
+## TDD Iron Law
+
+Every task in the EXECUTE phase follows:
+
+1. Write a failing test
+2. Write minimum code to pass
+3. Verify the test passes
+4. Commit
+
+Never execute without this cycle.
+
+## Design Philosophy
+
+Prism is built on the insight that **AI needs structure more than humans do.** Humans naturally ask clarifying questions and break problems down. AI doesn't — it optimizes for speed. Prism enforces the discipline that makes AI-assisted coding reliable:
+
+- Explicit understanding phase (no assumptions)
+- Enforced decomposition (no mega-tasks)
+- Batched execution with checkpoints (human in the loop)
+- TDD for every unit (verified, not assumed)
+
+The prism metaphor: white light (complex problem) enters from one side and decomposes into a spectrum of colors (manageable units). Each color (unit) is individually verified, then recombined into a working whole.
+
+## License
+
+MIT
+
+## Author
+
+lazysaturday91

package/bin/cli.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+/**
+ * claude-prism CLI
+ * Usage: prism init [--lang=ko] [--no-hooks]
+ *        prism check [--ci]
+ *        prism doctor
+ *        prism stats
+ *        prism reset
+ *        prism uninstall
+ *        prism update
+ */
+
+import { init, check, uninstall, update, doctor, stats, reset } from '../lib/installer.mjs';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getFlag(name) {
+  const flag = args.find(a => a.startsWith(`--${name}=`));
+  return flag ? flag.split('=')[1] : null;
+}
+
+function hasFlag(name) {
+  return args.includes(`--${name}`) || args.includes(`-${name}`);
+}
+
+// --version / -v
+if (hasFlag('version') || hasFlag('v')) {
+  const { stats: getStats } = await import('../lib/installer.mjs');
+  const s = getStats(process.cwd());
+  console.log(`claude-prism v${s.version}`);
+  process.exit(0);
+}
+
+const cwd = process.cwd();
+
+switch (command) {
+  case 'init': {
+    const language = getFlag('lang') || 'en';
+    const hooks = !hasFlag('no-hooks');
+
+    console.log('🌈 claude-prism init\n');
+    await init(cwd, { language, hooks });
+
+    console.log('✅ Rules injected → CLAUDE.md');
+    console.log('✅ Commands installed → /prism, /checkpoint');
+    if (hooks) {
+      console.log('✅ Hooks installed → commit-guard, debug-loop, test-tracker, scope-guard');
+    } else {
+      console.log('⏭️  Hooks skipped (use --no-hooks to skip)');
+    }
+    console.log('\n🌈 Done. Use /prism before complex tasks.');
+    break;
+  }
+
+  case 'check': {
+    const result = check(cwd);
+    const ci = hasFlag('ci');
+
+    if (ci) {
+      console.log(JSON.stringify(result));
+      process.exit(result.ok ? 0 : 1);
+    }
+
+    console.log('🌈 claude-prism check\n');
+    console.log(`  Commands:  ${result.commands ? '✅' : '❌'}`);
+    console.log(`  Rules:     ${result.rules ? '✅' : '❌'}`);
+    console.log(`  Hooks:     ${result.hooks ? '✅' : '⏭️  (optional)'}`);
+    console.log(`  Config:    ${result.config ? '✅' : '❌'}`);
+    console.log(`\n  Status:    ${result.ok ? '✅ All good' : '❌ Issues found'}`);
+    process.exit(result.ok ? 0 : 1);
+    break;
+  }
+
+  case 'doctor': {
+    console.log('🌈 claude-prism doctor\n');
+    const result = doctor(cwd);
+
+    if (result.healthy) {
+      console.log('  ✅ Installation is healthy. No issues found.');
+    } else {
+      console.log('  Issues found:\n');
+      for (const issue of result.issues) {
+        console.log(`  ❌ ${issue}`);
+      }
+      console.log('\n  Suggested fixes:\n');
+      for (const fix of result.fixes) {
+        console.log(`  💡 ${fix}`);
+      }
+    }
+    console.log(`\n  OMC:       ${result.omc.detected ? `✅ v${result.omc.version || 'unknown'}` : '⏭️  not detected'}`);
+    process.exit(result.healthy ? 0 : 1);
+    break;
+  }
+
+  case 'stats': {
+    const result = stats(cwd);
+    console.log('🌈 claude-prism stats\n');
+    console.log(`  Version:   v${result.version}`);
+    console.log(`  Language:  ${result.language}`);
+    console.log(`  Plans:     ${result.planFiles} file(s)`);
+    console.log(`  OMC:       ${result.omc.detected ? `✅ v${result.omc.version || 'unknown'}` : '⏭️  not detected'}`);
+    console.log('  Hooks:');
+    for (const [name, enabled] of Object.entries(result.hooks)) {
+      console.log(`    ${enabled ? '✅' : '⏭️ '} ${name}`);
+    }
+    break;
+  }
+
+  case 'reset': {
+    console.log('🌈 claude-prism reset\n');
+    reset();
+    console.log('✅ Hook state cleared (edit counters, test timestamps)');
+    console.log('\n🌈 Fresh start. All hooks reset.');
+    break;
+  }
+
+  case 'uninstall': {
+    console.log('🌈 claude-prism uninstall\n');
+    uninstall(cwd);
+    console.log('✅ Rules removed from CLAUDE.md');
+    console.log('✅ Commands removed');
+    console.log('✅ Hooks removed');
+    console.log('✅ Config removed');
+    console.log('\n🌈 Prism uninstalled.');
+    break;
+  }
+
+  case 'update': {
+    console.log('🌈 claude-prism update\n');
+    await update(cwd);
+    console.log('✅ Rules updated');
+    console.log('✅ Commands updated');
+    console.log('✅ Hooks updated');
+    console.log('\n🌈 Prism updated to latest.');
+    break;
+  }
+
+  default: {
+    console.log(`🌈 claude-prism — AI coding problem decomposition tool
+
+Usage:
+  prism init [--lang=XX] [--no-hooks]   Install prism in current project
+  prism check [--ci]                     Verify installation
+  prism doctor                           Diagnose issues with fix suggestions
+  prism stats                            Show installation summary
+  prism reset                            Clear hook state (edit counters, etc.)
+  prism update                           Re-install using current config
+  prism uninstall                        Remove prism
+
+Options:
+  --lang=XX    Language: en (default), ko, ja, zh
+  --no-hooks   Skip enforcement hooks
+  --ci         Output JSON for CI integration
+  --version    Show version`);
+  }
+}

package/hooks/commit-guard.mjs

@@ -0,0 +1,48 @@
+/**
+ * claude-prism — Commit Guard
+ * Blocks commits when tests failed or haven't been run
+ */
+
+import { readState } from '../lib/state.mjs';
+
+export const commitGuard = {
+  name: 'commit-guard',
+
+  evaluate(ctx, config, stateDir) {
+    const command = ctx.command || '';
+
+    if (!command.includes('git commit')) return { type: 'pass' };
+    if (command.includes('--allow-empty')) return { type: 'pass' };
+
+    // Hard block: last test failed
+    const testResult = readState(stateDir, 'last-test-result');
+    if (testResult !== null && testResult.trim() === 'fail') {
+      return {
+        type: 'block',
+        message: '🌈 Prism ✋ Commit blocked: last test run FAILED. Fix tests before committing.'
+      };
+    }
+
+    // Soft warn: no test run recorded
+    const lastTestRaw = readState(stateDir, 'last-test-run');
+    if (lastTestRaw === null) {
+      return {
+        type: 'warn',
+        message: '🌈 Prism > No test run detected this session. Run tests before committing.'
+      };
+    }
+
+    // Soft warn: test run is stale
+    const lastTest = parseInt(lastTestRaw, 10);
+    const now = Math.floor(Date.now() / 1000);
+    const diff = now - lastTest;
+    if (diff > (config.maxTestAge || 300)) {
+      return {
+        type: 'warn',
+        message: `🌈 Prism > Last test run was ${Math.floor(diff / 60)}min ago. Run tests before committing.`
+      };
+    }
+
+    return { type: 'pass' };
+  }
+};