feat: close all Gemini auto-activation gaps

Addresses 4 identified gaps in the Gemini CLI Superpowers integration:

1. Always-on gateway: when no specific regex matches, the router now
   injects a generic system message telling Gemini to check all skills
   before responding (replicates Claude's using-superpowers behavior).

2. All 14 skills now have triggers: added patterns for
   receiving-code-review, finishing-a-development-branch,
   verification-before-completion, and writing-skills. Broadened
   brainstorming triggers to catch natural language like 'Add a login
   page' (not just 'Let's build...').

3. New BeforeTool hook (superpowers-guard.js): intercepts agent tool
   calls like git commit/push/merge to inject verification and branch-
   finishing skills. These are agent-behavior triggers that can't be
   caught by user prompt matching alone.

4. Updated using-superpowers/SKILL.md with explicit Gemini CLI
   instructions for activate_skill tool alongside existing Claude Code
   instructions.

Author: mhenke

.gemini/install.sh

@@ -116,61 +116,71 @@ if [ -d "$REPO_AGENTS_DIR" ]; then
     echo "No agents directory found at "$REPO_AGENTS_DIR", skipping agent linking."
 fi
 
-# --- Register deterministic hook router in settings.json ---
+# --- Register deterministic hooks in settings.json ---
 SETTINGS_FILE="$GEMINI_DIR/settings.json"
 
-enable_router_hook() {
+register_hooks() {
     # Ensure settings.json exists
     if [ ! -f "$SETTINGS_FILE" ]; then
         echo "Creating basic $SETTINGS_FILE for hook registration..."
-        printf '{\n  "hooks": {\n    "beforeAgent": []\n  }\n}\n' > "$SETTINGS_FILE"
+        printf '{\n  "hooks": {}\n}\n' > "$SETTINGS_FILE"
     fi
 
-    echo "Registering superpowers-router hook in $SETTINGS_FILE..."
+    echo "Registering Superpowers hooks in $SETTINGS_FILE..."
 
-    # Path to the script
+    # Paths to the scripts
     ROUTER_PATH="$REPO_DIR/agents/superpowers-router.js"
+    GUARD_PATH="$REPO_DIR/agents/superpowers-guard.js"
 
-    # Python script to safely inject/update the hook without breaking existing ones
     if command -v python3 >/dev/null 2>&1; then
         python3 -c "
 import json, sys
 settings_path = sys.argv[1]
 router_path = sys.argv[2]
+guard_path = sys.argv[3]
 try:
     with open(settings_path, 'r') as f:
         d = json.load(f)
 except (FileNotFoundError, json.JSONDecodeError):
     d = {}
 
 hooks = d.setdefault('hooks', {})
-beforeAgent = hooks.setdefault('beforeAgent', [])
-
-# Remove existing superpower-router if it exists
-beforeAgent = [h for h in beforeAgent if h.get('name') != 'superpowers-router']
 
-# Append our router
+# BeforeAgent: deterministic phrase router
+beforeAgent = hooks.setdefault('beforeAgent', [])
+beforeAgent = [h for h in beforeAgent if h.get('name') not in ('superpowers-router',)]
 beforeAgent.append({
     'name': 'superpowers-router',
     'command': 'node',
     'args': [router_path],
     'matcher': '.*'
 })
-
 hooks['beforeAgent'] = beforeAgent
 
+# BeforeTool: agent-behavior guard (commit/merge interception)
+beforeTool = hooks.setdefault('beforeTool', [])
+beforeTool = [h for h in beforeTool if h.get('name') not in ('superpowers-guard',)]
+beforeTool.append({
+    'name': 'superpowers-guard',
+    'command': 'node',
+    'args': [guard_path],
+    'matcher': '.*'
+})
+hooks['beforeTool'] = beforeTool
+
 with open(settings_path, 'w') as f:
     json.dump(d, f, indent=2)
     f.write('\n')
-" "$SETTINGS_FILE" "$ROUTER_PATH"
-        echo "  ✓ Registered superpowers-router hook."
+" "$SETTINGS_FILE" "$ROUTER_PATH" "$GUARD_PATH"
+        echo "  ✓ Registered superpowers-router (BeforeAgent)"
+        echo "  ✓ Registered superpowers-guard (BeforeTool)"
     else
-        echo "  ⚠ python3 not found. Could not auto-register hooks. Please add manually:"
-        echo "  \"hooks\": { \"beforeAgent\": [{ \"name\": \"superpowers-router\", \"command\": \"node\", \"args\": [\"$ROUTER_PATH\"], \"matcher\": \".*\" }] }"
+        echo "  ⚠ python3 not found. Could not auto-register hooks."
+        echo "  Please add hooks manually to $SETTINGS_FILE. See docs/README.gemini.md."
     fi
 }
 
-enable_router_hook
+register_hooks
 
 # --- Context injection into GEMINI.md ---
 CONTEXT_HEADER="<!-- SUPERPOWERS-CONTEXT-START -->"

agents/superpowers-guard.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+const fs = require('fs');
+
+// BeforeTool hook: intercepts tool calls to inject Superpowers skills
+// that trigger on agent *behavior* rather than user phrases.
+//
+// Examples:
+// - Agent about to run `git commit` or `git push` → inject verification-before-completion
+// - Agent about to run `git merge` or create a PR → inject finishing-a-development-branch
+
+try {
+    const input = JSON.parse(fs.readFileSync(0, 'utf-8'));
+
+    const toolName = input.toolName || input.tool?.name || "";
+    const toolArgs = input.toolArgs || input.tool?.args || {};
+    const argsStr = JSON.stringify(toolArgs).toLowerCase();
+
+    // ─── Verification Before Completion ───────────────────────────────
+    // If the agent is about to commit, push, or claim "done", remind it
+    // to verify first.
+    const commitPatterns = [
+        /git\s+commit/i,
+        /git\s+push/i,
+    ];
+
+    const isCommitAction = commitPatterns.some(p => p.test(argsStr));
+    const isShellTool = /^(run_command|shell|bash|execute)$/i.test(toolName);
+
+    if (isShellTool && isCommitAction) {
+        console.error(`[Superpowers BeforeTool] Detected commit/push — injecting verification reminder`);
+        console.log(JSON.stringify({
+            continue: true,
+            systemMessage: `STOP. Before committing or pushing, you MUST verify your work is complete and correct. If you have not already activated the "verification-before-completion" skill, call activate_skill("verification-before-completion") NOW and follow its checklist before proceeding with this commit.`
+        }));
+        process.exit(0);
+    }
+
+    // ─── Finishing a Development Branch ───────────────────────────────
+    const mergePatterns = [
+        /git\s+merge/i,
+        /gh\s+pr\s+create/i,
+        /git\s+push.*--set-upstream/i,
+    ];
+
+    const isMergeAction = mergePatterns.some(p => p.test(argsStr));
+
+    if (isShellTool && isMergeAction) {
+        console.error(`[Superpowers BeforeTool] Detected merge/PR — injecting finishing-branch reminder`);
+        console.log(JSON.stringify({
+            continue: true,
+            systemMessage: `STOP. Before merging or creating a PR, you MUST follow the branch completion workflow. If you have not already activated the "finishing-a-development-branch" skill, call activate_skill("finishing-a-development-branch") NOW and follow its structured options before proceeding.`
+        }));
+        process.exit(0);
+    }
+
+    // No match: pass through
+    console.log(JSON.stringify({ continue: true }));
+
+} catch (error) {
+    console.error(`[Superpowers BeforeTool Error] ${error.message}`);
+    console.log(JSON.stringify({ continue: true }));
+}

agents/superpowers-router.js

@@ -5,28 +5,72 @@ try {
     // Read stdin JSON provided by Gemini CLI
     const input = JSON.parse(fs.readFileSync(0, 'utf-8'));
 
-    // Extract user prompt. Depending on exact schema, it might be in turn.userMessage.content
+    // Extract user prompt
     const userPrompt = input.turn?.userMessage?.content || input.prompt || "";
 
     if (!userPrompt) {
         console.log(JSON.stringify({ continue: true }));
         process.exit(0);
     }
 
-    // Generalized pattern marching for core Superpowers skills
+    // ─── Deterministic Triggers ───────────────────────────────────────────
+    // These patterns guarantee a specific skill is activated.
+    // Order matters: first match wins.
     const triggers = [
-        { pattern: /let\'s (build|make|create|design)/i, skill: 'brainstorming' },
+        // Brainstorming — any creative/building intent
+        { pattern: /let'?s (build|make|create|design|implement|add|write)/i, skill: 'brainstorming' },
         { pattern: /brainstorm/i, skill: 'brainstorming' },
+        { pattern: /^(build|make|create|design|implement) /i, skill: 'brainstorming' },
+        { pattern: /(new feature|add a |add an |new component|new page|new app)/i, skill: 'brainstorming' },
+
+        // Planning
         { pattern: /write.*plan/i, skill: 'writing-plans' },
         { pattern: /break.*down/i, skill: 'writing-plans' },
-        { pattern: /(debug|fix).*bug/i, skill: 'systematic-debugging' },
-        { pattern: /test.*driven/i, skill: 'test-driven-development' },
+        { pattern: /implementation plan/i, skill: 'writing-plans' },
+
+        // Debugging
+        { pattern: /(debug|fix|diagnose|troubleshoot)/i, skill: 'systematic-debugging' },
+        { pattern: /(bug|error|broken|failing|crash)/i, skill: 'systematic-debugging' },
+
+        // TDD
+        { pattern: /test.?driven/i, skill: 'test-driven-development' },
         { pattern: /\btdd\b/i, skill: 'test-driven-development' },
+        { pattern: /write.*tests? first/i, skill: 'test-driven-development' },
+
+        // Code review
         { pattern: /review.*code/i, skill: 'requesting-code-review' },
+        { pattern: /code.*review/i, skill: 'requesting-code-review' },
+        { pattern: /review.*feedback/i, skill: 'receiving-code-review' },
+        { pattern: /address.*review/i, skill: 'receiving-code-review' },
+        { pattern: /respond.*review/i, skill: 'receiving-code-review' },
+
+        // Parallel agents
         { pattern: /parallel.*agent/i, skill: 'dispatching-parallel-agents' },
+        { pattern: /dispatch.*agent/i, skill: 'dispatching-parallel-agents' },
+
+        // Git worktrees
         { pattern: /git.*worktree/i, skill: 'using-git-worktrees' },
-        { pattern: /subagent.*driven/i, skill: 'subagent-driven-development' },
-        { pattern: /execute.*plan/i, skill: 'executing-plans' }
+        { pattern: /worktree/i, skill: 'using-git-worktrees' },
+
+        // Subagent-driven development
+        { pattern: /subagent/i, skill: 'subagent-driven-development' },
+
+        // Executing plans
+        { pattern: /execute.*plan/i, skill: 'executing-plans' },
+        { pattern: /run.*plan/i, skill: 'executing-plans' },
+
+        // Finishing branches
+        { pattern: /(merge|finish|wrap up).*branch/i, skill: 'finishing-a-development-branch' },
+        { pattern: /create.*pr\b/i, skill: 'finishing-a-development-branch' },
+        { pattern: /pull request/i, skill: 'finishing-a-development-branch' },
+
+        // Verification
+        { pattern: /verify.*complete/i, skill: 'verification-before-completion' },
+        { pattern: /check.*work/i, skill: 'verification-before-completion' },
+
+        // Writing skills (meta)
+        { pattern: /write.*skill/i, skill: 'writing-skills' },
+        { pattern: /create.*skill/i, skill: 'writing-skills' },
     ];
 
     let matchedSkill = null;
@@ -38,8 +82,8 @@ try {
     }
 
     if (matchedSkill) {
-        // Deterministic: Force activation via injected system message
-        console.error(`[Superpowers Router] Matched pattern for skill "${matchedSkill}"`);
+        // ─── Deterministic Match ──────────────────────────────────────────
+        console.error(`[Superpowers Router] Matched skill "${matchedSkill}"`);
         console.log(JSON.stringify({
             continue: true,
             systemMessage: `User request matches the "${matchedSkill}" superpower. You MUST activate it now. Call the activate_skill tool with name="${matchedSkill}". Follow its workflow exactly. Do not proceed until you have activated this skill.`,
@@ -48,11 +92,16 @@ try {
         process.exit(0);
     }
 
-    // No match: pass through normally
-    console.log(JSON.stringify({ continue: true }));
+    // ─── Always-On Gateway (no match fallback) ──────────────────────────
+    // This replicates the "using-superpowers" behavior from Claude Code:
+    // every prompt gets a reminder to check skills before responding.
+    console.error(`[Superpowers Router] No direct match — injecting gateway reminder`);
+    console.log(JSON.stringify({
+        continue: true,
+        systemMessage: `You have Superpowers skills installed. Before responding, check if any installed skill applies to this task. Run /skills list mentally and if ANY skill is even 1% relevant, you MUST call the activate_skill tool with that skill's name before proceeding. Prioritize: brainstorming (for new features/apps/components), systematic-debugging (for bugs/errors), test-driven-development (for implementation), writing-plans (for multi-step work). If no skill applies, proceed normally.`
+    }));
 
 } catch (error) {
-    // On any error, log to stderr and allow the CLI to continue normally
     console.error(`[Superpowers Router Error] ${error.message}`);
     console.log(JSON.stringify({ continue: true }));
 }

skills/using-superpowers/SKILL.md

@@ -15,6 +15,8 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou
 
 **In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
 
+**In Gemini CLI:** Use the `activate_skill` tool with the skill name. When activated, the skill's SKILL.md and directory are loaded into your context. Use `/skills list` to see available skills.
+
 **In other environments:** Check your platform's documentation for how skills are loaded.
 
 # Using Skills
@@ -30,7 +32,7 @@ digraph skill_flow {
     "Already brainstormed?" [shape=diamond];
     "Invoke brainstorming skill" [shape=box];
     "Might any skill apply?" [shape=diamond];
-    "Invoke Skill tool" [shape=box];
+    "Invoke activate_skill tool" [shape=box];
     "Announce: 'Using [skill] to [purpose]'" [shape=box];
     "Has checklist?" [shape=diamond];
     "Create TodoWrite todo per item" [shape=box];
@@ -43,9 +45,9 @@ digraph skill_flow {
     "Invoke brainstorming skill" -> "Might any skill apply?";
 
     "User message received" -> "Might any skill apply?";
-    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Invoke activate_skill tool" [label="yes, even 1%"];
     "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
-    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+    "Invoke activate_skill tool" -> "Announce: 'Using [skill] to [purpose]'";
     "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
     "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
     "Has checklist?" -> "Follow skill exactly" [label="no"];