feat: implement deterministic skill router using BeforeAgent hook

Gemini CLI's natively built Agent Skills feature relies on probabilistic
semantic model matching for auto-activation. For Superpowers, we need
guaranteed deterministic routing (e.g., 'write a plan' must always map
to the writing-plans skill).

This commit:
- Creates agents/superpowers-router.js, a Node hook that intercepts
  prompts on the BeforeAgent lifecycle event, pattern-matches against
  Superpowers triggers, and injects strict deterministic overrides
  into the systemMessage.
- Updates .gemini/install.sh to auto-register this hook in the user's
  ~/.gemini/settings.json file.

Author: mhenke

.gemini/install.sh

@@ -113,9 +113,65 @@ if [ -d "$REPO_AGENTS_DIR" ]; then
             echo "  ✓ $agent_name"
         fi
     done
-else
+    echo "No agents directory found at "$REPO_AGENTS_DIR", skipping agent linking."
 fi
 
+# --- Register deterministic hook router in settings.json ---
+SETTINGS_FILE="$GEMINI_DIR/settings.json"
+
+enable_router_hook() {
+    # 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"
+    fi
+
+    echo "Registering superpowers-router hook in $SETTINGS_FILE..."
+    
+    # Path to the script
+    ROUTER_PATH="$REPO_DIR/agents/superpowers-router.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]
+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.append({
+    'name': 'superpowers-router',
+    'command': 'node',
+    'args': [router_path],
+    'matcher': '.*'
+})
+
+hooks['beforeAgent'] = beforeAgent
+
+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."
+    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\": \".*\" }] }"
+    fi
+}
+
+enable_router_hook
+
 # --- Context injection into GEMINI.md ---
 CONTEXT_HEADER="<!-- SUPERPOWERS-CONTEXT-START -->"
 CONTEXT_FOOTER="<!-- SUPERPOWERS-CONTEXT-END -->"

agents/superpowers-router.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+const fs = require('fs');
+
+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
+    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
+    const triggers = [
+        { pattern: /let\'s (build|make|create|design)/i, skill: 'brainstorming' },
+        { pattern: /brainstorm/i, skill: 'brainstorming' },
+        { 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: /\btdd\b/i, skill: 'test-driven-development' },
+        { pattern: /review.*code/i, skill: 'requesting-code-review' },
+        { pattern: /parallel.*agent/i, skill: 'dispatching-parallel-agents' },
+        { pattern: /git.*worktree/i, skill: 'using-git-worktrees' },
+        { pattern: /subagent.*driven/i, skill: 'subagent-driven-development' },
+        { pattern: /execute.*plan/i, skill: 'executing-plans' }
+    ];
+
+    let matchedSkill = null;
+    for (const trigger of triggers) {
+        if (trigger.pattern.test(userPrompt)) {
+            matchedSkill = trigger.skill;
+            break;
+        }
+    }
+
+    if (matchedSkill) {
+        // Deterministic: Force activation via injected system message
+        console.error(`[Superpowers Router] Matched pattern for 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.`,
+            suppressOutput: true
+        }));
+        process.exit(0);
+    }
+
+    // No match: pass through normally
+    console.log(JSON.stringify({ continue: true }));
+
+} 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 }));
+}