@hopla/claude-setup 1.15.0 → 1.17.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.17.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.17.0",
   "author": {
     "name": "Hopla Tools",
     "email": "julio@hopla.tools"

package/README.md

@@ -233,6 +233,9 @@ After each PIV loop, run the `execution-report` skill + `/hopla:system-review` t
 | `brainstorm` | "let's brainstorm", "explore approaches" |
 | `debug` | "debug this", "find the bug", "why is this failing" |
 | `tdd` | "write tests first", "TDD", "red-green-refactor" |
+| `refactoring` | "refactor", "clean up", "simplify", "extract", "deduplicate" |
+| `performance` | "slow", "optimize", "bottleneck", "lento", "tarda mucho" |
+| `migration` | "migrate", "upgrade", "switch from X to Y", "major version bump" |
 | `subagent-execution` | "use subagents", plans with 5+ tasks |
 | `parallel-dispatch` | "run in parallel", "parallelize this", independent tasks |
 
@@ -441,6 +444,7 @@ project/
 │   ├── rca/                       ← Root cause analysis docs (commit)
 │   ├── execution-reports/         ← Post-implementation reports (commit)
 │   ├── system-reviews/            ← Process improvement reports (commit)
+│   ├── audits/                    ← Persistent audit reports (commit — opt-in)
 │   └── code-reviews/              ← Code review reports (don't commit — ephemeral)
 └── .claude/
     └── commands/                  ← Project-specific commands (optional)

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/init-project.md

@@ -435,9 +435,15 @@ Create the following directories (with `.gitkeep` where needed):
 ├── rca/                 <- /hopla:rca saves root cause analysis docs here (commit)
 ├── execution-reports/   <- the `execution-report` skill saves here (commit — needed for cross-session learning)
 ├── system-reviews/      <- /hopla:system-review saves here (commit — needed for feedback loop)
+├── audits/              <- persistent audit reports worth preserving (commit — opt-in; copy a code review here when you want to keep it)
 └── code-reviews/        <- the `code-review` skill saves here (do NOT commit — ephemeral, consumed by code-review-fix)
 ```
 
+**Policy — `audits/` vs `code-reviews/`:**
+
+- `code-reviews/` is **ephemeral working state**. Every run overwrites/adds files; `code-review-fix` consumes them and they become stale fast. Never commit.
+- `audits/` is **persistent**. Move or copy a review here when it documents a finding the team should remember (security issue, architectural concern, post-mortem evidence). Commit.
+
 Add to `.gitignore` (create if it doesn't exist):
 ```
 .agents/code-reviews/

package/commands/plan-feature.md

@@ -27,8 +27,9 @@ Read the following to understand the project:
 2. `README.md` — project overview and setup
 3. `package.json` or `pyproject.toml` — stack, dependencies, scripts
 4. `.agents/guides/` — if this directory exists, read any guides relevant to the feature being planned (e.g. `@.agents/guides/api-guide.md` when planning an API endpoint)
-5. `MEMORY.md` (if it exists at project root or `~/.claude/`) — check for user preferences that affect this feature (UI patterns like modal vs inline, keyboard shortcuts, component conventions)
-6. `.agents/execution-reports/` — if this directory exists, scan recent reports (last 3-5) for technical patterns discovered and gotchas relevant to the feature being planned. These contain real-world learnings from previous implementations that prevent re-discovering known issues.
+5. `.agents/specs/` — if this directory exists, scan for design specs that match the feature name. These come from the `brainstorm` skill and already document the chosen approach, files affected, edge cases, and open questions. If a matching spec exists, it is the authoritative design — the plan turns that design into tasks. If no spec exists and the feature is non-trivial, suggest running the `brainstorm` skill first.
+6. `MEMORY.md` (if it exists at project root or `~/.claude/`) — check for user preferences that affect this feature (UI patterns like modal vs inline, keyboard shortcuts, component conventions)
+7. `.agents/execution-reports/` — if this directory exists, scan recent reports (last 3-5) for technical patterns discovered and gotchas relevant to the feature being planned. These contain real-world learnings from previous implementations that prevent re-discovering known issues.
 
 Then run:
 
@@ -47,7 +48,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 +61,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 +80,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 +113,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 +196,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 +207,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 +232,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.17.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/migration/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: migration
+description: "Phased migration workflow for upgrading dependencies, switching frameworks, or moving between systems. Use when the user says 'migrate', 'upgrade', 'switch from X to Y', 'move to', 'replace library', 'major version bump', 'deprecated', or when changing a framework/runtime/database version. Do NOT use for greenfield features or small refactors — use plan-feature or refactoring instead."
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+# Migration: Move Systems Without Breaking Them
+
+## Iron Rule
+
+**Every migration needs a rollback plan before the first line changes.** If you cannot describe how to undo the migration in one sentence, you are not ready to start it.
+
+## Step 1: Classify the Migration
+
+Ask the user (one question at a time):
+
+- **Type**: dependency upgrade (major version), framework switch (e.g. Express → Hono), runtime switch (Node → Bun), data store (SQLite → Postgres), API version (v1 → v2)
+- **Scope**: one module, one service, or the whole codebase?
+- **Downtime tolerance**: blue/green, zero-downtime (dual-run), acceptable window?
+- **Deadline driver**: deprecation, security, performance, or opportunistic?
+
+This framing determines whether the work is a single PR or a multi-phase plan.
+
+## Step 2: Audit the Surface
+
+Map **everything** that will be affected:
+
+- Imports / usages of the old API (use `grep -r` or `rg` across the codebase)
+- Public contracts that depend on current behavior (downstream callers, API consumers)
+- Build / deploy steps tied to the current version
+- Test suites that assume old behavior
+- Documentation mentioning the old API
+
+Write the inventory to `.agents/specs/migration-<topic>.md` with counts — "47 import sites across 12 files". Numbers help you size the work honestly.
+
+## Step 3: Read the Upgrade Notes
+
+Before writing code, read the target's official migration guide / changelog end to end. Note:
+
+- **Breaking changes** (renamed APIs, removed APIs, default-behavior flips)
+- **Deprecations** (will break in N+2, not now)
+- **Required minimum versions** for peer dependencies
+- **Data-shape changes** that require a migration script
+
+If the target project has no migration guide, treat it as higher risk and budget more time for exploration.
+
+## Step 4: Choose a Strategy
+
+| Strategy | When to use |
+|---|---|
+| **Big bang** | Small codebase, low downstream coupling, clean cut possible |
+| **Incremental with adapter** | Many call sites — introduce a thin wrapper that presents the old API on top of the new, migrate call sites one by one |
+| **Dual-run (strangler fig)** | High-risk or zero-downtime — run both old and new side by side, shift traffic gradually |
+| **Branch by abstraction** | Internal refactor + external API stays stable — hide the switch behind an interface |
+
+Pick one and document the trade-off in the spec file.
+
+## Step 5: Plan the Phases
+
+For anything non-trivial, run `/hopla:plan-feature` with `migration-<topic>` as the feature name. The plan should specify:
+
+- **Phase boundaries** (compatibility shim in, call sites migrated, shim removed)
+- **Rollback plan per phase** (revert commit? feature flag? dual-write?)
+- **Validation at each phase** (test suite green, feature flags covered, canary metrics)
+- **Data migration script** (if the storage layer changes) — idempotent, resumable
+
+Each phase should land as its own PR.
+
+## Step 6: Migrate With Guardrails
+
+Execute phase by phase. After every phase:
+
+- Run the full validation pyramid (`commands/guides/validation-pyramid.md`)
+- Check for mixed-version pitfalls — modules importing both the old and new API in the same request
+- Confirm the rollback path still works (git revert + redeploy, or feature flag off)
+
+Never advance to the next phase if validation failed on the previous one.
+
+## Step 7: Remove the Old Path
+
+Once every call site is migrated and observed green in production (where applicable):
+
+- Delete the compatibility shim
+- Remove the old dependency (`npm uninstall`, etc.)
+- Remove the feature flag
+- Update documentation to reference only the new path
+
+This "cleanup" step is part of the migration. A migration left half-done with a permanent shim is worse than no migration.
+
+## Rules
+
+- Never migrate on a Friday or before a public release
+- Keep the rollback plan alive at every phase — if it stops working, pause
+- Track breaking changes from the target's changelog in the spec, not in memory
+- Data migrations must be idempotent and resumable — migrations fail mid-run
+- If the migration drags past its original estimate by 2x, stop and reassess scope
+
+## Integration
+
+- Use `/hopla:plan-feature` to generate the phased plan from the Step 2 inventory
+- Use the `worktree` skill to keep the migration isolated from other work
+- The `code-review` skill (checklist sections 2 and 5) catches dual-import patterns and pattern drift
+- The `performance` skill verifies the migration did not regress hot paths
+
+## Next Step
+
+Once the migration is planned:
+
+> "Migration classified and inventoried. Saved spec to `.agents/specs/migration-<topic>.md`. Run `/hopla:plan-feature` to generate the phased implementation plan."

package/skills/performance/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: performance
+description: "Measured performance optimization workflow. Use when the user says 'slow', 'optimize', 'performance', 'bottleneck', 'too slow', 'high memory', 'high CPU', 'lento', 'tarda mucho', or when asking to make something faster. Do NOT use for correctness bugs or new features — use the debug or plan-feature skills instead."
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+# Performance: Measure Before You Change
+
+## Iron Rule
+
+**No optimization without a measurement.** Every performance change must start with a number (latency, memory, query count) and end with a comparison. Guessing at hot paths wastes time and often makes things slower.
+
+## Step 1: Clarify the Symptom
+
+Ask the user (one question at a time):
+
+- What operation feels slow? (page load, API request, build, test run, specific query)
+- How slow is it? (exact number if possible — "3 seconds", "30 MB", "10s with 100 items")
+- What is "fast enough"? (target: < 500 ms p95, < 100 MB, etc.)
+- Is it reproducible, or only under load?
+
+Without a concrete target, you cannot declare the optimization done.
+
+## Step 2: Measure the Baseline
+
+Pick the right tool for the symptom:
+
+| Symptom | Measurement |
+|---|---|
+| Slow endpoint | `curl -w "%{time_total}"` or APM dashboard (see `guides/mcp-integration.md` for MCP options) |
+| Slow DB query | `EXPLAIN ANALYZE` (Postgres), `EXPLAIN` (SQLite/MySQL) |
+| Slow frontend render | Chrome DevTools Performance tab, React Profiler |
+| Memory growth | `process.memoryUsage()` snapshots, heap dumps |
+| Slow build/test | Time the command, compare against a clean cache |
+
+Record the baseline with units. "3.2 s to load /dashboard with 1000 items" — not "it feels slow".
+
+## Step 3: Identify the Hot Path
+
+Rank suspects by where the baseline measurement actually spends its time:
+
+- **N+1 queries** — are there loops calling the DB or an API?
+- **Missing indexes** — does `EXPLAIN ANALYZE` show a seq scan on a large table?
+- **Synchronous I/O** — is there a blocking call that could be awaited in parallel (`Promise.all`)?
+- **Rendering** — are components re-rendering with unchanged props? Are lists virtualized?
+- **Algorithm** — is there an O(n²) that could be O(n) with a map?
+- **Caching** — is the same computation repeated without memoization?
+
+Do **not** guess. Use the profiler output or query plan to pick one suspect.
+
+## Step 4: Apply One Change
+
+Change one thing. Not three.
+
+- Add the index
+- Replace the loop with `Promise.all`
+- Memoize the expensive selector
+- Batch the API calls
+- Virtualize the list
+
+Keep the diff minimal so you can attribute the delta to this change alone.
+
+## Step 5: Measure Again
+
+Re-run the exact same measurement from Step 2 under the same conditions. Report:
+
+- Baseline: X
+- After change: Y
+- Delta: (X − Y) / X × 100 %
+- Target: [target from Step 1]
+
+If you did not hit the target, go back to Step 3 and pick the next suspect. If you regressed, revert and rethink.
+
+## Step 6: Regression Guard
+
+Once the target is met, add a guard so future changes do not erode the win:
+
+- A test with a timeout assertion (e.g. `expect(duration).toBeLessThan(500)`)
+- A query count assertion (e.g. `expect(dbQueries).toHaveLength(1)`)
+- A bundle size budget, memory budget, or frame budget if applicable
+
+Without a guard, the win decays.
+
+## Rules
+
+- One suspect at a time — never stack optimizations before measuring
+- Keep the baseline in the commit message so the win is auditable
+- If the fix adds significant complexity for a small win (< 10 %), consider reverting
+- Do not optimize code that is not actually hot — premature optimization hurts readability
+
+## Integration
+
+- Use the `code-review` skill checklist section 3 (Performance Problems) for patterns to watch for
+- If the optimization requires architectural changes, stop and run `/hopla:plan-feature`
+- After the change lands, the `verify` skill will require the regression guard to run fresh
+
+## Next Step
+
+After the target is met and a regression guard is in place:
+
+> "Target hit: [baseline → result]. Regression guard added. Say 'commit' to trigger the `git` skill with a `perf:` conventional commit."

package/skills/refactoring/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: refactoring
+description: "Safe refactoring workflow with behavior preservation. Use when the user says 'refactor', 'clean up', 'simplify', 'extract', 'restructure', 'deduplicate', 'rename', or when asking to improve code structure without changing behavior. Do NOT use for bug fixes, new features, or performance work — use the debug, plan-feature, or performance skills instead."
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+# Refactoring: Restructure Without Changing Behavior
+
+## Iron Rule
+
+**Behavior must be identical before and after.** If a refactor changes observable behavior — output, side effects, error shape, API surface — it is not a refactor. Stop and reclassify the work as a feature change or a bug fix.
+
+## Step 1: Confirm the Refactor Is Worth Doing
+
+Ask the user (one question at a time):
+
+- What is the current pain? (duplication, unclear naming, deep nesting, coupled modules)
+- What is the desired structure? (extract helper, collapse abstraction, rename, move, inline)
+- Is there a test suite, and does it cover the code being refactored?
+
+If the answers reveal a missing test covering the target, **write the test first** (pin current behavior), then refactor. Untested refactors are rewrites.
+
+## Step 2: Capture the Baseline
+
+Run the project's validation commands from `CLAUDE.md` (or use `/hopla:validate`). Record:
+
+- Lint / format — current state
+- Types — current state
+- Unit tests — pass/fail count
+- Relevant integration tests — pass/fail
+
+Every level must be green before starting. A refactor on top of red tests cannot prove it preserved behavior.
+
+## Step 3: Apply the Smallest Safe Change
+
+Pick one refactor at a time:
+
+- Extract function / module
+- Rename (symbol, file)
+- Inline (remove pointless indirection)
+- Move (relocate to a better home)
+- Deduplicate (merge two near-identical pieces)
+- Replace conditional with polymorphism / table lookup
+- Flatten / collapse nesting
+
+**Do not** mix refactors. If the change wants to become a redesign, stop and suggest `/hopla:plan-feature`.
+
+## Step 4: Re-run the Baseline
+
+After each refactor, re-run the same validation set from Step 2. Results must match exactly:
+
+- Same lint result (0 new warnings unless whitelisted)
+- Same type result
+- Same pass/fail count on tests
+- Same integration result
+
+If anything diverges, the refactor leaked behavior — revert or fix before continuing.
+
+## Step 5: Commit at a Clean Boundary
+
+When the baseline is restored and the refactor is coherent, suggest a commit via the `git` skill:
+
+> "Refactor complete — behavior preserved. Say 'commit' to save it with a `refactor:` conventional commit."
+
+## Rules
+
+- One refactor per commit — easier to review, easier to revert
+- Never combine refactor + feature in the same commit
+- Prefer many small refactors over one large one
+- If the test suite is missing, add tests FIRST, then refactor (two commits minimum)
+- Preserve public API unless the user explicitly approves a breaking change
+
+## Integration
+
+- Pair with the `tdd` skill when adding characterization tests before a refactor
+- Use the `code-review` skill after the refactor to confirm no pattern violations were introduced
+- If the refactor touches many files, consider the `worktree` skill for isolation
+
+## Next Step
+
+After the refactor passes validation:
+
+> "Refactor complete and validated. Say 'commit' to trigger the `git` skill with a `refactor:` conventional commit."

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.