@hopla/claude-setup 1.14.1 → 1.15.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.15.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.15.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/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
+          }
+        ]
+      }
     ]
   }
 }

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

@@ -65,6 +65,26 @@ async function main() {
         lines.push("Working tree is clean.");
     }
 
+    // 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 summary (first 20 lines)
     const claudeMdPath = path.join(process.cwd(), "CLAUDE.md");
     if (fs.existsSync(claudeMdPath)) {

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.15.0",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {