@hopla/claude-setup 1.15.0 → 1.16.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "hopla",
       "description": "Agentic coding system: PIV loop, TDD, debugging, brainstorming, subagent execution, and team workflows",
-      "version": "1.15.0",
+      "version": "1.16.0",
       "source": "./",
       "author": {
         "name": "Hopla Tools",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hopla",
   "description": "Agentic coding system for Claude Code: PIV loop (Plan → Implement → Validate), TDD, debugging, brainstorming, subagent execution, and team workflows",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "author": {
     "name": "Hopla Tools",
     "email": "julio@hopla.tools"

package/cli.js

@@ -87,6 +87,21 @@ function logRemoved(label) {
     log(`  ${RED}✕${RESET}  ${verb}: ${label}`);
 }
 
+// Safe parser for settings.json-style files. Returns null when the file is
+// missing. Warns (and returns null) when the file exists but is not valid JSON
+// — previously these failures were silently swallowed, causing cleanup and
+// permission updates to skip with no signal to the user.
+function parseSettingsFile(settingsPath) {
+    if (!fs.existsSync(settingsPath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    } catch (err) {
+        log(`  ${YELLOW}⚠${RESET}  Could not parse ${settingsPath}: ${err.message}`);
+        log(`     Skipping this file. Fix the JSON and re-run to apply changes.`);
+        return null;
+    }
+}
+
 function logInstalled(label, exists) {
     const verb = DRY_RUN
         ? (exists ? "Would update" : "Would install")
@@ -220,35 +235,34 @@ function removeLegacyFiles() {
 
     // hopla hook entries from settings.json AND settings.local.json
     for (const settingsPath of SETTINGS_FILES) {
-        if (!fs.existsSync(settingsPath)) continue;
-        try {
-            const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-            let changed = false;
-
-            if (settings.hooks) {
-                for (const [event, matchers] of Object.entries(settings.hooks)) {
-                    if (!Array.isArray(matchers)) continue;
-                    const filtered = matchers.filter((m) => {
-                        if (!m.hooks || !Array.isArray(m.hooks)) return true;
-                        const isHopla = m.hooks.every((h) =>
-                            LEGACY_HOOK_COMMANDS.some((cmd) => h.command && h.command.includes(cmd))
-                        );
-                        return !isHopla;
-                    });
-                    if (filtered.length !== matchers.length) {
-                        settings.hooks[event] = filtered;
-                        if (filtered.length === 0) delete settings.hooks[event];
-                        changed = true;
-                    }
+        const settings = parseSettingsFile(settingsPath);
+        if (!settings) continue;
+
+        let changed = false;
+
+        if (settings.hooks) {
+            for (const [event, matchers] of Object.entries(settings.hooks)) {
+                if (!Array.isArray(matchers)) continue;
+                const filtered = matchers.filter((m) => {
+                    if (!m.hooks || !Array.isArray(m.hooks)) return true;
+                    const isHopla = m.hooks.every((h) =>
+                        LEGACY_HOOK_COMMANDS.some((cmd) => h.command && h.command.includes(cmd))
+                    );
+                    return !isHopla;
+                });
+                if (filtered.length !== matchers.length) {
+                    settings.hooks[event] = filtered;
+                    if (filtered.length === 0) delete settings.hooks[event];
+                    changed = true;
                 }
-                if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
             }
+            if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+        }
 
-            if (changed) {
-                safeWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-                removed.push(`hooks from ${path.basename(settingsPath)}`);
-            }
-        } catch { /* ignore parse errors */ }
+        if (changed) {
+            safeWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+            removed.push(`hooks from ${path.basename(settingsPath)}`);
+        }
     }
 
     return removed;
@@ -257,31 +271,27 @@ function removeLegacyFiles() {
 function removeHoplaPermissions() {
     const removed = [];
     for (const settingsPath of SETTINGS_FILES) {
-        if (!fs.existsSync(settingsPath)) continue;
-        try {
-            const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-            if (!settings.permissions || !Array.isArray(settings.permissions.allow)) continue;
-            const before = settings.permissions.allow.length;
-            settings.permissions.allow = settings.permissions.allow.filter(
-                (p) => !ALL_HOPLA_PERMISSIONS.has(p)
-            );
-            if (settings.permissions.allow.length !== before) {
-                safeWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-                removed.push(`permissions from ${path.basename(settingsPath)}`);
-            }
-        } catch { /* ignore */ }
+        const settings = parseSettingsFile(settingsPath);
+        if (!settings) continue;
+        if (!settings.permissions || !Array.isArray(settings.permissions.allow)) continue;
+        const before = settings.permissions.allow.length;
+        settings.permissions.allow = settings.permissions.allow.filter(
+            (p) => !ALL_HOPLA_PERMISSIONS.has(p)
+        );
+        if (settings.permissions.allow.length !== before) {
+            safeWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+            removed.push(`permissions from ${path.basename(settingsPath)}`);
+        }
     }
     return removed;
 }
 
 function detectPlugin() {
     for (const settingsPath of SETTINGS_FILES) {
-        if (!fs.existsSync(settingsPath)) continue;
-        try {
-            const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-            const plugins = settings.enabledPlugins || {};
-            if (Object.keys(plugins).some((key) => key.startsWith("hopla@"))) return true;
-        } catch { /* ignore */ }
+        const settings = parseSettingsFile(settingsPath);
+        if (!settings) continue;
+        const plugins = settings.enabledPlugins || {};
+        if (Object.keys(plugins).some((key) => key.startsWith("hopla@"))) return true;
     }
     return false;
 }
@@ -373,11 +383,16 @@ async function uninstall() {
 async function setupPermissions() {
     const settingsPath = path.join(CLAUDE_DIR, "settings.json");
 
-    let settings = { permissions: { allow: [] } };
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-        } catch { /* keep defaults */ }
+    // Use parseSettingsFile so malformed JSON is reported instead of silently
+    // overwritten. When the file is missing we start from defaults.
+    let settings = parseSettingsFile(settingsPath);
+    if (!settings) {
+        if (fs.existsSync(settingsPath)) {
+            // Malformed JSON — do NOT overwrite (user needs to fix first)
+            log(`  ${YELLOW}↷${RESET}  Skipped permissions setup — settings.json is not valid JSON.`);
+            return;
+        }
+        settings = { permissions: { allow: [] } };
     }
     if (!settings.permissions) settings.permissions = {};
     if (!settings.permissions.allow) settings.permissions.allow = [];

package/commands/execute.md

@@ -98,7 +98,7 @@ Work through each task in the plan sequentially. For each task:
 
 1. **Announce** the task you are starting (e.g., "Starting Task 2: Create the filter component")
 2. **Follow the pattern** referenced in the plan — do not invent new patterns
-3. **Check for existing implementations** — before creating new functions, constants, or utility modules, search the codebase for existing implementations that serve the same purpose. Reuse or extend rather than duplicate. DRY violations were the #1 code quality issue across 28 implementations.
+3. **Check for existing implementations** — before creating new functions, constants, or utility modules, search the codebase for existing implementations that serve the same purpose. Reuse or extend rather than duplicate.
 4. **Implement** only what the task specifies — nothing more
 5. **Validate** the task using the method specified in the plan's validate field
 6. **Report completion** with a brief status: what was done, what was skipped, any decision made
@@ -137,54 +137,15 @@ If the user requests changes that are NOT in the plan during execution:
    - Suggest committing the current planned work first
    - Then create a new branch or add it to the backlog
    - Say: "This looks like a separate feature. I recommend we commit the current work first, then handle this in a new branch. Should I add it to `.agents/plans/backlog/` instead?"
-5. **Never** silently add significant unplanned work — scope creep caused the lowest alignment score (6/10) in past implementations
+5. **Never** silently add significant unplanned work — it mixes unreviewed changes into an otherwise reviewed plan and breaks the audit trail
 
 ## Step 5: Run Full Validation Pyramid
 
-After all tasks are complete, run the full validation sequence in order.
-**Do not skip levels. Do not proceed if a level fails.**
+After all tasks are complete, run **Levels 1–7** from `commands/guides/validation-pyramid.md` (same repo). Do not skip levels. Do not proceed if a level fails.
 
-Use the exact commands from the plan's **Validation Checklist**. If not specified, read `CLAUDE.md` section "Development Commands" to find the correct commands.
+Use the exact commands from the plan's **Validation Checklist**. If not specified, read `CLAUDE.md` "Development Commands" to find the correct commands.
 
-### Level 1 — Lint & Format
-Run the project's lint and format check (e.g. `npm run lint`, `uv run ruff check .`).
-Fix any issues before continuing.
-
-### Level 2 — Type Check
-Run the project's type checker (e.g. `npm run type-check`, `uv run mypy .`).
-Fix all type errors before continuing.
-
-### Level 3 — Unit Tests
-Run the project's unit test suite (e.g. `npm run test`, `uv run pytest`).
-If tests fail:
-- Investigate the root cause
-- Fix the code (not the tests)
-- Re-run until all pass
-
-### Level 4 — Integration Tests
-Run integration tests or manual verification as specified in the plan (e.g. `npm run test:e2e`, manual curl).
-Verify the feature works end-to-end.
-
-### Level 5 — Code Review
-Run a code review on all changed files following the the `code-review` skill process. This catches bugs that linting, types, and tests miss (security issues, logic errors, pattern violations).
-
-If the review finds critical or high severity issues, **fix them before proceeding**.
-
-### Level 6 — File Drift Check
-Compare the files actually changed against the plan's task list:
-
-```bash
-git diff --name-only
-git ls-files --others --exclude-standard
-```
-
-Flag any files that were changed but are **not listed in any task**. These are potential scope leaks — unplanned additions that didn't get the same scrutiny as planned tasks. Report them in the completion summary so the user can review.
-
-### Level 7 — Human Review (flag for user)
-List what the user should manually verify:
-- Specific behaviors to test in the browser or CLI
-- Edge cases to check
-- Any decisions made during implementation that the user should review
+Level 5 triggers the `code-review` skill (not a slash command). Level 6 is the file-drift check specific to plan execution. Level 7 surfaces items for human verification.
 
 ## Step 6: Completion Report
 

package/commands/guides/validation-pyramid.md

@@ -0,0 +1,74 @@
+# Validation Pyramid
+
+Shared reference for the full validation sequence. Callers (`commands/execute.md`, `commands/validate.md`, `skills/verify/SKILL.md`, plus plans' `Validation Checklist`) pick the levels that apply to their scope.
+
+Run levels **in order**. Do not skip a level. Do not proceed if a level fails — fix it first.
+
+Commands below are generic examples; use the exact commands from the project's `CLAUDE.md` "Development Commands" section or the plan's checklist.
+
+## Level 1 — Lint & Format
+
+Run the project's lint and format commands (e.g. `npm run lint`, `uv run ruff check .`).
+
+If issues are found:
+
+- Fix them automatically where the tool supports it (e.g. `--fix`)
+- Re-run to confirm clean
+
+## Level 2 — Type Check
+
+Run the project's type checker (e.g. `npm run typecheck`, `tsc --noEmit`, `uv run mypy .`).
+
+Fix all type errors before continuing.
+
+## Level 3 — Unit Tests
+
+Run the project's unit test suite (e.g. `npm run test`, `uv run pytest`).
+
+If tests fail:
+
+- Investigate the root cause
+- Fix the code (not the tests, unless the test is wrong)
+- Re-run until all pass
+
+## Level 4 — Integration Tests
+
+Run integration tests if the project has them (e.g. `npm run test:e2e`, manual curl).
+
+If not available, skip and note it in the report.
+
+## Level 5 — Code Review
+
+Trigger the `code-review` skill on the changed files. This catches bugs that lint, types, and tests miss (security issues, logic errors, pattern violations).
+
+If the review finds `critical` or `high` severity issues, **fix them before proceeding**.
+
+## Level 6 — File Drift Check (post-execution only)
+
+Compare the files actually changed against the plan's task list:
+
+```bash
+git diff --name-only
+git ls-files --others --exclude-standard
+```
+
+Flag any files that were changed but are **not listed in any task**. These are potential scope leaks — report them in the completion summary so the user can review.
+
+Skip this level when validating outside of a plan (`/hopla:validate` or the `verify` skill without a plan).
+
+## Level 7 — Human Review
+
+Flag for the user what they should verify manually:
+
+- Specific behaviors to test in the browser or CLI
+- Edge cases to check
+- Any decisions made during implementation that the user should review
+
+## Which levels apply when
+
+| Caller | Levels |
+|---|---|
+| `/hopla:validate` | 1–4 |
+| `verify` skill | 1–4 + 7 |
+| `/hopla:execute` | 1–7 |
+| Plan's `Validation Checklist` | as specified by the plan, typically 1–5 or 1–7 |

package/commands/plan-feature.md

@@ -47,7 +47,7 @@ Investigate the areas of the codebase relevant to this feature:
 - Locate similar features already implemented to use as reference
 - Find the entry points that will need to be modified or extended
 - Identify potential conflicts or dependencies
-- **DRY check:** Before specifying new utility functions, constants, or helpers in the plan, search for existing implementations that can be reused or extended. DRY violations were the #1 code review finding across 28 implementations.
+- **DRY check:** Before specifying new utility functions, constants, or helpers in the plan, search for existing implementations that can be reused or extended.
 
 Use the Grep tool to find relevant files (pattern: relevant keyword, case-insensitive).
 
@@ -60,7 +60,7 @@ For each existing table, API endpoint, or component the plan will modify, verify
 - **API endpoints:** Read the actual route handler. Confirm the request/response shape matches your assumptions.
 - **Components:** Read the component file. Confirm props, state, and data flow match your assumptions.
 
-Document verified assumptions in the plan's **Context References** with the exact file and line number. This prevents the #1 cause of mid-implementation redesigns: plans that assumed a field name, type, or constraint that didn't match reality.
+Document verified assumptions in the plan's **Context References** with the exact file and line number. This prevents mid-implementation redesigns caused by plans that assumed a field name, type, or constraint that did not match reality.
 
 ### Data audit (required for features that consume existing data)
 
@@ -79,17 +79,17 @@ Based on research, define:
 - Any risks, edge cases, or gotchas to flag
 - What tests are needed
 - **Derived/computed values:** If any value is calculated from other fields, specify the exact formula including how stored values are interpreted (sign, units, semantics), AND how derived values propagate when inputs change (event system, reactivity, polling, etc.)
-- **Interaction states & edge cases:** For features involving interactive UI (forms, grids, keyboard navigation, wizards, CLI interactions), define a matrix of user interactions and their expected behavior. Cover: all keyboard shortcuts (both directions — e.g., Tab AND Shift+Tab), state transitions (empty → editing → saved → error), and boundary conditions (first item, last item, empty list, maximum items). This prevents iterative fix rounds that consumed up to 40% of session time in past implementations.
-- **API input validation:** For every API endpoint being created or modified, specify: required fields, field format constraints (e.g., "IMEI must be exactly 15 digits"), payload size limits, and what the user sees on validation failure. This was the #2 most common gap in past plans — validation was only added after code review in 4 of 7 implementations.
-- **Bidirectional data interactions:** If feature A updates data that feature B displays, does B need to react? If adding an item triggers validation, does editing trigger re-validation? Map all data mutation → side effect chains, not just keyboard navigation. Missed bidirectional interactions were a recurring planning blind spot.
+- **Interaction states & edge cases:** For features involving interactive UI (forms, grids, keyboard navigation, wizards, CLI interactions), define a matrix of user interactions and their expected behavior. Cover: all keyboard shortcuts (both directions — e.g., Tab AND Shift+Tab), state transitions (empty → editing → saved → error), and boundary conditions (first item, last item, empty list, maximum items).
+- **API input validation:** For every API endpoint being created or modified, specify: required fields, field format constraints (e.g., "IMEI must be exactly 15 digits"), payload size limits, and what the user sees on validation failure.
+- **Bidirectional data interactions:** If feature A updates data that feature B displays, does B need to react? If adding an item triggers validation, does editing trigger re-validation? Map all data mutation → side effect chains, not just keyboard navigation.
 - **AI/LLM prompt tasks:** If the plan involves creating or modifying AI prompts (system prompts, prompt templates, LLM-based features), add an explicit task for testing against real data with 2-3 iteration cycles budgeted. AI prompt engineering rarely works on the first attempt.
-- **User preferences check:** Before specifying UI architecture (modal vs. inline, page vs. panel, dialog vs. drawer), verify against MEMORY.md and conversation history for established preferences. In past implementations, plans that specified modals were rejected because the user preferred inline panels — this caused rework. When no preference exists, note it as a decision point for the user to confirm.
-- **Reuse context analysis:** When a new view reuses an existing component in a different context (e.g., a list component in a "history" view vs. an "active" view), the plan MUST list what's different about the new context's requirements: different columns, different data filters, different interactions, different toolbar layout. Missed context differences caused 40%+ of unplanned work in past implementations.
+- **User preferences check:** Before specifying UI architecture (modal vs. inline, page vs. panel, dialog vs. drawer), verify against `MEMORY.md` and conversation history for established preferences. When no preference exists, note it as a decision point for the user to confirm.
+- **Reuse context analysis:** When a new view reuses an existing component in a different context (e.g., a list component in a "history" view vs. an "active" view), the plan MUST list what's different about the new context's requirements: different columns, different data filters, different interactions, different toolbar layout.
 - **Multi-phase plan guidance:** For features requiring 3+ phases, create an architectural plan (`backlog/NN-feature.md`) with schema, phase boundaries, and target architecture. When executing each phase, create a standalone plan (`phase-NX-description.md`) with full task-level detail following this template. The architectural plan is the spec; phase plans are the execution instructions. Each phase should have its own feature branch and PR.
-- **API surface enumeration (security/access control plans):** When the plan modifies access control, authorization, or data visibility, enumerate ALL API surfaces that serve the same data — REST endpoints, WebSocket handlers, Durable Object methods, and any other data paths. Each surface must be updated consistently. In past implementations, updating only the WebSocket path while missing the parallel REST endpoint caused a security gap that was only caught by code review. Add a task for each surface, not just the primary one.
-- **Role access matrix:** For features involving multiple user roles or multi-tenant access (admin, member, viewer, buyer, external user), define a matrix: what data does each role see? What endpoints does each role call? What filters apply per role? In past implementations, plans that didn't specify role-level access had authorization bugs discovered only during code review.
-- **External integration buffer:** If the feature integrates an external API or third-party service, budget 2x the estimated time. Document: do we have working test credentials? Is the SDK tested in our runtime (Workers, Node, edge, etc.)? Are there known deprecations or version constraints? External integrations consistently took 2-3x longer than planned in past implementations.
-- **UI iteration budget:** For features with significant UI (new pages, complex forms, interactive grids), note that UI specifications are provisional — expect 30-50% additional work for visual refinement based on user feedback. Specify what "good enough for v1" looks like vs. future polish. This prevents scope creep from being classified as plan failure.
+- **API surface enumeration (security/access control plans):** When the plan modifies access control, authorization, or data visibility, enumerate ALL API surfaces that serve the same data — REST endpoints, WebSocket handlers, Durable Object methods, and any other data paths. Each surface must be updated consistently. Add a task for each surface, not just the primary one.
+- **Role access matrix:** For features involving multiple user roles or multi-tenant access (admin, member, viewer, buyer, external user), define a matrix: what data does each role see? What endpoints does each role call? What filters apply per role?
+- **External integration buffer:** If the feature integrates an external API or third-party service, budget 2x the estimated time. Document: do we have working test credentials? Is the SDK tested in our runtime (Workers, Node, edge, etc.)? Are there known deprecations or version constraints?
+- **UI iteration budget:** For features with significant UI (new pages, complex forms, interactive grids), note that UI specifications are provisional — visual polish typically needs iteration on user feedback. Specify what "good enough for v1" looks like vs. future polish so scope creep is not classified as plan failure.
 
 ## Phase 5: Generate the Plan
 
@@ -112,7 +112,7 @@ Use this structure:
 - [Anything explicitly excluded]
 
 ## Likely Follow-ups
-[Features or changes naturally adjacent to this work that the user may request during or after execution. Historical data: 71% of sessions had scope expansion. Listing these upfront helps the executing agent handle them via the Scope Guard rather than improvising.]
+[Features or changes naturally adjacent to this work that the user may request during or after execution. Listing these upfront helps the executing agent handle scope expansion via the Scope Guard rather than improvising.]
 - [Follow-up 1]
 - [Follow-up 2]
 
@@ -195,7 +195,7 @@ Scoring guide:
 ## Notes for Executing Agent
 [Any important context, warnings, or decisions made during planning that the executing agent needs to know]
 
-> **UI Styling Note:** UI styling specifications (colors, sizes, variants, labels, spacing) are `[provisional]` proposals. Historical data shows these change in 50%+ of implementations based on user feedback. Implement as specified but do not over-invest in pixel-perfect adherence — expect iteration.
+> **UI Styling Note:** UI styling specifications (colors, sizes, variants, labels, spacing) are `[provisional]` proposals — expect them to change once the user sees the implementation. Implement as specified but do not over-invest in pixel-perfect adherence; plan for iteration.
 ```
 
 ---
@@ -206,7 +206,7 @@ After generating the plan, count the implementation tasks (excluding test tasks)
 
 - **3–7 tasks:** Optimal size. Proceed as-is.
 - **8–11 tasks:** Consider grouping tasks into logical phases with intermediate commit points. Add a `## Phase Boundaries` section to the plan listing where commits should happen.
-- **12+ tasks:** The plan should be split into multiple plans or phased with mandatory intermediate commits. Historical data: plans with 12+ tasks scored 6/10 alignment vs 10/10 for 3–7 task plans. Add phase boundaries and consider whether independent task groups can be separate plans.
+- **12+ tasks:** The plan should be split into multiple plans or phased with mandatory intermediate commits. Large plans tend to drift during execution; phase boundaries give reviewers and the executing agent natural checkpoints. Consider whether independent task groups can be separate plans.
 
 ---
 
@@ -231,7 +231,7 @@ Before saving the draft, review the plan against these criteria:
 - [ ] **Plan size checked:** If >8 tasks, phase boundaries are defined with intermediate commit points. If >12 tasks, split justification is provided or phases are created.
 - [ ] **Likely follow-ups listed:** If the Out of Scope section has items, the Likely Follow-ups section is populated with naturally adjacent work the user may request
 - [ ] **API surface enumeration (if security/access plan):** All parallel API surfaces (REST, WebSocket, DO) that serve the same data are listed with a task for each
-- [ ] **N+1 query check:** For every task that writes database queries or API calls, verify: is any call inside a loop? Could it be batched? Are there duplicate existence checks before mutations? N+1 queries were found in 5 of 13 recent implementations.
+- [ ] **N+1 query check:** For every task that writes database queries or API calls, verify: is any call inside a loop? Could it be batched? Are there duplicate existence checks before mutations?
 
 ## Phase 7: Save Draft and Enter Review Loop
 

package/commands/validate.md

@@ -14,36 +14,9 @@ If a `.claude/commands/validate.md` exists at the project root, use the commands
 
 ## Step 2: Run the Validation Pyramid
 
-Execute each level in order. **Do not skip levels. Do not proceed if a level fails — fix it first.**
+Execute levels **1–4** from `commands/guides/validation-pyramid.md` (same repo). Do not skip levels. Do not proceed if a level fails — fix it first.
 
-### Level 1 — Lint & Format
-
-Run the project's lint and format commands (e.g. `npm run lint`, `uv run ruff check .`).
-
-If issues are found:
-- Fix them automatically if the tool supports it (e.g. `--fix`)
-- Re-run to confirm clean
-
-### Level 2 — Type Check
-
-Run the project's type checker (e.g. `npm run typecheck`, `uv run mypy .`).
-
-Fix all type errors before continuing.
-
-### Level 3 — Unit Tests
-
-Run the project's test suite (e.g. `npm run test`, `uv run pytest`).
-
-If tests fail:
-- Investigate the root cause
-- Fix the code (not the tests, unless the test is wrong)
-- Re-run until all pass
-
-### Level 4 — Integration Tests
-
-Run integration tests if the project has them (e.g. `npm run test:e2e`).
-
-If not available, skip and note it in the report.
+Use the exact commands from the project's `CLAUDE.md` "Development Commands" section. If a `.claude/commands/validate.md` exists at the project root, use the commands defined there instead.
 
 ## Step 3: Summary Report
 
@@ -72,4 +45,4 @@ If anything failed and could not be fixed, list the remaining issues and suggest
 ## Next Step
 
 After validation passes, suggest:
-> "All validation levels passed. Consider running the `code-review` skill for a deeper analysis — code review catches bugs in 79% of implementations that pass automated validation (stale closures, missing input validation, route shadowing, unhandled promise rejections). Run the `code-review` skill to check, or the `git` skill (say "commit") to commit directly."
+> "All validation levels passed. Consider triggering the `code-review` skill for a deeper analysis — it catches classes of bugs that lint/types/tests miss (stale closures, missing input validation, route shadowing, unhandled promise rejections). Say 'review the code' to trigger it, or say 'commit' to use the `git` skill directly."

package/hooks/session-prime.js

@@ -13,6 +13,18 @@ function run(cmd) {
     }
 }
 
+function excerptClaudeMd(content) {
+    const lines = content.split("\n");
+    // Prefer the first `---` separator after the opening heading and first section
+    for (let i = 5; i < Math.min(lines.length, 120); i++) {
+        if (lines[i].trim() === "---") {
+            return lines.slice(0, i).join("\n").trimEnd();
+        }
+    }
+    // No separator within a reasonable window — cap at 60 lines
+    return lines.slice(0, Math.min(lines.length, 60)).join("\n").trimEnd();
+}
+
 function discoverSkills() {
     // Try plugin context first: ../skills/ relative to this script
     const hookDir = import.meta.dirname;
@@ -85,11 +97,11 @@ async function main() {
         }
     }
 
-    // CLAUDE.md summary (first 20 lines)
+    // CLAUDE.md excerpt — cut at a natural boundary, not a fixed line count
     const claudeMdPath = path.join(process.cwd(), "CLAUDE.md");
     if (fs.existsSync(claudeMdPath)) {
-        const content = fs.readFileSync(claudeMdPath, "utf8").split("\n").slice(0, 20).join("\n");
-        lines.push(`Project rules (CLAUDE.md excerpt):\n${content}`);
+        const excerpt = excerptClaudeMd(fs.readFileSync(claudeMdPath, "utf8"));
+        lines.push(`Project rules (CLAUDE.md excerpt):\n${excerpt}`);
     }
 
     // Auto-discover available skills

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {
@@ -16,6 +16,10 @@
     "hooks/",
     ".claude-plugin/"
   ],
+  "scripts": {
+    "prepublishOnly": "node scripts/check-versions.js",
+    "check-versions": "node scripts/check-versions.js"
+  },
   "engines": {
     "node": ">=18"
   },

package/skills/code-review/SKILL.md

@@ -14,7 +14,7 @@ Read `CLAUDE.md` or `AGENTS.md` to understand project standards and patterns.
 
 If `.agents/guides/` exists, read any guides relevant to the files being reviewed (e.g. `@.agents/guides/api-guide.md` when reviewing API changes). These guides define the expected patterns for specific task types.
 
-If `.agents/guides/review-checklist.md` exists, read it and apply the project-specific checks it defines in addition to the standard checks below. Project-specific checklists cover framework gotchas and domain anti-patterns unique to the project (e.g., AG Grid stale closures, Hono route ordering).
+If `.agents/guides/review-checklist.md` exists, read it and apply the project-specific checks it defines in addition to the standard checks. Project-specific checklists cover framework gotchas and domain anti-patterns unique to the project (e.g., grid stale closures, route ordering).
 
 ## Step 2: Identify Changed Files
 
@@ -28,42 +28,16 @@ Read each changed or new file in its entirety — not just the diff.
 
 ## Step 3: Analyze for Issues
 
-For each changed file, look for:
-
-**1. Logic Errors**
-- Off-by-one errors, incorrect conditionals
-- Missing error handling, unhandled edge cases
-- Race conditions or async issues
-- Stale closures — callbacks passed to imperative APIs (grids, charts, maps) that capture stale state instead of using refs or stable references
-- Unhandled promise rejections — `.then()` without `.catch()`, async calls without `try/catch` in non-void contexts
-- Side effects inside JSX render — mutations of arrays/objects inside `.map()` in JSX (breaks React strict mode, causes double-execution bugs)
-- Stale dependency arrays — for every new `useState`/`useRef` variable introduced in the diff, verify it appears in the dependency arrays of `useEffect`, `useCallback`, or `useMemo` that reference it. Missing deps cause stale closures — this was the #1 React bug category across 28 implementations
-
-**2. Security Issues**
-- Exposed secrets or API keys
-- SQL/command injection vulnerabilities
-- Missing input validation on API endpoints — required fields, format constraints (regex, length), payload size limits
-- Insecure data handling — raw user input in queries, responses exposing internal data or stack traces
-- XSS vulnerabilities (frontend)
-- Multi-user authorization context — for multi-tenant apps, verify each endpoint filters by the correct context (e.g., active org vs personal org, admin vs viewer). Check that middleware/auth guards match the intended audience for each route
-
-**3. Performance Problems**
-- Unnecessary re-renders (React)
-- N+1 queries — database queries or API calls inside loops (`for`, `.map`, `.forEach`), duplicate existence checks before mutations, sequential operations that could use `Promise.all()` or batch SQL. This was found in 5 of 13 recent implementations
-- Memory leaks
-
-**4. Code Quality**
-- DRY violations — before flagging, search for similar functions/constants elsewhere in the codebase; suggest extraction to a shared module if the same logic exists in multiple places
-- Poor naming or overly complex functions
-- Missing TypeScript types or `any` usage
-
-**5. Pattern Adherence**
-- Follows project conventions from CLAUDE.md
-- Consistent with existing codebase style
-
-**6. Route & Middleware Ordering**
-- Static routes defined AFTER parameterized routes (e.g., `/users/all` after `/users/:id`) causing shadowing — the parameterized route captures requests meant for the static one
-- Middleware applied in incorrect order (e.g., auth after route handler, CORS after response sent)
+Apply the full checklist in `checklist.md` (same directory). It covers:
+
+1. Logic errors (stale closures, unhandled rejections, missing deps)
+2. Security (secrets, injection, input validation, multi-tenant auth)
+3. Performance (N+1, re-renders, memory leaks)
+4. Code quality (DRY, naming, types)
+5. Pattern adherence (project conventions)
+6. Route & middleware ordering
+
+Read `checklist.md` before reviewing so you apply every category.
 
 ## Step 4: Verify Issues Are Real
 
@@ -73,9 +47,10 @@ Before reporting, confirm each issue is legitimate:
 
 ## Step 5: Output Report
 
-Save to `.agents/code-reviews/[descriptive-name].md`
+Save to `.agents/code-reviews/[descriptive-name].md`.
 
 **Format for each issue:**
+
 ```
 severity: critical | high | medium | low
 file: path/to/file.ts
@@ -88,6 +63,7 @@ suggestion: [how to fix it]
 If no issues found: "Code review passed. No technical issues detected."
 
 **Rules:**
+
 - Be specific — line numbers, not vague complaints
 - Focus on real bugs, not style preferences (linting handles that)
 - Flag security issues as `critical`
@@ -96,4 +72,5 @@ If no issues found: "Code review passed. No technical issues detected."
 ## Next Step
 
 After the review, suggest:
+
 > "Code review saved to `.agents/code-reviews/[name].md`. If issues were found, run `/hopla:code-review-fix .agents/code-reviews/[name].md` to fix them. If the review passed clean, proceed to the `execution-report` skill."

package/skills/code-review/checklist.md

@@ -0,0 +1,44 @@
+# Code Review Checklist
+
+Apply every category to every changed file. Severity guidance is in the parent `SKILL.md`.
+
+## 1. Logic Errors
+
+- Off-by-one errors, incorrect conditionals
+- Missing error handling, unhandled edge cases
+- Race conditions or async issues
+- Stale closures — callbacks passed to imperative APIs (grids, charts, maps) that capture stale state instead of using refs or stable references
+- Unhandled promise rejections — `.then()` without `.catch()`, async calls without `try/catch` in non-void contexts
+- Side effects inside JSX render — mutations of arrays/objects inside `.map()` in JSX (breaks React strict mode, causes double-execution bugs)
+- Stale dependency arrays — for every new `useState`/`useRef` variable introduced in the diff, verify it appears in the dependency arrays of `useEffect`, `useCallback`, or `useMemo` that reference it. Missing deps cause stale closures and are a recurring source of React bugs.
+
+## 2. Security Issues
+
+- Exposed secrets or API keys
+- SQL/command injection vulnerabilities
+- Missing input validation on API endpoints — required fields, format constraints (regex, length), payload size limits
+- Insecure data handling — raw user input in queries, responses exposing internal data or stack traces
+- XSS vulnerabilities (frontend)
+- Multi-user authorization context — for multi-tenant apps, verify each endpoint filters by the correct context (e.g., active org vs personal org, admin vs viewer). Check that middleware/auth guards match the intended audience for each route.
+
+## 3. Performance Problems
+
+- Unnecessary re-renders (React)
+- N+1 queries — database queries or API calls inside loops (`for`, `.map`, `.forEach`), duplicate existence checks before mutations, sequential operations that could use `Promise.all()` or batch SQL
+- Memory leaks (event listeners not detached, timers not cleared, closures holding large objects)
+
+## 4. Code Quality
+
+- DRY violations — before flagging, search for similar functions/constants elsewhere in the codebase; suggest extraction to a shared module if the same logic exists in multiple places
+- Poor naming or overly complex functions
+- Missing TypeScript types or `any` usage
+
+## 5. Pattern Adherence
+
+- Follows project conventions from `CLAUDE.md`
+- Consistent with existing codebase style
+
+## 6. Route & Middleware Ordering
+
+- Static routes defined AFTER parameterized routes (e.g., `/users/all` after `/users/:id`) causing shadowing — the parameterized route captures requests meant for the static one
+- Middleware applied in incorrect order (e.g., auth after route handler, CORS after response sent)

package/skills/execution-report/SKILL.md

@@ -22,97 +22,30 @@ Also check for recent code reviews:
 ls -t .agents/code-reviews/ 2>/dev/null | head -5
 ```
 
-If a code review exists for this feature, note its path for the Code Review Findings section below.
+If a code review exists for this feature, note its path for the Code Review Findings section.
 
-## Step 2: Generate Report
+## Step 2: Generate the Report
 
-Save to: `.agents/execution-reports/[feature-name].md`
+Save to: `.agents/execution-reports/[feature-name].md`.
 
-Use the following structure:
+Use the full structure documented in `report-structure.md` (same directory). It covers:
 
----
-
-### Meta Information
-
-- **Plan file:** [path to the plan that guided this implementation]
-- **Files added:** [list with paths]
-- **Files modified:** [list with paths]
-- **Lines changed:** +X -Y
-
-### Validation Results
-
-- Syntax & Linting: ✓/✗ [details if failed]
-- Type Checking: ✓/✗ [details if failed]
-- Unit Tests: ✓/✗ [X passed, Y failed]
-- Integration Tests: ✓/✗ [X passed, Y failed]
-
-### Code Review Findings
-
-- **Code review file:** [path to `.agents/code-reviews/[name].md`, or "Not run"]
-- **Issues found:** [count by severity: X critical, Y high, Z medium, W low]
-- **Issues fixed before this report:** [count]
-- **Key findings:** [1-2 sentence summary of the most significant issues found]
-
-### What Went Well
-
-List specific things that worked smoothly:
-- [concrete examples]
-
-### Challenges Encountered
-
-List specific difficulties encountered:
-- [what was difficult and why]
-
-### Bugs Encountered
-
-Categorize each bug found during implementation:
-
-| Bug | Category | Found By | Severity |
-|-----|----------|----------|----------|
-| [description] | stale closure / validation / race condition / styling / scope mismatch / type error / route ordering / other | lint / types / tests / code review / manual testing | critical / high / medium / low |
+- Meta information (plan file, files added/modified, lines changed)
+- Validation results
+- Code review findings
+- What went well
+- Challenges encountered
+- Bugs encountered (with categorization table)
+- Divergences from plan
+- Scope assessment
+- Skipped items
+- Technical patterns discovered (with ready-to-paste CLAUDE.md entry)
+- Recommendations
 
-If no bugs were encountered, write "No bugs encountered during implementation."
-
-### Divergences from Plan
-
-For each divergence from the original plan:
-
-**[Divergence Title]**
-- **Planned:** [what the plan specified]
-- **Actual:** [what was implemented instead]
-- **Reason:** [why this divergence occurred]
-- **Type:** Better approach found | Plan assumption wrong | Security concern | Performance issue | Other
-
-### Scope Assessment
-
-- **Planned tasks:** [number of tasks in the original plan]
-- **Executed tasks:** [number of tasks actually completed]
-- **Unplanned additions:** [count and brief description of work not in the original plan]
-- **Scope accuracy:** On target | Under-scoped (took more work than planned) | Over-scoped (simpler than expected)
-
-### Skipped Items
-
-List anything from the plan that was not implemented:
-- [what was skipped] — Reason: [why]
-
-### Technical Patterns Discovered
-
-New gotchas, patterns, or conventions learned during this implementation that should be documented:
-
-- **Pattern/Gotcha:** [description]
-- **Where it applies:** [what type of feature or context triggers this]
-- **Ready-to-paste CLAUDE.md entry:** [Write the EXACT text that should be added to the project's CLAUDE.md to prevent this gotcha in future features. Format it as a bullet point under the appropriate section. If it belongs in a guide instead, write the exact text for the guide. Do not write vague suggestions like "document this" — write the actual content so the system reviewer can apply it directly.]
-
-If nothing new was discovered, write "No new patterns discovered."
-
-### Recommendations
-
-Based on this implementation, what should change for next time?
-- Plan command improvements: [suggestions]
-- Execute command improvements: [suggestions]
-- CLAUDE.md additions: [suggestions]
+Read `report-structure.md` before writing so every section is filled correctly.
 
 ## Next Step
 
 After the report is saved, suggest:
-> "Execution report saved to `.agents/execution-reports/[name].md`. Run the `git` skill (say "commit") to commit your changes."
+
+> "Execution report saved to `.agents/execution-reports/[name].md`. Use the `git` skill (say 'commit') to save your changes."

package/skills/execution-report/report-structure.md

@@ -0,0 +1,88 @@
+# Execution Report Structure
+
+Fill every section. Write "Not applicable" rather than leaving a section blank — empty sections make it unclear whether the check was performed.
+
+## Meta Information
+
+- **Plan file:** [path to the plan that guided this implementation]
+- **Files added:** [list with paths]
+- **Files modified:** [list with paths]
+- **Lines changed:** +X −Y
+
+## Validation Results
+
+- Syntax & Linting: ✓/✗ [details if failed]
+- Type Checking: ✓/✗ [details if failed]
+- Unit Tests: ✓/✗ [X passed, Y failed]
+- Integration Tests: ✓/✗ [X passed, Y failed]
+
+## Code Review Findings
+
+- **Code review file:** [path to `.agents/code-reviews/[name].md`, or "Not run"]
+- **Issues found:** [count by severity: X critical, Y high, Z medium, W low]
+- **Issues fixed before this report:** [count]
+- **Key findings:** [1-2 sentence summary of the most significant issues found]
+
+## What Went Well
+
+List specific things that worked smoothly:
+
+- [concrete examples]
+
+## Challenges Encountered
+
+List specific difficulties:
+
+- [what was difficult and why]
+
+## Bugs Encountered
+
+Categorize each bug found during implementation:
+
+| Bug | Category | Found By | Severity |
+|-----|----------|----------|----------|
+| [description] | stale closure / validation / race condition / styling / scope mismatch / type error / route ordering / other | lint / types / tests / code review / manual testing | critical / high / medium / low |
+
+If no bugs were encountered, write "No bugs encountered during implementation."
+
+## Divergences from Plan
+
+For each divergence:
+
+**[Divergence Title]**
+
+- **Planned:** [what the plan specified]
+- **Actual:** [what was implemented instead]
+- **Reason:** [why this divergence occurred]
+- **Type:** Better approach found | Plan assumption wrong | Security concern | Performance issue | Other
+
+## Scope Assessment
+
+- **Planned tasks:** [number in the original plan]
+- **Executed tasks:** [number actually completed]
+- **Unplanned additions:** [count and brief description of work not in the original plan]
+- **Scope accuracy:** On target | Under-scoped (took more work than planned) | Over-scoped (simpler than expected)
+
+## Skipped Items
+
+List anything from the plan that was not implemented:
+
+- [what was skipped] — Reason: [why]
+
+## Technical Patterns Discovered
+
+New gotchas, patterns, or conventions learned during this implementation that should be documented:
+
+- **Pattern/Gotcha:** [description]
+- **Where it applies:** [what type of feature or context triggers this]
+- **Ready-to-paste CLAUDE.md entry:** [Write the EXACT text that should be added to the project's CLAUDE.md to prevent this gotcha in future features. Format it as a bullet point under the appropriate section. If it belongs in a guide instead, write the exact text for the guide. Do not write vague suggestions like "document this" — write the actual content so the system reviewer can apply it directly.]
+
+If nothing new was discovered, write "No new patterns discovered."
+
+## Recommendations
+
+Based on this implementation, what should change for next time?
+
+- Plan command improvements: [suggestions]
+- Execute command improvements: [suggestions]
+- CLAUDE.md additions: [suggestions]

package/skills/verify/SKILL.md

@@ -47,13 +47,7 @@ Instead, run the verification and report actual results.
 
 ## Integration with Validation Pyramid
 
-When completing a feature (not just a single file edit), run the full validation pyramid:
-
-1. **Level 1**: Lint & format
-2. **Level 2**: Type check
-3. **Level 3**: Unit tests
-4. **Level 4**: Integration tests (if applicable)
-5. **Level 5**: Human review suggestion
+When completing a feature (not just a single file edit), run levels **1–4 + 7** from `commands/guides/validation-pyramid.md` (Lint, Types, Unit, Integration, Human review).
 
 Reference `/hopla:validate` for project-specific validation commands.
 
@@ -72,3 +66,14 @@ When verifying completion of a plan execution (not just a standalone task):
 3. **All acceptance criteria met?** — Read the plan's acceptance criteria and verify each one has fresh evidence.
 
 These checks prevent the common pattern where implementation is "done" but divergences are silently omitted from the report.
+
+## Authoritative post-implementation sequence
+
+When verification passes, follow this order to avoid redundant work and skill overlap:
+
+1. **`verify`** (this skill) — confirm fresh evidence for every completion claim.
+2. **`code-review`** — run technical review on changed files. Fix `critical`/`high` issues before proceeding.
+3. **`execution-report`** — document what was built, bugs found, divergences, patterns discovered.
+4. **`git`** — commit (and PR when ready).
+
+Each step cites the next, so at any point you should be routing to exactly one subsequent skill. If multiple skills are triggering simultaneously on a completion claim, this is the canonical ordering.