ai-qakit 1.0.0

package/templates/.claude/settings.json

@@ -0,0 +1,54 @@
+{
+  "env": {
+    "AI_DEVKIT_VERSION": "1.8.0"
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/statusline.cjs",
+    "padding": 0
+  },
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "repomix-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "repomix",
+        "--mcp"
+      ]
+    },
+    "morphllm": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "morphllm-mcp"
+      ],
+      "env": {
+        "MORPH_API_KEY": "${MORPH_API_KEY}"
+      }
+    },
+    "filesystem-morph": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@anthropics/mcp-server-filesystem-morph"
+      ],
+      "env": {
+        "MORPHLLM_API_KEY": "${MORPHLLM_API_KEY}"
+      }
+    }
+  }
+}

package/templates/.claude/settings.local.README.md

@@ -0,0 +1,650 @@
+# Settings Configuration Guide
+
+This document explains the configuration options in `settings.local.json` and provides guidance for creating and managing hooks.
+
+---
+
+## Table of Contents
+
+- [Configuration Reference](#configuration-reference)
+  - [permissions](#permissions)
+  - [hooks.UserPromptSubmit](#hooksuserpromptsub mit)
+  - [hooks.PreToolUse](#hookspretooluse)
+  - [alwaysThinkingEnabled](#alwaysthinkingEnabled)
+- [Hook Development Guide](#hook-development-guide)
+  - [Hook Types](#hook-types)
+  - [Hook Structure](#hook-structure)
+  - [Best Practices](#best-practices)
+- [Adding New Hooks](#adding-new-hooks)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Configuration Reference
+
+### permissions
+
+**Purpose**: Control which tools and commands Claude can execute without user approval.
+
+**Current Configuration**:
+```json
+"permissions": {
+  "deny": [
+    "Bash(git add:*)",
+    "Bash(git commit:*)",
+    "Bash(git push:*)"
+  ]
+}
+```
+
+**What it does**:
+- Blocks automatic git staging (`git add`)
+- Blocks automatic commits (`git commit`)
+- Blocks automatic pushes (`git push`)
+- Ensures user maintains control over version control operations
+
+**Why**: Prevents accidental commits or pushes of incomplete/incorrect changes. Users should explicitly approve all git operations.
+
+---
+
+### hooks.UserPromptSubmit
+
+**Purpose**: Executes before Claude processes user input. Useful for reminders, validations, and context injection.
+
+**Trigger**: Runs immediately after user submits a prompt but before Claude begins processing.
+
+**Current Hooks**:
+
+#### executable_force-agent-skills-eval.sh
+- **Purpose**: Enforces the delegation-first architecture with mandatory delegation sequence
+- **What it does**:
+  - Displays execution priority: Specialized sub-agent → Skill → general-purpose/manual
+  - Enforces 4-step delegation sequence:
+    1. **Evaluate Agents**: Scan available subagent_types and match to task
+    2. **Evaluate Skills**: Only if no agent fits, scan available skills
+    3. **Activate**: Launch matched agent/skill immediately
+    4. **Implement**: Only after activation step is complete
+  - Enforces independence rule (each task must be self-contained)
+  - Limits concurrent agents to 3 parallel max (batch into waves if more)
+  - Emphasizes orchestration over manual implementation
+  - Ensures sub-agent skill inheritance (instructs sub-agents to check available_skills)
+- **When it runs**: On every user prompt
+- **Non-blocking**: Yes - provides guidance but doesn't prevent execution
+
+#### dev-rules-reminder.cjs
+- **Purpose**: Injects development rules, catalog generation commands, and modularization reminders
+- **What it does**:
+  - Links to development rules workflow file (if exists at `.claude/workflows/development-rules.md`)
+  - Enforces markdown file organization (plans/ and docs/ directories only)
+  - Provides catalog generation commands via `generate_catalogs.py`:
+    - `--skills` flag to generate and analyze skills catalog
+    - `--commands` flag to generate and analyze commands catalog
+  - Enforces YAGNI, KISS, DRY principles
+  - Injects modularization guidelines:
+    - Check existing modules before creating new
+    - Analyze logical separation boundaries
+    - Use kebab-case naming with descriptive names (self-documenting for LLM tools)
+    - Write descriptive code comments
+    - Exceptions: markdown, plain text, bash scripts, config files
+  - Skips injection if recently reminded (checks last 150 lines of transcript)
+  - Emphasizes token consumption efficiency
+- **When it runs**: On every user prompt (debounced)
+- **Non-blocking**: Yes - provides guidance only
+
+**Use Cases**:
+- Reminders and checklists before processing requests
+- Validation checks (e.g., "Did you run tests?")
+- Context injection for specific patterns (e.g., commits, deployments)
+- Workflow enforcement
+
+**Example Configuration**:
+```json
+"UserPromptSubmit": [
+  {
+    "hooks": [
+      {
+        "type": "command",
+        "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/your-hook.sh"
+      }
+    ]
+  }
+]
+```
+
+---
+
+### hooks.PreToolUse
+
+**Purpose**: Executes before a tool is used. Ideal for blocking dangerous operations, validating inputs, or preventing access to sensitive areas.
+
+**Trigger**: Runs immediately before a tool execution begins. Can block the tool from running.
+
+**Current Hooks**:
+
+#### scout-block.cjs
+- **Purpose**: Blocks access to directories listed in `.scoutignore`
+- **What it does**:
+  - Reads patterns from `.claude/.scoutignore` file
+  - Blocks file access to ignored directories (node_modules, __pycache__, .git, dist, build by default)
+  - Blocks Bash commands that access ignored directories (cd, ls, cat, etc.)
+  - **Allows** build commands (npm build, pnpm build, yarn build, npm run build)
+  - Cross-platform support:
+    - Windows (win32): Uses PowerShell via `scout-block/scout-block.ps1`
+    - Unix (Linux/macOS): Uses Bash via `scout-block/scout-block.sh`
+    - WSL: Automatically detects and uses bash implementation
+  - Validates JSON structure of hook input before processing
+- **Matcher**: `Bash|Glob|Grep|Read|Edit|Write` - runs before file and bash operations
+- **Blocking**: Yes - prevents tool execution when accessing blocked paths (exit code 2)
+- **Configuration**: Edit `.claude/.scoutignore` to customize blocked patterns (one per line, # for comments)
+
+**Blocking Rules**:
+- File paths: Blocks any `file_path`/`path`/`pattern` containing blocked directories
+- Bash commands: Blocks directory access but ALLOWS build commands
+  - Blocked: `cd node_modules`, `ls build/`, `cat dist/file.js`
+  - Allowed: `npm build`, `pnpm build`, `yarn build`, `npm run build`
+
+**Example Configuration**:
+```json
+"PreToolUse": [
+  {
+    "matcher": "Bash|Glob|Grep|Read|Edit|Write",
+    "hooks": [
+      {
+        "type": "command",
+        "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scout-block.cjs"
+      }
+    ]
+  }
+]
+```
+
+**Matcher Patterns**:
+- `"Bash|Glob|Grep|Read|Edit|Write"` - Matches multiple tools with OR
+- `"Task"` - Matches Task tool (sub-agent invocations)
+- `"*commit*"` - Wildcard matching for partial strings
+- No matcher = runs on all tool uses
+
+---
+
+### alwaysThinkingEnabled
+
+**Purpose**: Forces extended thinking for complex tasks, improving output quality.
+
+**Default**: `true`
+
+**What it does**:
+- Enables Claude to use extended thinking mode for all requests
+- Provides more thorough analysis and planning
+- Increases response time but improves accuracy
+
+**When to disable**:
+- Simple, repetitive tasks
+- When speed is prioritized over depth
+- Resource-constrained environments
+
+**Configuration**:
+```json
+{
+  "alwaysThinkingEnabled": true
+}
+```
+
+---
+
+## Hook Development Guide
+
+### Hook Types
+
+Claude Code supports two types of hooks:
+
+1. **Command Hooks**: Execute shell commands or scripts
+   ```json
+   {
+     "type": "command",
+     "command": "bash script.sh"
+   }
+   ```
+
+2. **Inline Hooks**: Execute inline code (JavaScript/Node.js)
+   ```json
+   {
+     "type": "inline",
+     "code": "console.log('Hello from hook');"
+   }
+   ```
+
+### Hook Structure
+
+#### Input (stdin)
+Hooks receive JSON payload via stdin containing:
+```json
+{
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "/path/to/file.ts",
+    "content": "...",
+    // ... other tool-specific parameters
+  },
+  "tool_output": "...",
+  "transcript_path": "/path/to/transcript.md",
+  // ... other context
+}
+```
+
+#### Output (stdout)
+Hooks can output JSON to provide context or control flow:
+
+**Non-blocking hook** (suggestion/reminder):
+```json
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "additionalContext": "Your reminder message here"
+  }
+}
+```
+
+**Blocking hook** (prevents tool execution):
+```json
+{
+  "continue": false,
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "additionalContext": "Error: Access to node_modules is blocked"
+  }
+}
+```
+
+**Plain text output** (for UserPromptSubmit):
+Hooks can also output plain text which gets injected into the conversation context.
+
+#### Exit Codes
+- `0` - Success (non-blocking by default)
+- `2` - Error/Blocked (blocks tool execution for PreToolUse hooks)
+
+### Best Practices
+
+1. **Non-blocking by Default**
+   - Most hooks should be informational, not blocking
+   - Let Claude and the user decide whether to act on suggestions
+   - Only block for critical validations (security, access control)
+
+2. **Clear, Actionable Messages**
+   - Use emojis for visual clarity (📊, ⚠️, ✅)
+   - Provide specific, actionable recommendations
+   - Include context (file names, line counts, thresholds)
+
+3. **Performance**
+   - Keep hooks fast (<100ms when possible)
+   - Avoid expensive operations in frequently-triggered hooks
+   - Use debouncing for repeated triggers (see dev-rules-reminder.cjs)
+
+4. **Error Handling**
+   - Catch and handle errors gracefully
+   - Don't break Claude's workflow on hook failures
+   - Log errors to stderr, not stdout
+
+5. **Debugging**
+   - Support DEBUG environment variables
+   - Log to stderr (console.error) not stdout
+   - Example: `SCOUT_BLOCK_DEBUG=true`
+
+6. **Documentation**
+   - Add header comments explaining purpose and exit codes
+   - Document environment variables and configuration
+   - Include usage examples
+
+#### Example Hook Template (Bash)
+
+```bash
+#!/bin/bash
+# Hook Name - UserPromptSubmit Hook
+#
+# Description: What this hook does
+#
+# Exit Codes:
+#   0 - Success (non-blocking)
+#   1 - Error (non-blocking, logs only)
+
+# Read stdin
+INPUT=$(cat)
+
+# Parse JSON (requires jq)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
+
+# Your logic here
+cat << 'EOF'
+📋 Your reminder message here
+
+- Point 1
+- Point 2
+EOF
+
+exit 0
+```
+
+#### Example Hook Template (Node.js - CommonJS)
+
+```javascript
+#!/usr/bin/env node
+
+/**
+ * Hook Name - PreToolUse Hook
+ *
+ * Description: What this hook does
+ *
+ * Exit Codes:
+ *   0 - Success (allows tool execution)
+ *   2 - Blocked (prevents tool execution)
+ */
+
+const fs = require('fs');
+
+async function main() {
+  try {
+    // Read stdin
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    if (!stdin) process.exit(0);
+
+    const payload = JSON.parse(stdin);
+    const toolName = payload.tool_name ?? 'unknown';
+    const toolInput = payload.tool_input ?? {};
+
+    // Your logic here
+    if (shouldBlock(toolInput)) {
+      console.log(JSON.stringify({
+        continue: false,
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: "Blocked: reason here"
+        }
+      }));
+      process.exit(2);
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error(`Hook error: ${error.message}`);
+    process.exit(0); // Non-blocking even on error
+  }
+}
+
+main();
+```
+
+---
+
+## Adding New Hooks
+
+### Step 1: Create the Hook Script
+
+1. Create a new file in `.claude/hooks/`
+2. Name it descriptively (e.g., `test-coverage-check.cjs`, `lint-reminder.sh`)
+3. Make it executable: `chmod +x .claude/hooks/your-hook.sh`
+4. Add header documentation with purpose and exit codes
+5. Use `.cjs` extension for Node.js hooks (CommonJS modules)
+
+### Step 2: Update settings.local.json
+
+Add your hook to the appropriate section:
+
+**For UserPromptSubmit (context injection)**:
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/your-hook.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**For PreToolUse (validation/blocking)**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/your-hook.cjs"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**For PostToolUse (follow-up actions)**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/your-post-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Step 3: Test Your Hook
+
+1. Trigger the hook by using the matched tool or pattern
+2. Check that the output appears in Claude's context
+3. Verify blocking/non-blocking behavior works as expected
+4. Test error cases
+
+### Step 4: Document
+
+Update this README with:
+- Hook purpose and behavior
+- Configuration options
+- Usage examples
+- Known limitations
+
+---
+
+## Troubleshooting
+
+### Hook Not Triggering
+
+**Check**:
+1. Is the hook file executable? `chmod +x hook.sh`
+2. Does the matcher pattern match your use case?
+3. Is the path correct? Use `$CLAUDE_PROJECT_DIR` variable
+4. Check Claude Code logs for errors
+5. For Node.js hooks, use `.cjs` extension for CommonJS modules
+
+### Hook Blocking Unexpectedly
+
+**Solutions**:
+1. Check exit codes - `0` allows, `2` blocks (for PreToolUse)
+2. Ensure `"continue": true` in JSON output for non-blocking
+3. Review matcher patterns - they might be too broad
+
+### Hook Not Blocking When It Should
+
+**Solutions**:
+1. Ensure exit code is `2` for blocking
+2. Ensure `"continue": false` in JSON output
+3. Verify matcher pattern matches the target tool
+
+### Hook Output Not Appearing
+
+**Check**:
+1. Are you writing to stdout (not stderr)?
+2. Is JSON format valid? Test with `jq`
+3. Does output include required fields (`hookSpecificOutput`, `hookEventName`)?
+4. For plain text output, just print directly without JSON wrapper
+
+### Performance Issues
+
+**Solutions**:
+1. Profile hook execution time
+2. Add debouncing for frequently-triggered hooks (check transcript)
+3. Add caching for repeated calculations
+4. Consider moving expensive operations to async background tasks
+
+### Debug Mode
+
+Enable debug logging:
+
+**Bash**:
+```bash
+# In your hook script
+if [[ "$DEBUG" == "true" ]]; then
+  echo "[debug] Your message" >&2
+fi
+```
+
+**Node.js**:
+```javascript
+const DEBUG = process.env.HOOK_DEBUG === 'true';
+
+function debugLog(message) {
+  if (DEBUG) {
+    console.error(`[debug] ${message}`);
+  }
+}
+```
+
+**Usage**:
+```bash
+export HOOK_DEBUG=true
+export SCOUT_BLOCK_DEBUG=true
+```
+
+---
+
+## Examples
+
+### Example 1: Simple Reminder Hook (UserPromptSubmit)
+
+```bash
+#!/bin/bash
+# Simple reminder on every prompt
+
+cat << 'EOF'
+📋 Quick Reminders:
+- Run tests before committing
+- Update documentation for API changes
+- Check for security vulnerabilities
+EOF
+
+exit 0
+```
+
+### Example 2: Path Blocking Hook (PreToolUse)
+
+```javascript
+#!/usr/bin/env node
+
+const fs = require('fs');
+
+async function main() {
+  const stdin = fs.readFileSync(0, 'utf-8').trim();
+  if (!stdin) process.exit(0);
+
+  const payload = JSON.parse(stdin);
+  const filePath = payload.tool_input?.file_path || '';
+
+  // Block access to secrets
+  if (filePath.includes('.env') || filePath.includes('secrets')) {
+    console.log(JSON.stringify({
+      continue: false,
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: "🚫 Access to sensitive files is blocked"
+      }
+    }));
+    process.exit(2);
+  }
+
+  process.exit(0);
+}
+
+main();
+```
+
+### Example 3: Post-Task Reminder Hook (PostToolUse)
+
+```bash
+#!/bin/bash
+# Reminder after sub-agent task completion
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
+
+if [[ "$TOOL_NAME" == "Task" ]]; then
+  cat << 'EOF'
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "✅ Sub-agent task complete. Review the output and verify correctness."
+  }
+}
+EOF
+fi
+
+exit 0
+```
+
+### Example 4: Conditional Context Injection
+
+```javascript
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+async function main() {
+  const stdin = fs.readFileSync(0, 'utf-8').trim();
+  if (!stdin) process.exit(0);
+
+  const payload = JSON.parse(stdin);
+  const userPrompt = payload.user_prompt || '';
+
+  // Inject testing context when user mentions tests
+  if (userPrompt.toLowerCase().includes('test')) {
+    console.log(`
+## Testing Context
+- Test framework: Jest
+- Coverage threshold: 80%
+- Run tests: \`npm test\`
+- Watch mode: \`npm test -- --watch\`
+`);
+  }
+
+  process.exit(0);
+}
+
+main();
+```
+
+---
+
+## Further Reading
+
+- [Claude Code Hooks Documentation](https://docs.anthropic.com/claude-code/hooks)
+- [JSON Schema Reference](https://json-schema.org/)
+- [Shell Scripting Best Practices](https://google.github.io/styleguide/shellguide.html)
+- [Node.js CLI Best Practices](https://github.com/lirantal/nodejs-cli-apps-best-practices)