claude-prism 1.4.0 → 1.5.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-prism",
-  "version": "1.4.0",
-  "description": "EUDEC methodology framework for AI coding agents",
+  "version": "1.5.0",
+  "description": "AI agent harness implementing the EUDEC methodology",
   "author": { "name": "lazysaturday91" },
   "repository": "https://github.com/lazysaturday91/claude-prism",
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] — 2026-03-04
+
+### Changed
+- **Adaptive Weight routing** — EUDEC path auto-scales by task size (Lightweight/Standard/Full)
+- **Bugfix Fast Path** — 4-step lightweight path: symptom → cause → fix → verify (skips formal EUDEC)
+- **Verification Fallback Ladder** simplified from 6 levels to 3 (Tests/Build/Diff)
+- **Adaptive checkpoints** — frequency proportional to task weight (no pause for lightweight)
+- **Rationalization Defense** compressed from 17 to 4 highest-impact items
+- Section numbering corrected (4-8 moved after 4-7)
+- Package description and keywords updated with "agent harness" positioning
+
 ## [1.4.0] — 2026-03-03
 
 ### Added

package/README.md

@@ -16,7 +16,12 @@
 
 # claude-prism
 
-**EUDEC methodology framework for AI coding agents.**
+**AI agent harness implementing the EUDEC methodology for reliable AI-assisted coding.**
+
+Prism is an [agent harness](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html) —
+the infrastructure that channels AI coding agents toward correct, verified output.
+It combines a behavioral methodology (EUDEC), deterministic hooks for enforcement,
+session lifecycle automation, and adaptive process weight that scales with task complexity.
 
 Installs the EUDEC methodology — **Essence, Understand, Decompose, Execute, Checkpoint** — directly into your project's Claude Code environment. Includes a session transition protocol (Handoff) that bookends the core cycle. Seven hooks enforce the methodology and automate session management.
 
@@ -75,10 +80,16 @@ Injected into `CLAUDE.md`, EUDEC is a behavioral framework that corrects how AI
 - **Medium risk** (new components, API integration): Build + runtime check
 - **Low risk** (imports, types, renaming): Build/lint passes
 - **No test infra** (legacy PHP, WordPress): Grep-based static check + syntax validation
-- Fallback: Automated Tests → Approval Testing → Build → Lint → Smoke Check → Manual Diff
+- Fallback Ladder: Tests → Build → Diff (use highest available)
 
 **Quality gates** between phases prevent executing on broken baselines.
 
+**v1.5.0:**
+- **Adaptive Weight**: EUDEC auto-scales — lightweight (1-2 files), standard, or full path
+- **Bugfix Fast Path**: symptom → cause → fix → verify (skips formal EUDEC cycle)
+- **Streamlined verification**: 3-level fallback ladder (Tests → Build → Diff)
+- **Adaptive checkpoints**: no pause for small tasks, summary for medium, full for large
+
 **New in v1.4.0:**
 - **Native Claude Code plugin** — `claude plugin install claude-prism` for zero-config setup
 - **4 new hook events** — PreCompact (auto-HANDOFF), SessionEnd (session protection), SubagentStart (scope injection), TaskCompleted (plan auto-update)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-prism",
-  "version": "1.4.0",
-  "description": "EUDEC methodology framework for AI coding agents — Essence, Understand, Decompose, Execute, Checkpoint.",
+  "version": "1.5.0",
+  "description": "AI agent harness implementing the EUDEC methodology — Essence, Understand, Decompose, Execute, Checkpoint.",
   "type": "module",
   "bin": {
     "prism": "./bin/cli.mjs"
@@ -21,7 +21,11 @@
     "claude-code-hooks",
     "udec",
     "eudec",
-    "ai-agent"
+    "ai-agent",
+    "harness-engineering",
+    "agent-harness",
+    "ai-harness",
+    "context-engineering"
   ],
   "engines": {
     "node": ">=18"

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

@@ -17,12 +17,22 @@ When this command is invoked, follow the EUDEC framework strictly:
 
    | Essence Character | Type | Path |
    |-------------------|------|------|
-   | "X is broken" | Bugfix | UNDERSTAND → locate → fix → verify |
+   | "X is broken" | Bugfix | Fast Path (below) |
    | "X should be possible" | Feature | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
    | "All X must become Y" | Migration | UNDERSTAND → pattern → batch apply → verify |
    | "X's structure must change" | Refactor | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
    | "Why does X happen?" | Investigation | explore → analyze → report |
 
+2b. **Adaptive Weight** — select EUDEC path by task size:
+
+   | Weight | Criteria | Path |
+   |--------|----------|------|
+   | **Lightweight** | 1-2 files, <50 LOC, clear scope | Essence (1 line) → Execute → Verify → Done |
+   | **Standard** | 3-5 files, 50-200 LOC | Full EUDEC, summary checkpoints |
+   | **Full** | 6+ files, 200+ LOC, or unclear scope | Full EUDEC with plan file + full checkpoints |
+
+   Lightweight skips formal UNDERSTAND and DECOMPOSE. Bugfix fast path (regardless of file count): reproduce → root cause → minimal fix → verify (skips ESSENCE/UNDERSTAND/DECOMPOSE entirely).
+
 ## U — UNDERSTAND
 
 3. **Explore first**: Read package.json, project structure, related files before asking anything
@@ -89,7 +99,7 @@ When this command is invoked, follow the EUDEC framework strictly:
     - **Medium risk** (new components with logic, API integration): Build + lint pass
     - **Low risk** (imports, types, style, renaming): Build/lint passes
     - **No test infra** (legacy PHP, WordPress, etc.): Grep-based static check + syntax validation
-    - Use **Verification Fallback Ladder**: Automated Tests → Approval Testing → Build → Lint → Smoke Check → Manual Diff Review (use highest available level)
+    - **Verification Fallback Ladder** (use highest available): Tests → Build → Diff
 21. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
 22. **Goal Recitation**: At every batch boundary, re-read the plan and confirm: "Current work aligns with: [original goal]"
 23. **Self-correction triggers (Thrashing Detector)**:
@@ -124,7 +134,7 @@ When this command is invoked, follow the EUDEC framework strictly:
 
 28. **Plan-Reality sync**: Grep for plan targets, mark vanished targets as "already completed", add newly discovered targets.
 29. Include: verification results, files modified, tests status
-30. **Checkpoint policy**: after 3 consecutive approvals, increase batch size to 5-8 for the rest of the phase
+30. **Checkpoint policy** (proportional to weight): Lightweight — no pause, report with evidence. Standard — summary (1-2 lines). Full — full dashboard + "Continue?"
 31. Ask: "Continue to next batch?"
 32. User can redirect, adjust scope, or stop at any checkpoint
 

package/templates/rules.md

@@ -39,7 +39,7 @@ The task type naturally emerges from the essence:
 
 | Essence Character | Type | Path |
 |-------------------|------|------|
-| "X is broken" | Bugfix | UNDERSTAND → locate → fix → verify |
+| "X is broken" | Bugfix | Fast Path (1-5) |
 | "X should be possible" | Feature | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
 | "All X must become Y" | Migration | UNDERSTAND → pattern → batch apply → verify |
 | "X's structure must change" | Refactor | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
@@ -66,6 +66,26 @@ Before moving to UNDERSTAND, verify:
 - [ ] Each step in the expansion path works independently
 - [ ] Task type has been clearly derived
 
+### 1-5. Adaptive Weight (Task Size Routing)
+
+After extracting essence and task type, assess task weight to select the appropriate EUDEC path:
+
+| Weight | Criteria | Path |
+|--------|----------|------|
+| **Lightweight** | 1-2 files, <50 LOC, clear scope | Essence (1 line) → Execute → Verify → Done |
+| **Standard** | 3-5 files, 50-200 LOC | Full EUDEC, summary checkpoints |
+| **Full** | 6+ files, 200+ LOC, or unclear scope | Full EUDEC with plan file + full checkpoints |
+
+**Lightweight path** skips formal UNDERSTAND (sufficiency assessment, question rounds, alignment confirmation) and DECOMPOSE. The essence statement still grounds the work but takes one line, not a full section.
+
+**Bugfix fast path** (regardless of file count):
+1. Reproduce the symptom
+2. Trace to root cause
+3. Minimal fix (smallest change that resolves the cause)
+4. Verify (test/build/diff)
+
+Bugfixes skip ESSENCE extraction, UNDERSTAND ceremony, and DECOMPOSE entirely. The 4-step debugging protocol (4-3) is the complete path.
+
 ---
 
 ## EUDEC 2. UNDERSTAND — Understanding Protocol
@@ -247,14 +267,11 @@ Choose verification proportional to the **risk of the change**, not the file pat
 
 **Verification Fallback Ladder** (use highest available level):
 
-| Level | Method | Tools Required |
-|-------|--------|---------------|
-| 1. Automated Tests | TDD / unit / integration | Test runner |
-| 2. Approval Testing | Capture output before, diff after | diff, shell |
-| 3. Build Verification | Compiles without errors | Build tool |
-| 4. Lint/Static Analysis | No new warnings | Linter |
-| 5. Smoke Check | App starts, key routes respond | curl, browser |
-| 6. Manual Diff Review | `git diff` reviewed for regressions | git |
+| Level | Method | When |
+|-------|--------|------|
+| 1. Tests | Automated tests (unit, integration, e2e) | Test infrastructure exists |
+| 2. Build | Compiles + lint without new errors | No tests for this area |
+| 3. Diff | `git diff` reviewed for regressions | No build tooling |
 
 **Every change must have SOME verification.** If no tooling exists, `git diff` review is the minimum.
 
@@ -327,13 +344,6 @@ 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 |
@@ -343,6 +353,13 @@ Claude Code creates automatic checkpoints on every edit. Use `Esc+Esc` or `/rewi
 | **Scripts/CLI** | Language syntax check | Run with known inputs, compare outputs | Capture stdout before/after |
 | **Infra/Config** | `terraform plan`, `docker build` | Dry-run deploy | Compare plan output before/after |
 
+### 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
+
 ---
 
 ## EUDEC 5. CHECKPOINT — Confirmation Protocol
@@ -373,10 +390,12 @@ After each batch:
 3. If new targets discovered → add to plan's "Risks / Open Questions"
 4. Update plan file's `Codebase Audit` section with fresh counts
 
-**Checkpoint frequency:**
-- **Phase boundary**: always stop (mandatory)
-- **Batch boundary**: stop by default → after 3 consecutive approvals, increase batch size for the remainder
-- **Blocker encountered**: always stop (mandatory)
+**Checkpoint frequency** (proportional to task weight):
+- **Lightweight tasks**: no checkpoint pause — report completion with evidence
+- **Standard tasks**: summary checkpoint (1-2 lines: what done, verification result, next)
+- **Full tasks**: full checkpoint with progress dashboard + "Continue?"
+- **Phase boundary**: always stop (mandatory, all weights)
+- **Blocker encountered**: always stop (mandatory, all weights)
 
 **Progress dashboard:**
 ```
@@ -456,27 +475,14 @@ When a session starts:
 
 ## 7. Rationalization Defense
 
-If any of these excuses come to mind, **that's a warning signal**. Stop and return to principles:
+If any of these come to mind, **stop and return to principles**:
 
 | Excuse | Reality |
 |--------|---------|
-| "Too simple to decompose" | 3+ files = always decompose (unless migration type) |
-| "Don't want to bother the user" | If vague, must ask. No guessing |
-| "I'll add tests later" | Tests come first for high-risk changes |
-| "Just this once" | No exceptions |
-| "User said to proceed" | One approval ≠ unlimited delegation |
 | "I know what they mean" | Verify. Assumption is the root of all bugs |
-| "While I'm here, let me also..." | Scope creep. Stay on task |
-| "This is close enough" | Close ≠ correct. Verify precisely |
-| "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 `.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 |
-| "No need to simplify, just implement" | Starting without a minimal case drowns you in complexity |
-| "Expansion path can wait" | Without expansion direction, the minimal case becomes a dead end |
+| "While I'm here, let me also..." | Scope creep. Note it for later, stay on task |
+| "Too simple to decompose" | Check file count and coupling. Simple ≠ small |
+| "I'll add tests later" | High-risk changes: tests come first. No exceptions |
 
 ## 8. Completion Declaration Rules
 

package/templates/skills/prism/SKILL.md

@@ -47,12 +47,22 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
 
    | Essence Character | Type | Path |
    |-------------------|------|------|
-   | "X is broken" | Bugfix | UNDERSTAND → locate → fix → verify |
+   | "X is broken" | Bugfix | Fast Path (below) |
    | "X should be possible" | Feature | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
    | "All X must become Y" | Migration | UNDERSTAND → pattern → batch apply → verify |
    | "X's structure must change" | Refactor | UNDERSTAND → DECOMPOSE → EXECUTE → CHECKPOINT |
    | "Why does X happen?" | Investigation | explore → analyze → report |
 
+2b. **Adaptive Weight** — select EUDEC path by task size:
+
+   | Weight | Criteria | Path |
+   |--------|----------|------|
+   | **Lightweight** | 1-2 files, <50 LOC, clear scope | Essence (1 line) → Execute → Verify → Done |
+   | **Standard** | 3-5 files, 50-200 LOC | Full EUDEC, summary checkpoints |
+   | **Full** | 6+ files, 200+ LOC, or unclear scope | Full EUDEC with plan file + full checkpoints |
+
+   Lightweight skips formal UNDERSTAND and DECOMPOSE. Bugfix fast path (regardless of file count): reproduce → root cause → minimal fix → verify (skips ESSENCE/UNDERSTAND/DECOMPOSE entirely).
+
 ## U — UNDERSTAND
 
 3. **Explore first**: Read package.json, project structure, related files before asking anything
@@ -119,7 +129,7 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
     - **Medium risk** (new components with logic, API integration): Build + lint pass
     - **Low risk** (imports, types, style, renaming): Build/lint passes
     - **No test infra** (legacy PHP, WordPress, etc.): Grep-based static check + syntax validation
-    - Use **Verification Fallback Ladder**: Automated Tests → Approval Testing → Build → Lint → Smoke Check → Manual Diff Review (use highest available level)
+    - **Verification Fallback Ladder** (use highest available): Tests → Build → Diff
 21. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
 22. **Goal Recitation**: At every batch boundary, re-read the plan and confirm: "Current work aligns with: [original goal]"
 23. **Self-correction triggers (Thrashing Detector)**:
@@ -154,7 +164,7 @@ AI agents optimize for speed, not correctness. Without structure, they skip unde
 
 28. **Plan-Reality sync**: Grep for plan targets, mark vanished targets as "already completed", add newly discovered targets.
 29. Include: verification results, files modified, tests status
-30. **Checkpoint policy**: after 3 consecutive approvals, increase batch size to 5-8 for the rest of the phase
+30. **Checkpoint policy** (proportional to weight): Lightweight — no pause, report with evidence. Standard — summary (1-2 lines). Full — full dashboard + "Continue?"
 31. Ask: "Continue to next batch?"
 32. User can redirect, adjust scope, or stop at any checkpoint