claude-prism 1.2.7 → 1.4.0

package/plugin-hooks.json

@@ -0,0 +1,82 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/pre-tool.mjs",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/pre-tool.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/post-tool.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/precompact.mjs",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/session-end.mjs",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/subagent-start.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/task-completed.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}

package/scripts/post-tool.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runPipelineAsync } from '../lib/pipeline.mjs';
+import { testTracker } from '../hooks/test-tracker.mjs';
+
+await runPipelineAsync([
+  { name: 'test-tracker', rule: testTracker },
+], 'PostToolUse');

package/scripts/pre-tool.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runPipelineAsync } from '../lib/pipeline.mjs';
+import { commitGuard } from '../hooks/commit-guard.mjs';
+import { planEnforcement } from '../hooks/plan-enforcement.mjs';
+
+await runPipelineAsync([
+  { name: 'commit-guard', rule: commitGuard },
+  { name: 'plan-enforcement', rule: planEnforcement },
+], 'PreToolUse');

package/scripts/precompact.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Plugin-mode runner for PreCompact event
+ * Generates HANDOFF.md before context compaction
+ */
+import { readFileSync } from 'fs';
+import { precompactHandler } from '../hooks/precompact-handler.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = precompactHandler.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  // Silent fail — hooks should never break the session
+  process.exit(0);
+}

package/scripts/session-end.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Plugin-mode runner for SessionEnd event
+ * Saves HANDOFF.md and appends to PROJECT-MEMORY.md
+ */
+import { readFileSync } from 'fs';
+import { sessionEndHandler } from '../hooks/session-end-handler.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = sessionEndHandler.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  process.exit(0);
+}

package/scripts/subagent-start.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Plugin-mode runner for SubagentStart event
+ * Injects current plan scope into subagent context
+ */
+import { readFileSync } from 'fs';
+import { scopeInjector } from '../hooks/subagent-scope-injector.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = scopeInjector.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  process.exit(0);
+}

package/scripts/task-completed.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Plugin-mode runner for TaskCompleted event
+ * Auto-updates plan file checkboxes
+ */
+import { readFileSync } from 'fs';
+import { planSync } from '../hooks/task-plan-sync.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = planSync.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  process.exit(0);
+}

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

@@ -2,7 +2,7 @@
 
 When this command is invoked:
 
-1. **Read the plan file** from `docs/plans/` (most recent matching file)
+1. **Read the plan file** from `.prism/plans/` (most recent matching file)
 2. **Auto-count progress** by running:
    - `grep -c '\- \[x\]' <plan-file>` → completed count
    - `grep -c '\- \[ \]' <plan-file>` → remaining count

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

@@ -5,7 +5,7 @@ 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?
+2. **Config**: Does `.prism/config.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, update.md
 4. **Hooks**: Do these files exist in `.claude/hooks/`?
@@ -23,7 +23,7 @@ When this command is invoked, check all components of the prism installation:
 🌈 claude-prism doctor
 
   CLAUDE.md:   ✅ PRISM rules present
-  Config:      ✅ .claude-prism.json valid
+  Config:      ✅ .prism/config.json valid
   Commands:    ✅ 7/7 installed
   Hooks:       ✅ 2/2 installed
   Rules:       ✅ 3/3 installed

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

@@ -6,7 +6,7 @@
 |---------|-------------|
 | `/claude-prism:prism` | Start full EUDEC workflow (Essence → 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:plan` | List, create, or view plan files in `.prism/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 |

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

@@ -4,8 +4,8 @@ When this command is invoked:
 
 ## List Plans
 
-1. **Check** if `docs/plans/` exists. If not, report "No plans directory found. Create one with `/claude-prism:plan create <topic>`."
-2. **Scan** `docs/plans/` for all `.md` files
+1. **Check** if `.prism/plans/` exists. If not, report "No plans directory found. Create one with `/claude-prism:plan create <topic>`."
+2. **Scan** `.prism/plans/` for all `.md` files
 3. **Show each plan** with:
    - Filename and date
    - Goal (first line after `## Goal`)
@@ -17,7 +17,7 @@ When this command is invoked:
 If user requests a new plan:
 
 1. **Determine topic** from user's description
-2. **Create file** at `docs/plans/YYYY-MM-DD-<topic>.md`
+2. **Create file** at `.prism/plans/YYYY-MM-DD-<topic>.md`
 3. **Use EUDEC template**:
 
 ```

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

@@ -69,12 +69,12 @@ When this command is invoked, follow the EUDEC framework strictly:
 13. **Assign verification strategy** per task: `| Verify: TDD` or `| Verify: Build` or `| Verify: Visual`
 14. **Pre-decomposition checklist**:
     - **Codebase audit**: grep/search to verify targets actually exist in code
-    - **Cross-plan check**: if other plans exist in `docs/plans/`, identify overlapping files
+    - **Cross-plan check**: if other plans exist in `.prism/plans/`, identify overlapping files
     - Required types/interfaces have the necessary fields?
     - External package APIs behave as expected?
     - Cross-package dependencies identified and noted as prerequisites?
 15. **Quality gate**: Plan file exists and targets verified, project builds, dependencies resolved, environment validated. All must pass before execution.
-16. **Save plan** to `docs/plans/YYYY-MM-DD-<topic>.md`
+16. **Save plan** to `.prism/plans/YYYY-MM-DD-<topic>.md`
 17. **Get approval**: "Proceed with this plan?"
 
 ## X — EXECUTE
@@ -83,7 +83,7 @@ When this command is invoked, follow the EUDEC framework strictly:
     - Simple changes (imports, types, config): 5-8 per batch
     - Standard changes (feature add/modify): 3-4 per batch
     - Complex changes (new module, architecture): 1-2 per batch
-19. **Git-as-Memory**: commit after each completed batch as a rollback point. Use `git diff` summaries to maintain context in long sessions.
+19. **Git-as-Memory**: commit after each completed batch as a rollback point. Use `git diff` summaries to maintain context in long sessions. Claude Code checkpoints (`Esc+Esc` / `/rewind`) complement git for intra-session rollback.
 20. Apply risk-based verification:
     - **High risk** (business logic, auth, data mutation): TDD — failing test → implement → pass. Include negative tests.
     - **Medium risk** (new components with logic, API integration): Build + lint pass

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

@@ -4,10 +4,10 @@ When this command is invoked:
 
 ## Gather Information
 
-1. **Read `.claude-prism.json`** for:
+1. **Read `.prism/config.json`** for:
    - Language setting
    - Hook configurations and enabled status
-2. **Scan plan files** in `docs/plans/*.md`:
+2. **Scan plan files** in `.prism/plans/*.md`:
    - Count total files
    - For each plan, count `[x]` (done) vs `[ ]` (pending) tasks
    - Calculate completion percentage

package/templates/rules.md

@@ -159,7 +159,7 @@ If no code change is needed (architecture review, cause analysis, investigation)
 ### 3-3. Plan File Persistence
 
 Save multi-step plans (6+ files) as markdown:
-- **Path**: `docs/plans/YYYY-MM-DD-<topic>.md`
+- **Path**: `.prism/plans/YYYY-MM-DD-<topic>.md`
 
 ```markdown
 ## Goal
@@ -196,7 +196,7 @@ Tech stack, key decisions, 2-3 sentences max.
 
 Before creating the plan:
 - [ ] **Codebase audit**: grep/search to verify targets actually exist in code (don't trust assumptions from prior sessions)
-- [ ] **Cross-plan check**: if other plans exist in `docs/plans/`, identify overlapping files and note dependencies
+- [ ] **Cross-plan check**: if other plans exist in `.prism/plans/`, identify overlapping files and note dependencies
 - [ ] Required types/interfaces have the necessary fields?
 - [ ] External package APIs behave as expected?
 - [ ] Cross-package dependencies identified?
@@ -327,6 +327,13 @@ When delegating work to sub-agents:
 
 **Never mark a delegated task as complete without reading the actual file state.**
 
+### 4-8. Checkpoint Integration
+
+Claude Code creates automatic checkpoints on every edit. Use `Esc+Esc` or `/rewind` to restore.
+- Before risky changes: checkpoint exists automatically
+- After failed batch: consider `/rewind` to restore clean state before retry
+- Checkpoints complement Git-as-Memory: git for cross-session, checkpoints for intra-session
+
 ### 4-7. Project-Type Verification Examples
 
 | Project Type | Syntax Check | Smoke Test | Approval Test |
@@ -464,7 +471,7 @@ If any of these excuses come to mind, **that's a warning signal**. Stop and retu
 | "It worked in my head" | Run the test. Thought experiments don't count |
 | "The existing code is messy anyway" | Fix what was asked. Note the rest for later |
 | "The plan says 0% so we start fresh" | Grep the codebase. Prior work may already exist |
-| "Other plans won't conflict" | Check `docs/plans/` for overlapping files |
+| "Other plans won't conflict" | Check `.prism/plans/` for overlapping files |
 | "Tests pass, so it must be correct" | Passing tests only prove what you tested. Check edge cases and negative cases |
 | "3 files is too few to decompose" | Depends on coupling. 2 files in a tightly-coupled legacy system may need decomposition |
 | "I already grasped the essence" | If the essence statement contains technology names, it's still at solution level |

package/templates/runners/precompact.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI-mode runner for PreCompact event
+ * Installed to .claude/hooks/precompact.mjs
+ */
+import { readFileSync } from 'fs';
+import { precompactHandler } from '../rules/precompact-handler.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = precompactHandler.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  process.exit(0);
+}

package/templates/runners/session-end.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI-mode runner for SessionEnd event
+ * Installed to .claude/hooks/session-end.mjs
+ */
+import { readFileSync } from 'fs';
+import { sessionEndHandler } from '../rules/session-end-handler.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = sessionEndHandler.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  process.exit(0);
+}

package/templates/runners/subagent-start.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI-mode runner for SubagentStart event
+ * Installed to .claude/hooks/subagent-start.mjs
+ */
+import { readFileSync } from 'fs';
+import { scopeInjector } from '../rules/subagent-scope-injector.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = scopeInjector.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  process.exit(0);
+}

package/templates/runners/task-completed.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI-mode runner for TaskCompleted event
+ * Installed to .claude/hooks/task-completed.mjs
+ */
+import { readFileSync } from 'fs';
+import { planSync } from '../rules/task-plan-sync.mjs';
+import { loadConfig } from '../lib/config.mjs';
+
+try {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const config = loadConfig(process.cwd());
+  const result = planSync.evaluate(input, config);
+  if (result) {
+    process.stdout.write(JSON.stringify(result));
+  }
+} catch (e) {
+  process.exit(0);
+}

package/templates/settings.json

@@ -33,6 +33,50 @@
           }
         ]
       }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/precompact.mjs",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/session-end.mjs",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/subagent-start.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/task-completed.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
     ]
   }
 }

package/templates/skills/prism/SKILL.md

@@ -99,12 +99,12 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
 13. **Assign verification strategy** per task: `| Verify: TDD` or `| Verify: Build` or `| Verify: Visual`
 14. **Pre-decomposition checklist**:
     - **Codebase audit**: grep/search to verify targets actually exist in code
-    - **Cross-plan check**: if other plans exist in `docs/plans/`, identify overlapping files
+    - **Cross-plan check**: if other plans exist in `.prism/plans/`, identify overlapping files
     - Required types/interfaces have the necessary fields?
     - External package APIs behave as expected?
     - Cross-package dependencies identified and noted as prerequisites?
 15. **Quality gate**: Plan file exists and targets verified, project builds, dependencies resolved, environment validated. All must pass before execution.
-16. **Save plan** to `docs/plans/YYYY-MM-DD-<topic>.md`
+16. **Save plan** to `.prism/plans/YYYY-MM-DD-<topic>.md`
 17. **Get approval**: "Proceed with this plan?"
 
 ## X — EXECUTE
@@ -113,7 +113,7 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
     - Simple changes (imports, types, config): 5-8 per batch
     - Standard changes (feature add/modify): 3-4 per batch
     - Complex changes (new module, architecture): 1-2 per batch
-19. **Git-as-Memory**: commit after each completed batch as a rollback point. Use `git diff` summaries to maintain context in long sessions.
+19. **Git-as-Memory**: commit after each completed batch as a rollback point. Use `git diff` summaries to maintain context in long sessions. Claude Code checkpoints (`Esc+Esc` / `/rewind`) complement git for intra-session rollback.
 20. Apply risk-based verification:
     - **High risk** (business logic, auth, data mutation): TDD — failing test → implement → pass. Include negative tests.
     - **Medium risk** (new components with logic, API integration): Build + lint pass