@hopla/claude-setup 1.14.1 → 1.16.0

package/.claude-plugin/.mcp.json.example

@@ -0,0 +1,41 @@
+{
+  "_comment": "Copy this file to your project root as .mcp.json and uncomment the servers you want Claude Code to use. Each server is standalone — enable only what you need. Set the required env vars in your shell or .envrc (NOT committed). Restart Claude Code after editing.",
+
+  "mcpServers": {
+    "_playwright_example": {
+      "_note": "Browser automation for E2E testing and UI inspection. No credentials needed.",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp"]
+    },
+
+    "_github_example": {
+      "_note": "GitHub API access for reading repos, issues, PRs. Requires a token with the scopes you need.",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    },
+
+    "_linear_example": {
+      "_note": "Linear workspace access (issues, projects, cycles). Get an API key at linear.app/settings/api.",
+      "command": "npx",
+      "args": ["-y", "@tacticlaunch/mcp-linear"],
+      "env": {
+        "LINEAR_API_KEY": "${LINEAR_API_KEY}"
+      }
+    },
+
+    "_postgres_example": {
+      "_note": "Read-only Postgres access for database introspection and ad-hoc queries.",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
+    },
+
+    "_filesystem_example": {
+      "_note": "Constrained filesystem access outside the current workspace (e.g. to inspect ~/Documents/specs).",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ABSOLUTE/PATH/TO/ALLOWED/DIR"]
+    }
+  }
+}

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.14.1",
+      "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.14.1",
+  "version": "1.16.0",
   "author": {
     "name": "Hopla Tools",
     "email": "julio@hopla.tools"

package/README.md

@@ -101,10 +101,32 @@ Removes `~/.claude/CLAUDE.md` plus legacy `hopla-*` files from older installs.
 | `claude-setup --force` | Install without prompts |
 | `claude-setup --migrate` | Remove legacy CLI-installed duplicates only |
 | `claude-setup --uninstall` | Remove global rules + legacy files |
+| `claude-setup --dry-run` | Preview changes without touching disk (composes with other flags) |
 | `claude-setup --version` | Print package version |
 
 ---
 
+## Optional: Hopla statusline
+
+The plugin ships a statusline script that shows your branch, worktree indicator, uncommitted count, and active plan file (`📋 plan-name`) in Claude Code's status bar.
+
+Enable it by adding to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/plugins/marketplaces/hopla-marketplace/hooks/statusline.js"
+  }
+}
+```
+
+Then run `/reload-plugins` or restart Claude Code.
+
+Sample output: ` feature/auth · 3M · 📋 add-authentication`
+
+---
+
 ## Naming Convention
 
 Skills and commands use short names in source (e.g., `prime`, `execute`, `git`). The plugin namespaces them automatically:

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/global-rules.md

@@ -85,11 +85,21 @@ When suggesting a commit, explain in plain language why it's a good moment, adap
 ---
 
 ## 🔌 MCP Servers
-<!-- List your configured MCP servers here so the agent knows what tools are available -->
-<!-- Example: -->
-<!-- - Playwright: Browser automation for E2E testing -->
-<!-- - Supabase: Database management -->
-<!-- When planning features, explicitly include MCP integration points in the plan -->
+
+Declare MCP servers in your project's `.mcp.json` so Claude Code picks them up automatically. Copy the starter template from the plugin:
+
+```bash
+# Inside your project root
+cp ~/.claude/plugins/marketplaces/hopla-marketplace/.claude-plugin/.mcp.json.example .mcp.json
+# Then edit — uncomment the servers you need, set env vars in your shell
+```
+
+List the servers you actually enabled here so the agent knows what tools are available, e.g.:
+- Playwright — browser automation for E2E testing and UI inspection
+- GitHub — PR/issue access (read and write depending on token scope)
+- Linear — workspace tickets, cycles, projects
+
+When planning features, explicitly include MCP integration points in the plan.
 
 ---
 

package/hooks/hooks.json

@@ -35,6 +35,28 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/prompt-route.js\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/precompact-snapshot.js\"",
+            "async": false
+          }
+        ]
+      }
     ]
   }
 }