claude-prism 0.2.1 → 0.3.0

package/hooks/debug-loop.mjs

@@ -34,23 +34,31 @@ export const debugLoop = {
     writeJsonState(stateDir, logKey, editLog);
 
     const name = filePath.split('/').pop();
+    const pattern = count >= config.warnAt ? analyzePattern(editLog) : null;
 
-    if (count === config.warnAt) {
-      const pattern = analyzePattern(editLog);
-      const hint = pattern === 'divergent'
-        ? ' Pattern: DIVERGENT — same area edited repeatedly.'
-        : '';
+    if (count >= config.blockAt) {
+      // Divergent pattern → block; convergent (different areas) → downgrade to warn
+      if (pattern === 'divergent') {
+        return {
+          type: 'block',
+          message: `🌈 Prism ✋ Debug Loop blocked: ${name} edited ${count} times on same area. Discuss approach with user before continuing.`
+        };
+      }
       return {
         type: 'warn',
-        message: `🌈 Prism > Debug Loop: ${name} edited ${count} times.${hint} Stop and investigate root cause.`
+        message: `🌈 Prism > Debug Loop: ${name} edited ${count} times (different areas). Consider if this is expected.`
       };
     }
 
-    if (count >= config.blockAt) {
-      return {
-        type: 'block',
-        message: `🌈 Prism ✋ Debug Loop blocked: ${name} edited ${count} times. Discuss approach with user before continuing.`
-      };
+    if (count >= config.warnAt) {
+      // Only warn on divergent pattern (same area edited repeatedly)
+      if (pattern === 'divergent') {
+        return {
+          type: 'warn',
+          message: `🌈 Prism > Debug Loop: ${name} edited ${count} times on same area. Stop and investigate root cause.`
+        };
+      }
+      // Convergent edits (different areas) = normal progressive work → pass
     }
 
     return { type: 'pass' };

package/hooks/scope-guard.mjs

@@ -16,10 +16,10 @@ export const scopeGuard = {
     const filePath = ctx.filePath;
     if (!filePath) return { type: 'pass' };
 
-    // Plan file created → reset scope (user is decomposing properly)
+    // Plan file created → mark plan as active (thresholds will be doubled)
     if (PLAN_PATTERN.test(filePath)) {
-      writeJsonState(stateDir, 'scope-files', []);
-      return { type: 'pass', message: '🌈 Prism 📋 Plan file detected. Scope counter reset.' };
+      writeJsonState(stateDir, 'scope-has-plan', true);
+      return { type: 'pass', message: '🌈 Prism 📋 Plan file detected. Scope thresholds raised.' };
     }
 
     // Only track source files
@@ -39,8 +39,15 @@ export const scopeGuard = {
 
     // Agent-aware thresholds: sub-agents get higher limits
     const isAgent = ctx.agentId && ctx.agentId !== '' && ctx.agentId !== 'default';
-    const warnAt = isAgent ? (config.agentWarnAt || 8) : (config.warnAt || 4);
-    const blockAt = isAgent ? (config.agentBlockAt || 12) : (config.blockAt || 7);
+    let warnAt = isAgent ? (config.agentWarnAt || 8) : (config.warnAt || 4);
+    let blockAt = isAgent ? (config.agentBlockAt || 12) : (config.blockAt || 7);
+
+    // Active plan → double thresholds (planned work is expected to touch many files)
+    const hasPlan = readJsonState(stateDir, 'scope-has-plan');
+    if (hasPlan) {
+      warnAt *= 2;
+      blockAt *= 2;
+    }
 
     if (count >= blockAt) {
       return {

package/lib/installer.mjs

@@ -30,7 +30,7 @@ export async function init(projectDir, options = {}) {
   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'];
+  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md'];
   for (const cmd of commandFiles) {
     copyFileSync(
       join(TEMPLATES_DIR, 'commands', 'claude-prism', cmd),
@@ -241,7 +241,7 @@ export function doctor(projectDir, options = {}) {
 
   // Check namespaced commands
   const nsCommandsDir = join(claudeDir, 'commands', 'claude-prism');
-  const expectedCommands = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md'];
+  const expectedCommands = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md'];
   for (const cmd of expectedCommands) {
     if (!existsSync(join(nsCommandsDir, cmd))) {
       issues.push(`Missing command: claude-prism/${cmd}`);
@@ -386,7 +386,7 @@ export function initGlobal(options = {}) {
   const commandsDir = join(claudeDir, 'commands', 'claude-prism');
   mkdirSync(commandsDir, { recursive: true });
 
-  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md'];
+  const commandFiles = ['prism.md', 'checkpoint.md', 'plan.md', 'doctor.md', 'stats.md', 'help.md', 'update.md'];
   for (const cmd of commandFiles) {
     copyFileSync(
       join(TEMPLATES_DIR, 'commands', 'claude-prism', cmd),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-prism",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "AI coding problem decomposition tool — Understand, Decompose, Execute, Checkpoint.",
   "type": "module",
   "bin": {

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

@@ -47,8 +47,14 @@ When this command is invoked, follow the UDEC framework strictly:
 
 ## E — EXECUTE
 
-11. Execute one batch at a time (3-4 tasks per batch)
-12. Follow TDD: write failing test → implement → verify → commit
+11. Execute in adaptive batches:
+    - 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
+12. Apply context-aware verification:
+    - `lib/`, `utils/`, `store/`, `hooks/`, `services/` → TDD (failing test → implement → verify)
+    - `components/`, `pages/`, `views/` → Build verification (escalate to TDD if complex logic)
+    - `config/`, `styles/`, `types/` → Build/lint only
 13. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
 14. **Self-correction triggers**:
     - Same file edited 3+ times **on the same region/logic** → stop, investigate root cause (progressive edits across different regions — imports, logic, JSX — are normal)

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

@@ -0,0 +1,36 @@
+# /claude-prism:update — Update Prism
+
+When this command is invoked, update claude-prism to the latest version.
+
+## Steps
+
+1. **Run the update command**:
+   ```bash
+   npx claude-prism@latest update
+   ```
+
+2. **If `--global` argument is provided**, update global installation instead:
+   ```bash
+   npx claude-prism@latest update --global
+   ```
+
+3. **Report the result** using this format:
+
+```
+🌈 claude-prism updated
+
+  ✅ Rules updated → CLAUDE.md
+  ✅ Commands updated → /claude-prism:*
+  ✅ Hooks updated → commit-guard, debug-loop, test-tracker, scope-guard
+```
+
+Or for global:
+
+```
+🌈 claude-prism updated (global)
+
+  ✅ Commands updated → ~/.claude/commands/claude-prism/
+  ✅ OMC skill updated → ~/.claude/skills/prism/
+```
+
+4. **Verify** by running `prism check` (local) or checking file existence (global).

package/templates/rules.en.md

@@ -124,17 +124,29 @@ Tech stack, key decisions, 2-3 sentences max.
 
 ### 3-1. Batch Execution + Checkpoints
 
-1. **Batch size**: 3-4 tasks per batch
+1. **Adaptive batch size**:
+   - 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
 2. **Checkpoint**: report results after each batch + wait for user feedback
 3. **Report content**: what was done / verification results / next batch preview
 4. **On blockers**: stop immediately and report (do not guess)
 
-### 3-2. TDD Iron Law
+### 3-2. Verification Strategy (Context-Aware)
 
-1. Write a failing test first
-2. Write minimal code to pass the test
-3. Never commit without tests
-4. Never claim completion without fresh verification evidence
+Choose verification method by file location:
+
+| Path Pattern | Strategy | When to Escalate to TDD |
+|---|---|---|
+| `lib/`, `utils/`, `store/`, `hooks/`, `services/` | **TDD required** — failing test → implement → verify | Always |
+| `components/`, `pages/`, `views/` | **Build verification** — build passes + visual check | When component has complex logic (state machines, calculations) |
+| `config/`, `styles/`, `types/`, `*.json` | **Build only** — build/lint passes | Never |
+
+**Core Rules (apply to all):**
+1. Never claim completion without fresh verification evidence
+2. Never commit code that doesn't build
+3. For TDD paths: write failing test first → minimal code to pass → verify
+4. For build paths: run build/lint after changes → confirm no regressions
 
 ### 3-3. Systematic Debugging
 
@@ -177,6 +189,17 @@ Before modifying any code, pass this filter:
 
 **If tempted:** Note the improvement for the user. Ask: "I noticed X could be improved. Want me to address it after the current task?"
 
+### 3-6. Agent Delegation Verification
+
+When delegating work to sub-agents (OMC executor, etc.):
+
+1. **Clear instructions**: specify expected output, files to modify, pass criteria
+2. **Read actual files** after agent completes — never trust the agent's report alone
+3. **Run build/test** to verify the agent's changes work
+4. **Fix or retry** if incomplete: complete remaining work directly, or re-delegate with clearer instructions
+
+**Never mark a delegated task as complete without reading the actual file state.**
+
 ---
 
 ## 4. CHECKPOINT — Confirmation Protocol

package/templates/rules.ja.md

@@ -124,17 +124,29 @@ DECOMPOSEに進む前に確認:
 
 ### 3-1. バッチ実行 + チェックポイント
 
-1. **バッチサイズ**: バッチあたり3-4タスク
+1. **バッチサイズ（変更の複雑さに応じて調整）**:
+   - 単純な変更（import、型定義、設定ファイル）: 1バッチあたり5-8タスク
+   - 標準的な変更（機能追加・修正）: 1バッチあたり3-4タスク
+   - 複雑な変更（新規モジュール、アーキテクチャ変更）: 1バッチあたり1-2タスク
 2. **チェックポイント**: 各バッチ後に結果を報告 + ユーザーフィードバックを待つ
 3. **報告内容**: 実施内容 / 検証結果 / 次のバッチのプレビュー
 4. **ブロッカー発生時**: 即座に停止して報告 (推測しない)
 
-### 3-2. TDD Iron Law
+### 3-2. 検証戦略（コンテキスト対応）
 
-1. まず失敗するテストを書く
-2. テストを通過する最小限のコードを書く
-3. テストなしでコミットしない
-4. 新鮮な検証証拠なしで完了を宣言しない
+ファイルの配置場所に応じて検証方法を選択する:
+
+| パスパターン | 戦略 | TDDに昇格するタイミング |
+|---|---|---|
+| `lib/`, `utils/`, `store/`, `hooks/`, `services/` | **TDD必須** — 失敗テスト作成 → 実装 → 検証 | 常に |
+| `components/`, `pages/`, `views/` | **ビルド検証** — ビルド通過 + 動作確認 | コンポーネントに複雑なロジックがある場合（ステートマシン、計算処理） |
+| `config/`, `styles/`, `types/`, `*.json` | **ビルドのみ** — ビルド/lint通過 | 不要 |
+
+**全パスに適用する基本ルール:**
+1. 新鮮な検証証拠なしに完了を宣言しない
+2. ビルドが通らないコードをコミットしない
+3. TDDパスでは: まず失敗テストを書く → 通過させる最小限のコードを書く → 検証する
+4. ビルドパスでは: 変更後にビルド/lintを実行 → リグレッションがないことを確認する
 
 ### 3-3. 体系的デバッグ
 
@@ -177,6 +189,17 @@ DECOMPOSEに進む前に確認:
 
 **誘惑を感じたら：** ユーザーにメモとして残せ。「Xを改善できそうです。現在のタスク完了後に対応しますか？」
 
+### 3-6. エージェント委任の検証
+
+サブエージェント（OMC executor等）に作業を委任する場合:
+
+1. **明確な指示**: 期待する出力、変更するファイル、合格基準を具体的に指定する
+2. **実際のファイルを確認**: エージェント完了後は実際のファイルを読む — エージェントの報告だけを信用しない
+3. **ビルド/テストを実行**: エージェントの変更が正しく動作するか検証する
+4. **不完全なら修正または再委任**: 残作業を直接完了させるか、より明確な指示で再委任する
+
+**委任したタスクは、実際のファイル状態を確認せずに完了とマークしない。**
+
 ---
 
 ## 4. CHECKPOINT (確認) — 確認プロトコル

package/templates/rules.ko.md

@@ -124,17 +124,29 @@ DECOMPOSE로 넘어가기 전 확인:
 
 ### 3-1. 배치 실행 + 체크포인트
 
-1. **배치 단위**: 3-4개 태스크씩 실행
+1. **적응형 배치 크기**:
+   - 단순 변경 (import, 타입, 설정): 5-8개/배치
+   - 일반 변경 (기능 추가/수정): 3-4개/배치
+   - 복잡 변경 (새 모듈, 아키텍처): 1-2개/배치
 2. **체크포인트**: 배치 완료 후 결과 보고 + 사용자 피드백 대기
 3. **보고 내용**: 구현된 것 / 검증 결과 / 다음 배치 미리보기
 4. **블로커 발생 시**: 즉시 멈추고 보고 (추측하지 않음)
 
-### 3-2. TDD Iron Law
+### 3-2. 검증 전략 (컨텍스트별 분류)
 
-1. 실패하는 테스트를 먼저 작성한다
-2. 테스트를 통과하는 최소 코드를 작성한다
-3. 테스트 없이 커밋하지 않는다
-4. 검증 없이 완료를 선언하지 않는다
+파일 위치에 따라 검증 방법을 선택하라:
+
+| 경로 패턴 | 전략 | TDD로 격상하는 조건 |
+|---|---|---|
+| `lib/`, `utils/`, `store/`, `hooks/`, `services/` | **TDD 필수** — 실패 테스트 → 구현 → 검증 | 항상 |
+| `components/`, `pages/`, `views/` | **빌드 검증** — 빌드 통과 + 시각적 확인 | 컴포넌트에 복잡한 로직이 있을 때 (상태 머신, 계산 등) |
+| `config/`, `styles/`, `types/`, `*.json` | **빌드만** — 빌드/린트 통과 | 불필요 |
+
+**핵심 규칙 (모든 경로에 적용):**
+1. 검증 없이 완료를 선언하지 않는다
+2. 빌드가 깨진 코드를 커밋하지 않는다
+3. TDD 경로: 실패 테스트 → 최소 코드 → 검증
+4. 빌드 경로: 변경 후 빌드/린트 실행 → 회귀 없음 확인
 
 ### 3-3. 체계적 디버깅
 
@@ -177,6 +189,17 @@ DECOMPOSE로 넘어가기 전 확인:
 
 **유혹을 느끼면:** 사용자에게 메모로 남겨라. "X를 개선할 수 있을 것 같습니다. 현재 작업 완료 후 다룰까요?"
 
+### 3-6. 에이전트 위임 검증
+
+서브 에이전트(OMC executor 등)에 작업을 위임할 때:
+
+1. **명확한 지시**: 예상 결과물, 수정할 파일, 통과 기준 명시
+2. **실제 파일 읽기**: 에이전트 완료 후 보고서만 믿지 말고 실제 파일 상태 확인
+3. **빌드/테스트 실행**: 에이전트의 변경사항이 작동하는지 검증
+4. **보완 또는 재시도**: 미완성이면 직접 보완하거나, 더 명확한 지시로 재위임
+
+**위임된 작업은 실제 파일 상태를 읽지 않고 완료 처리하지 마라.**
+
 ---
 
 ## 4. CHECKPOINT — 확인 프로토콜

package/templates/rules.zh.md

@@ -124,17 +124,29 @@
 
 ### 3-1. 批次执行 + 检查点
 
-1. **批次大小**：每批 3-4 个任务
+1. **批次大小（根据变更复杂度调整）**：
+   - 简单变更（import、类型定义、配置文件）：每批 5-8 个任务
+   - 标准变更（功能新增/修改）：每批 3-4 个任务
+   - 复杂变更（新模块、架构调整）：每批 1-2 个任务
 2. **检查点**：每批后报告结果 + 等待用户反馈
 3. **报告内容**：完成了什么 / 验证结果 / 下一批预览
 4. **遇到阻塞时**：立即停止并报告（不要猜测）
 
-### 3-2. TDD Iron Law
+### 3-2. 验证策略（上下文感知）
 
-1. 先写一个失败的测试
-2. 写最少的代码来通过测试
-3. 没有测试不提交
-4. 没有新鲜验证证据不声明完成
+根据文件所在位置选择验证方式：
+
+| 路径模式 | 策略 | 何时升级为 TDD |
+|---|---|---|
+| `lib/`, `utils/`, `store/`, `hooks/`, `services/` | **必须 TDD** — 先写失败测试 → 实现 → 验证 | 始终 |
+| `components/`, `pages/`, `views/` | **构建验证** — 构建通过 + 视觉确认 | 组件含复杂逻辑时（状态机、计算逻辑） |
+| `config/`, `styles/`, `types/`, `*.json` | **仅构建** — 构建/lint 通过 | 不需要 |
+
+**适用于所有路径的核心规则：**
+1. 没有新鲜验证证据不声明完成
+2. 不提交无法构建的代码
+3. TDD 路径：先写失败测试 → 写最少代码通过 → 验证
+4. 构建路径：变更后运行构建/lint → 确认无回归
 
 ### 3-3. 系统化调试
 
@@ -177,6 +189,17 @@
 
 **感到诱惑时：** 给用户留个备注。"我注意到 X 可以改进。当前任务完成后要处理吗？"
 
+### 3-6. 代理委托验证
+
+将工作委托给子代理（OMC executor 等）时：
+
+1. **明确指令**：具体说明预期输出、要修改的文件、通过标准
+2. **读取实际文件**：代理完成后亲自读取文件 — 不要只相信代理的报告
+3. **运行构建/测试**：验证代理的变更是否正常工作
+4. **不完整则修复或重新委托**：直接补全剩余工作，或提供更明确的指令重新委托
+
+**委托的任务，必须确认实际文件状态后才能标记为完成。**
+
 ---
 
 ## 4. CHECKPOINT (检查点) — 确认协议

package/templates/skills/prism/SKILL.md

@@ -76,17 +76,23 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
 
 ## E — EXECUTE
 
-11. Execute one batch at a time (3-4 tasks per batch)
-12. Follow TDD: write failing test → implement → verify → commit
+11. Execute in adaptive batches:
+    - 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
+12. Apply context-aware verification:
+    - `lib/`, `utils/`, `store/`, `hooks/`, `services/` → TDD (failing test → implement → verify)
+    - `components/`, `pages/`, `views/` → Build verification (escalate to TDD if complex logic)
+    - `config/`, `styles/`, `types/` → Build/lint only
 13. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
 14. **Self-correction triggers**:
-    - Same file edited 3+ times on the same region/logic → stop, investigate root cause
+    - Same file edited 3+ times **on the same region/logic** → stop, investigate root cause (progressive edits across different regions — imports, logic, JSX — are normal)
     - File not in plan → pause, ask about scope change
     - 3 consecutive test failures → stop, reconsider approach
     - New package needed → ask user first
     - Adding workarounds on workarounds → design problem, step back
-15. **Verification scoping**: When running build checks, filter output to only changed files.
-16. **Agent failure recovery**: If a delegated agent partially fails:
+15. **Verification scoping**: When running build checks (tsc, lint, etc.), filter output to only changed files. Pre-existing errors in other files are not your concern. Example: `tsc --noEmit 2>&1 | grep -i "<changed-file>"`
+16. **Agent failure recovery**: If a delegated agent partially fails or produces incomplete results:
     1. Verify actual file state (read the file, not just the agent's report)
     2. If partially correct → complete the remaining work directly
     3. If fully wrong → retry with clearer instructions or execute directly
@@ -110,5 +116,6 @@ If oh-my-claudecode is detected in this environment:
 - Use `architect` agent for complex decomposition decisions
 - Use `executor` agents for parallel batch execution when tasks are independent
 - Use `verifier` agent for checkpoint verification
+- Scope Guard thresholds are automatically raised for sub-agents (8 warn / 12 block vs 4/7)
 
 </Steps>