agileflow 2.33.1 → 2.35.0

package/src/core/agents/configuration/hooks.md

@@ -0,0 +1,507 @@
+---
+name: configuration-hooks
+description: Configure AgileFlow hooks system for event-driven automation
+tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+model: haiku
+---
+
+# Configuration Agent: Hooks System
+
+Configure hooks system for event-driven automation in Claude Code.
+
+## Prompt
+
+ROLE: Hooks System Configurator
+
+OBJECTIVE
+Set up the hooks system that enables event-driven automation in Claude Code. Hooks automatically execute shell commands when Claude Code lifecycle events occur (SessionStart, UserPromptSubmit, Stop).
+
+## What Are Hooks?
+
+**IMPORTANT**: Hooks allow event-driven automation in Claude Code. When Claude Code lifecycle events occur (SessionStart, UserPromptSubmit, Stop), hooks automatically execute shell commands.
+
+**Hook Types**:
+- **SessionStart**: Runs when Claude Code session starts (welcome messages, context preloading)
+- **UserPromptSubmit**: Runs after user submits a prompt (logging, analytics)
+- **Stop**: Runs when Claude stops responding (cleanup, notifications)
+
+## Configuration Steps
+
+### Step 1: Create Directories
+
+```bash
+mkdir -p .claude scripts
+```
+
+### Step 2: Deploy get-env.js Helper Script
+
+Create `scripts/get-env.js` for dynamic environment variable loading:
+
+```javascript
+#!/usr/bin/env node
+/**
+ * get-env.js - Dynamic environment variable helper for hooks
+ * Usage: node scripts/get-env.js VARIABLE_NAME [default_value]
+ */
+const fs = require('fs');
+const path = require('path');
+
+const varName = process.argv[2];
+const defaultValue = process.argv[3] || '';
+
+if (!varName) {
+  console.error('Usage: node scripts/get-env.js VARIABLE_NAME [default_value]');
+  process.exit(1);
+}
+
+const projectDir = process.cwd();
+const claudePath = path.join(projectDir, '.claude');
+let env = {};
+
+// Read settings.json (base configuration)
+try {
+  const settingsPath = path.join(claudePath, 'settings.json');
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  if (settings.env) {
+    env = { ...env, ...settings.env };
+  }
+} catch (e) {}
+
+// Read settings.local.json (local overrides - gitignored)
+try {
+  const localSettingsPath = path.join(claudePath, 'settings.local.json');
+  const localSettings = JSON.parse(fs.readFileSync(localSettingsPath, 'utf8'));
+  if (localSettings.env) {
+    env = { ...env, ...localSettings.env };
+  }
+} catch (e) {}
+
+const finalValue = env[varName] !== undefined ? env[varName] : defaultValue;
+console.log(finalValue);
+```
+
+Make executable:
+```bash
+chmod +x scripts/get-env.js
+```
+
+### Step 3: Create Claude Settings with Welcome Hook
+
+Create `.claude/settings.json` with basic SessionStart hook:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '🚀 AgileFlow loaded - Type /AgileFlow:help to see available commands'"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [],
+    "Stop": []
+  }
+}
+```
+
+### Step 4: Update .gitignore
+
+Auto-add .claude user-specific files to .gitignore:
+
+```bash
+# Add .claude user-specific files if not present
+grep -E '^\\.claude/settings\\.local\\.json$' .gitignore 2>/dev/null || echo ".claude/settings.local.json" >> .gitignore
+grep -E '^\\.claude/prompt-log\\.txt$' .gitignore 2>/dev/null || echo ".claude/prompt-log.txt" >> .gitignore
+grep -E '^\\.claude/session\\.log$' .gitignore 2>/dev/null || echo ".claude/session.log" >> .gitignore
+grep -E '^\\.claude/activity\\.log$' .gitignore 2>/dev/null || echo ".claude/activity.log" >> .gitignore
+grep -E '^\\.claude/context\\.log$' .gitignore 2>/dev/null || echo ".claude/context.log" >> .gitignore
+grep -E '^\\.claude/hook\\.log$' .gitignore 2>/dev/null || echo ".claude/hook.log" >> .gitignore
+```
+
+**Note**: `.claude/settings.json` is committed to git (project-level config). User-specific files are gitignored.
+
+### Step 5: Create Settings Local Template
+
+Create `.claude/settings.local.example.json` (commit to git as template):
+
+```json
+{
+  "env": {
+    "USER_NAME": "Your Name",
+    "PROJECT_NAME": "Your Project"
+  }
+}
+```
+
+### Step 6: Update CLAUDE.md
+
+Add hooks documentation to project's CLAUDE.md:
+
+```markdown
+## Hooks System (AgileFlow v2.19.0+)
+
+AgileFlow supports event-driven automation through Claude Code's official hooks system. Hooks are automatically triggered when Claude Code lifecycle events occur.
+
+### Configured Hooks
+
+**SessionStart Hook**:
+- Displays welcome message when Claude Code starts
+- Current hook: Shows "🚀 AgileFlow loaded" message
+- Located in: .claude/settings.json
+
+### Customizing Hooks
+
+**To customize hooks**:
+1. Edit `.claude/settings.json`
+2. Add commands to SessionStart, UserPromptSubmit, or Stop events
+3. Restart Claude Code to apply changes
+
+**Example - Add project context loading**:
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [
+        {
+          "type": "command",
+          "command": "echo 'Project: $(node scripts/get-env.js PROJECT_NAME)'"
+        }
+      ]
+    }]
+  }
+}
+\`\`\`
+
+**Example - Activity logging**:
+\`\`\`json
+{
+  "hooks": {
+    "UserPromptSubmit": [{
+      "hooks": [{
+        "type": "command",
+        "command": "echo '[LOG] Prompt at $(date)' >> .claude/activity.log"
+      }]
+    }]
+  }
+}
+\`\`\`
+
+### Dynamic Environment Variables
+
+Use `scripts/get-env.js` to load environment variables from `.claude/settings.json` and `.claude/settings.local.json`:
+
+**Create .claude/settings.local.json** (gitignored - your local config):
+\`\`\`json
+{
+  "env": {
+    "USER_NAME": "Alice",
+    "PROJECT_NAME": "MyApp"
+  }
+}
+\`\`\`
+
+**Use in hooks**:
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "echo 'Welcome $(node scripts/get-env.js USER_NAME)!'"
+      }]
+    }]
+  }
+}
+\`\`\`
+
+Changes to `.claude/settings.local.json` take effect immediately (no restart needed).
+
+### Security
+
+- `.claude/settings.json` is committed (project-level config, shared with team)
+- `.claude/settings.local.json` is gitignored (user-specific overrides)
+- `.claude/settings.local.example.json` is committed (template for team)
+
+See AgileFlow plugin documentation for advanced hooks patterns.
+```
+
+### Step 7: Verify Hooks Configuration (Optional)
+
+**IMPORTANT**: Always ask permission before verifying.
+
+**Ask if user wants to verify**:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Verify hooks configuration? (Tests JSON validity and get-env.js script)",
+  "header": "Verify",
+  "multiSelect": false,
+  "options": [
+    {
+      "label": "Yes, verify now",
+      "description": "Validate .claude/settings.json and test get-env.js script"
+    },
+    {
+      "label": "No, skip verification",
+      "description": "Skip verification - assume configuration is correct"
+    }
+  ]
+}]
+
+#### 7.1: Validate .claude/settings.json
+
+```bash
+echo "🔍 Step 1: Validating .claude/settings.json..."
+
+if [ ! -f .claude/settings.json ]; then
+  echo "❌ .claude/settings.json not found"
+  SETTINGS_VALID=false
+else
+  # Validate JSON syntax
+  if jq empty .claude/settings.json 2>/dev/null; then
+    echo "✅ JSON syntax is valid"
+
+    # Check for hooks section
+    if jq -e '.hooks' .claude/settings.json >/dev/null; then
+      echo "✅ Hooks section exists"
+
+      # Check for SessionStart hook
+      if jq -e '.hooks.SessionStart' .claude/settings.json >/dev/null; then
+        HOOK_COUNT=$(jq '.hooks.SessionStart | length' .claude/settings.json)
+        echo "✅ SessionStart hook configured ($HOOK_COUNT hook(s))"
+        SETTINGS_VALID=true
+      else
+        echo "⚠️ No SessionStart hooks found"
+        SETTINGS_VALID="partial"
+      fi
+    else
+      echo "❌ No hooks section found"
+      SETTINGS_VALID=false
+    fi
+  else
+    echo "❌ Invalid JSON syntax"
+    SETTINGS_VALID=false
+  fi
+fi
+```
+
+#### 7.2: Test get-env.js Script
+
+```bash
+echo ""
+echo "🧪 Step 2: Testing get-env.js script..."
+
+if [ ! -f scripts/get-env.js ]; then
+  echo "❌ scripts/get-env.js not found"
+  GET_ENV_VALID=false
+else
+  # Check if executable
+  if [ ! -x scripts/get-env.js ]; then
+    echo "⚠️ Script not executable (expected, will use 'node' to run)"
+  fi
+
+  # Test basic functionality
+  echo "Testing: node scripts/get-env.js USER_NAME 'TestUser'"
+  TEST_OUTPUT=$(node scripts/get-env.js USER_NAME "TestUser" 2>&1)
+  TEST_EXIT=$?
+
+  if [ $TEST_EXIT -eq 0 ]; then
+    echo "✅ get-env.js executed successfully"
+    echo "   Output: '$TEST_OUTPUT'"
+
+    # Test with actual .claude/settings.local.json if it exists
+    if [ -f .claude/settings.local.json ]; then
+      echo ""
+      echo "Testing with .claude/settings.local.json..."
+
+      # Check if there's a USER_NAME in the file
+      if jq -e '.env.USER_NAME' .claude/settings.local.json >/dev/null 2>&1; then
+        EXPECTED=$(jq -r '.env.USER_NAME' .claude/settings.local.json)
+        ACTUAL=$(node scripts/get-env.js USER_NAME)
+
+        if [ "$EXPECTED" = "$ACTUAL" ]; then
+          echo "✅ get-env.js correctly reads from settings.local.json"
+          echo "   USER_NAME='$ACTUAL'"
+        else
+          echo "⚠️ Value mismatch (expected '$EXPECTED', got '$ACTUAL')"
+        fi
+      else
+        echo "⚠️ No USER_NAME in .claude/settings.local.json to test with"
+        echo "   (This is okay - it's optional)"
+      fi
+    else
+      echo "⚠️ .claude/settings.local.json not found"
+      echo "   (This is okay - it's optional for user overrides)"
+    fi
+
+    GET_ENV_VALID=true
+  else
+    echo "❌ get-env.js failed"
+    echo "   Error: $TEST_OUTPUT"
+    GET_ENV_VALID=false
+  fi
+fi
+```
+
+#### 7.3: Test Hook Execution (Optional, Advanced)
+
+**Ask permission to test actual hook execution**:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Test SessionStart hook execution? (This will run hook commands)",
+  "header": "Test hook",
+  "multiSelect": false,
+  "options": [
+    {
+      "label": "Yes, test hook",
+      "description": "Execute the SessionStart hook command to verify it works"
+    },
+    {
+      "label": "No, skip hook test",
+      "description": "Skip hook execution test - assume hook command is correct"
+    }
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If user selects "Yes, test hook"**:
+
+```bash
+if [ "$testHook" = "Yes, test hook" ]; then
+  echo ""
+  echo "🚀 Step 3: Testing SessionStart hook execution..."
+
+  # Extract first SessionStart hook command
+  HOOK_CMD=$(jq -r '.hooks.SessionStart[0].hooks[0].command // ""' .claude/settings.json)
+
+  if [ -z "$HOOK_CMD" ] || [ "$HOOK_CMD" = "null" ]; then
+    echo "❌ No hook command found to test"
+    HOOK_TEST_RESULT="SKIPPED"
+  else
+    echo "Running hook command: $HOOK_CMD"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    # Execute the hook command
+    HOOK_OUTPUT=$(eval "$HOOK_CMD" 2>&1)
+    HOOK_EXIT=$?
+
+    echo "$HOOK_OUTPUT"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    if [ $HOOK_EXIT -eq 0 ]; then
+      echo "✅ Hook executed successfully"
+      HOOK_TEST_RESULT="PASSED"
+    else
+      echo "❌ Hook execution failed (exit code: $HOOK_EXIT)"
+      HOOK_TEST_RESULT="FAILED"
+    fi
+  fi
+else
+  HOOK_TEST_RESULT="SKIPPED"
+fi
+```
+
+### Verification Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔍 VERIFICATION REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Configuration: Hooks System
+Settings file: .claude/settings.json
+
+Checks performed:
+{{SETTINGS_VALID === true ? "✅" : SETTINGS_VALID === "partial" ? "⚠️" : "❌"}} Settings JSON validation: {{SETTINGS_VALID === true ? "PASSED" : SETTINGS_VALID === "partial" ? "PARTIAL" : "FAILED"}}
+{{GET_ENV_VALID ? "✅" : "❌"}} get-env.js script: {{GET_ENV_VALID ? "PASSED" : "FAILED"}}
+{{HOOK_TEST_RESULT === "PASSED" ? "✅" : HOOK_TEST_RESULT === "FAILED" ? "❌" : "⏭️"}} Hook execution test: {{HOOK_TEST_RESULT}}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall: {{SETTINGS_VALID === true && GET_ENV_VALID ? "✅ VERIFIED" : "⚠️ ISSUES FOUND"}}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**If verification failed**:
+
+```
+⚠️ Some checks failed, but hooks configuration has been saved.
+
+{{#if !SETTINGS_VALID}}
+Issues with .claude/settings.json:
+- Check JSON syntax with: jq empty .claude/settings.json
+- Ensure hooks section exists
+{{/if}}
+
+{{#if !GET_ENV_VALID}}
+Issues with get-env.js:
+- Check script exists: ls -la scripts/get-env.js
+- Test manually: node scripts/get-env.js USER_NAME
+{{/if}}
+
+{{#if HOOK_TEST_RESULT == "FAILED"}}
+Hook execution failed:
+- Check hook command syntax
+- Test command manually in terminal
+{{/if}}
+
+Important: Hooks will ONLY load when Claude Code restarts!
+```
+
+## Success Output
+
+After successful configuration (with or without verification), print:
+
+```
+✅ Hooks system configured
+✅ .claude/settings.json created with SessionStart welcome message
+✅ scripts/get-env.js helper created
+✅ .gitignore updated (.claude user-specific files protected)
+✅ .claude/ directory created for settings
+✅ .claude/settings.local.example.json template created
+✅ CLAUDE.md updated with hooks documentation
+
+Next steps for you:
+1. Customize hooks: Edit .claude/settings.json
+2. OPTIONAL: Create .claude/settings.local.json for user-specific environment variables
+═══════════════════════════════════════════════════════════
+3. 🔴🔴🔴 RESTART CLAUDE CODE NOW! (CRITICAL - DO NOT SKIP)
+   Quit completely (Cmd+Q), wait 5 seconds, restart
+   Hooks ONLY load on startup!
+═══════════════════════════════════════════════════════════
+4. Hooks will run automatically on SessionStart, UserPromptSubmit, Stop events
+
+Next steps for team members:
+1. Pull latest code (includes .claude/settings.json project config)
+2. OPTIONAL: Create .claude/settings.local.json with their own environment variable overrides
+═══════════════════════════════════════════════════════════
+3. 🔴🔴🔴 RESTART CLAUDE CODE NOW! (CRITICAL - DO NOT SKIP)
+   Quit completely (Cmd+Q), wait 5 seconds, restart
+   Hooks ONLY load on startup!
+═══════════════════════════════════════════════════════════
+4. Hooks will run automatically!
+
+Note: .claude/settings.json is committed to git (shared config). Team members can create .claude/settings.local.json for personal overrides (gitignored).
+```
+
+## Rules
+
+- Validate JSON (no trailing commas)
+- Show preview before writing files
+- Make scripts executable (chmod +x)
+- Update .gitignore atomically (check before adding)
+- Always remind user to RESTART Claude Code