@hopla/claude-setup 1.14.1 → 1.16.0

package/hooks/precompact-snapshot.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// PreCompact hook: snapshot the session's work state so it survives /compact.
+// The SessionStart hook (session-prime.js) re-injects this when it exists and is recent.
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+function run(cmd) {
+    try {
+        return execSync(cmd, { cwd: process.cwd(), stdio: "pipe" }).toString().trim();
+    } catch {
+        return null;
+    }
+}
+
+function findActivePlan() {
+    const plansDir = path.join(process.cwd(), ".agents", "plans");
+    if (!fs.existsSync(plansDir)) return null;
+    try {
+        const files = fs
+            .readdirSync(plansDir)
+            .filter((f) => f.endsWith(".md") && !f.startsWith("."))
+            .map((f) => ({ name: f, mtime: fs.statSync(path.join(plansDir, f)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime);
+        return files[0]?.name || null;
+    } catch {
+        return null;
+    }
+}
+
+function detectWorktree() {
+    const gitDir = run("git rev-parse --git-dir");
+    const commonDir = run("git rev-parse --git-common-dir");
+    if (!gitDir || !commonDir) return false;
+    return path.resolve(gitDir) !== path.resolve(commonDir);
+}
+
+async function main() {
+    // Drain stdin (hook contract)
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+
+    const snapshot = {
+        timestamp: new Date().toISOString(),
+        branch: run("git branch --show-current"),
+        uncommitted: run("git status --short"),
+        activePlan: findActivePlan(),
+        inWorktree: detectWorktree(),
+    };
+
+    const targetDir = path.join(process.cwd(), ".claude");
+    try {
+        fs.mkdirSync(targetDir, { recursive: true });
+        fs.writeFileSync(
+            path.join(targetDir, "compact-snapshot.json"),
+            JSON.stringify(snapshot, null, 2) + "\n"
+        );
+    } catch {
+        // Best-effort — never block /compact
+    }
+    process.exit(0);
+}
+
+main();

package/hooks/prompt-route.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook: scan the user's prompt for skill keywords and inject
+// a short routing hint. Keeps skill suggestions visible mid-session even after
+// compaction or long conversations where the initial skill list gets buried.
+
+const SKILL_TRIGGERS = [
+    {
+        skill: "git",
+        patterns: [
+            /\bcommit\b/i,
+            /save (my |the )?changes/i,
+            /\bcreate (a )?pr\b/i,
+            /pull request/i,
+            /\bpush\b/i,
+            /merge request/i,
+        ],
+    },
+    {
+        skill: "worktree",
+        patterns: [
+            /\bworktree\b/i,
+            /isolated branch/i,
+            /parallel (feature|development)/i,
+        ],
+    },
+    {
+        skill: "prime",
+        patterns: [
+            /\borient(\b| yourself)/i,
+            /catch me up/i,
+            /get context/i,
+            /load project/i,
+            /what is this project/i,
+        ],
+    },
+    {
+        skill: "brainstorm",
+        patterns: [
+            /\bbrainstorm\b/i,
+            /explore (options|approaches)/i,
+            /how should we/i,
+            /trade[- ]offs?/i,
+        ],
+    },
+    {
+        skill: "debug",
+        patterns: [
+            /\bbug\b/i,
+            /\berror\b/i,
+            /\bdebug\b/i,
+            /not working/i,
+            /\bfailing\b/i,
+            /\bbroken\b/i,
+            /\bno funciona\b/i,
+        ],
+    },
+    {
+        skill: "verify",
+        patterns: [
+            /\bverify\b/i,
+            /all tests? pass/i,
+            /\blisto\b/i,
+            /\bterminé\b/i,
+            /\bya está\b/i,
+        ],
+    },
+    {
+        skill: "code-review",
+        patterns: [
+            /review (the |my )?code/i,
+            /code review/i,
+            /audit (the |my )?code/i,
+        ],
+    },
+    {
+        skill: "execution-report",
+        patterns: [
+            /generate (the |a )?report/i,
+            /document what was done/i,
+            /execution report/i,
+        ],
+    },
+    {
+        skill: "tdd",
+        patterns: [
+            /\btdd\b/i,
+            /test[- ]first/i,
+            /red[- ]green[- ]refactor/i,
+        ],
+    },
+];
+
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+
+    let input;
+    try {
+        input = JSON.parse(Buffer.concat(chunks).toString());
+    } catch {
+        // Malformed payload — skip silently so we never block legitimate prompts
+        process.exit(0);
+    }
+
+    // Cap prompt length so regex matching stays cheap on large paste-ins
+    const prompt = (input.prompt || "").slice(0, 4000);
+    if (!prompt) process.exit(0);
+
+    const matched = [];
+    for (const { skill, patterns } of SKILL_TRIGGERS) {
+        if (patterns.some((p) => p.test(prompt))) matched.push(skill);
+    }
+
+    if (matched.length === 0) process.exit(0);
+
+    const list = matched.map((s) => `\`${s}\``).join(", ");
+    const plural = matched.length > 1;
+    process.stdout.write(
+        `📦 HOPLA routing hint: this prompt matches skill${plural ? "s" : ""} ${list}. ` +
+        `Use ${plural ? "them" : "it"} if applicable to the current task.`
+    );
+    process.exit(0);
+}
+
+main();

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;
@@ -65,11 +77,31 @@ async function main() {
         lines.push("Working tree is clean.");
     }
 
-    // CLAUDE.md summary (first 20 lines)
+    // Re-inject pre-compact snapshot if recent (< 2 hours old)
+    const snapshotPath = path.join(process.cwd(), ".claude", "compact-snapshot.json");
+    if (fs.existsSync(snapshotPath)) {
+        try {
+            const snap = JSON.parse(fs.readFileSync(snapshotPath, "utf8"));
+            const ageMs = Date.now() - Date.parse(snap.timestamp);
+            if (Number.isFinite(ageMs) && ageMs < 2 * 60 * 60 * 1000) {
+                const parts = [
+                    `Resuming from pre-compact snapshot (${Math.round(ageMs / 60000)} min ago):`,
+                ];
+                if (snap.branch) parts.push(`- branch: ${snap.branch}${snap.inWorktree ? " (worktree)" : ""}`);
+                if (snap.activePlan) parts.push(`- active plan: .agents/plans/${snap.activePlan}`);
+                if (snap.uncommitted) parts.push(`- uncommitted at snapshot:\n${snap.uncommitted}`);
+                lines.push(parts.join("\n"));
+            }
+        } catch {
+            // Ignore malformed snapshot
+        }
+    }
+
+    // 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/hooks/statusline.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Hopla statusline: branch · worktree indicator · uncommitted count · active plan.
+// Wire it up by adding to ~/.claude/settings.json:
+//   "statusLine": {
+//     "type": "command",
+//     "command": "node ~/.claude/plugins/marketplaces/hopla-marketplace/hooks/statusline.js"
+//   }
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+const CYAN = "\x1b[36m";
+const YELLOW = "\x1b[33m";
+const MAGENTA = "\x1b[35m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+function run(cmd, cwd) {
+    try {
+        return execSync(cmd, { cwd, stdio: "pipe" }).toString().trim();
+    } catch {
+        return null;
+    }
+}
+
+function findActivePlan(cwd) {
+    const plansDir = path.join(cwd, ".agents", "plans");
+    if (!fs.existsSync(plansDir)) return null;
+    try {
+        const files = fs
+            .readdirSync(plansDir)
+            .filter((f) => f.endsWith(".md") && !f.startsWith("."))
+            .map((f) => ({ name: f, mtime: fs.statSync(path.join(plansDir, f)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime);
+        return files[0]?.name.replace(/\.md$/, "") || null;
+    } catch {
+        return null;
+    }
+}
+
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+
+    let input = {};
+    try {
+        input = JSON.parse(Buffer.concat(chunks).toString());
+    } catch {
+        // Malformed payload — render nothing
+        process.exit(0);
+    }
+
+    const cwd = input.workspace?.current_dir || input.cwd || process.cwd();
+    const parts = [];
+
+    const branch = run("git branch --show-current", cwd);
+    if (branch) {
+        const gitDir = run("git rev-parse --git-dir", cwd);
+        const commonDir = run("git rev-parse --git-common-dir", cwd);
+        const isWorktree =
+            gitDir && commonDir && path.resolve(cwd, gitDir) !== path.resolve(cwd, commonDir);
+        parts.push(`${CYAN}${isWorktree ? "⎇ " : " "}${branch}${RESET}`);
+    }
+
+    const status = run("git status --short", cwd);
+    if (status) {
+        const count = status.split("\n").length;
+        parts.push(`${YELLOW}${count}M${RESET}`);
+    }
+
+    const plan = findActivePlan(cwd);
+    if (plan) {
+        parts.push(`${MAGENTA}📋 ${plan}${RESET}`);
+    }
+
+    if (parts.length === 0) process.exit(0);
+
+    process.stdout.write(parts.join(` ${DIM}·${RESET} `));
+    process.exit(0);
+}
+
+main();

package/package.json

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

package/skills/code-review/SKILL.md

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

package/skills/code-review/checklist.md

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

package/skills/execution-report/SKILL.md

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