ai-qakit 1.0.0

package/templates/.claude/hooks/scout-block/scout-block.ps1

@@ -0,0 +1,92 @@
+# scout-block.ps1 - PowerShell implementation for blocking heavy directories
+# Reads patterns from .scoutignore file (defaults: node_modules, __pycache__, .git, dist, build)
+#
+# Blocking Rules:
+# - File paths: Blocks any file_path/path/pattern containing blocked directories
+# - Bash commands: Blocks directory access (cd, ls, cat, etc.) but ALLOWS build commands
+#   - Blocked: cd node_modules, ls build/, cat dist/file.js
+#   - Allowed: npm build, pnpm build, yarn build, npm run build
+
+# Read JSON input from stdin
+$inputJson = $input | Out-String
+
+# Validate input not empty
+if ([string]::IsNullOrWhiteSpace($inputJson)) {
+    Write-Error "ERROR: Empty input"
+    exit 2
+}
+
+# Parse JSON (PowerShell 5.1+ compatible)
+try {
+    $hookData = $inputJson | ConvertFrom-Json
+} catch {
+    Write-Error "ERROR: Failed to parse JSON input"
+    exit 2
+}
+
+# Validate JSON structure
+if (-not $hookData.tool_input) {
+    Write-Error "ERROR: Invalid JSON structure - missing tool_input"
+    exit 2
+}
+
+# Extract tool input
+$toolInput = $hookData.tool_input
+
+# Determine script directory and .claude folder for .scoutignore lookup
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$claudeDir = Split-Path -Parent $scriptDir
+$scoutignoreFile = Join-Path $claudeDir ".scoutignore"
+
+# Default blocked patterns
+$blockedPatterns = @('node_modules', '__pycache__', '\.git', 'dist', 'build')
+
+# Read patterns from .scoutignore if it exists
+if (Test-Path $scoutignoreFile) {
+    $patterns = Get-Content $scoutignoreFile |
+        ForEach-Object { $_.Trim() } |
+        Where-Object { $_ -and -not $_.StartsWith('#') }
+    if ($patterns.Count -gt 0) {
+        # Escape special regex characters
+        $blockedPatterns = $patterns | ForEach-Object { [regex]::Escape($_) }
+    }
+}
+
+# Build dynamic pattern group
+$patternGroup = $blockedPatterns -join '|'
+
+# Pattern for directory paths (used for file_path, path, pattern)
+# Handles both forward slashes (/) and backslashes (\) for cross-platform support
+$blockedDirPattern = "(^|[/\\]|\s)($patternGroup)([/\\]|`$|\s)"
+
+# Pattern for Bash commands - only block directory access, not build commands
+# Blocks: cd node_modules, ls build/, cat dist/file.js
+# Allows: npm build, pnpm build, yarn build, npm run build
+$blockedBashPattern = "(cd\s+|ls\s+|cat\s+|rm\s+|cp\s+|mv\s+|find\s+)($patternGroup)([/\\]|`$|\s)|(\s|^|[/\\])($patternGroup)[/\\]"
+
+# Check file path parameters (strict blocking)
+$fileParams = @(
+    $toolInput.file_path,    # Read, Edit, Write tools
+    $toolInput.path,         # Grep, Glob tools
+    $toolInput.pattern       # Glob, Grep tools
+)
+
+foreach ($param in $fileParams) {
+    if ($param -and ($param -is [string]) -and ($param -match $blockedDirPattern)) {
+        $patternList = ($blockedPatterns -replace '\\', '') -join ', '
+        Write-Error "ERROR: Blocked directory pattern ($patternList)"
+        exit 2
+    }
+}
+
+# Check Bash command (selective blocking - only directory access)
+if ($toolInput.command -and ($toolInput.command -is [string])) {
+    if ($toolInput.command -match $blockedBashPattern) {
+        $patternList = ($blockedPatterns -replace '\\', '') -join ', '
+        Write-Error "ERROR: Blocked directory pattern ($patternList)"
+        exit 2
+    }
+}
+
+# Allow command to proceed (exit 0)
+exit 0

package/templates/.claude/hooks/scout-block/scout-block.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# scout-block.sh - Bash implementation for blocking heavy directories
+# Reads patterns from .scoutignore file (defaults: node_modules, __pycache__, .git, dist, build)
+#
+# Blocking Rules:
+# - File paths: Blocks any file_path/path/pattern containing blocked directories
+# - Bash commands: Blocks directory access (cd, ls, cat, etc.) but ALLOWS build commands
+#   - Blocked: cd node_modules, ls build/, cat dist/file.js
+#   - Allowed: npm build, pnpm build, yarn build, npm run build
+
+# Read stdin
+INPUT=$(cat)
+
+# Validate input not empty
+if [ -z "$INPUT" ]; then
+  echo "ERROR: Empty input" >&2
+  exit 2
+fi
+
+# Determine script directory for .scoutignore lookup
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Look for .scoutignore in .claude/ folder (1 level up from .claude/hooks/)
+CLAUDE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SCOUTIGNORE_FILE="$CLAUDE_DIR/.scoutignore"
+
+# Parse JSON and extract all relevant parameters using Node.js
+CHECK_RESULT=$(echo "$INPUT" | SCOUTIGNORE_FILE="$SCOUTIGNORE_FILE" node -e "
+const fs = require('fs');
+const path = require('path');
+
+try {
+  const input = fs.readFileSync(0, 'utf-8');
+  const data = JSON.parse(input);
+
+  if (!data.tool_input || typeof data.tool_input !== 'object') {
+    // If JSON structure is invalid, allow operation with warning
+    console.error('WARN: Invalid JSON structure, allowing operation');
+    console.log('ALLOWED');
+    process.exit(0);
+  }
+
+  const toolInput = data.tool_input;
+
+  // Read patterns from .scoutignore file
+  const scoutignorePath = process.env.SCOUTIGNORE_FILE;
+  let blockedPatterns = ['node_modules', '__pycache__', '.git', 'dist', 'build']; // defaults
+
+  if (scoutignorePath && fs.existsSync(scoutignorePath)) {
+    const content = fs.readFileSync(scoutignorePath, 'utf-8');
+    const patterns = content
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#'));
+    if (patterns.length > 0) {
+      blockedPatterns = patterns;
+    }
+  }
+
+  // Escape special regex characters and build dynamic patterns
+  const escapeRegex = (str) => str.replace(/[.*+?^\${}()|[\]\\\\]/g, '\\\\$&');
+  const escapedPatterns = blockedPatterns.map(escapeRegex);
+  const patternGroup = escapedPatterns.join('|');
+
+  // Pattern for directory paths (used for file_path, path, pattern)
+  const blockedDirPattern = new RegExp('(^|/|\\\\s)(' + patternGroup + ')(/|\$|\\\\s)');
+
+  // Pattern for Bash commands - only block directory access, not build commands
+  // Blocks: cd node_modules, ls build/, cat dist/file.js
+  // Allows: npm build, pnpm build, yarn build, npm run build
+  const blockedBashPattern = new RegExp(
+    '(cd\\\\s+|ls\\\\s+|cat\\\\s+|rm\\\\s+|cp\\\\s+|mv\\\\s+|find\\\\s+)(' + patternGroup + ')(/|\$|\\\\s)|' +
+    '(\\\\s|^|/)(' + patternGroup + ')/'
+  );
+
+  // Check file path parameters (strict blocking)
+  const fileParams = [
+    toolInput.file_path,    // Read, Edit, Write tools
+    toolInput.path,         // Grep, Glob tools
+    toolInput.pattern       // Glob, Grep tools
+  ];
+
+  for (const param of fileParams) {
+    if (param && typeof param === 'string' && blockedDirPattern.test(param)) {
+      console.log('BLOCKED');
+      process.exit(0);
+    }
+  }
+
+  // Check Bash command (selective blocking - only directory access)
+  if (toolInput.command && typeof toolInput.command === 'string') {
+    if (blockedBashPattern.test(toolInput.command)) {
+      console.log('BLOCKED');
+      process.exit(0);
+    }
+  }
+
+  console.log('ALLOWED');
+} catch (error) {
+  // If JSON parsing fails, allow operation with warning (fail-open approach)
+  // This prevents hook configuration issues from blocking all operations
+  console.error('WARN: JSON parse failed, allowing operation -', error.message);
+  console.log('ALLOWED');
+  process.exit(0);
+}
+")
+
+# Check if parsing failed
+if [ $? -ne 0 ]; then
+  exit 2
+fi
+
+# Check result
+if [ "$CHECK_RESULT" = "BLOCKED" ]; then
+  echo "ERROR: Blocked directory pattern (node_modules, __pycache__, .git/, dist/, build/)" >&2
+  exit 2
+fi
+
+# Allow command (exit 0)
+exit 0

package/templates/.claude/hooks/scout-block.cjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * scout-block.js - Cross-platform hook dispatcher
+ *
+ * Blocks access to directories listed in .claude/.scoutignore
+ * (defaults: node_modules, __pycache__, .git, dist, build)
+ *
+ * Blocking Rules:
+ * - File paths: Blocks any file_path/path/pattern containing blocked directories
+ * - Bash commands: Blocks directory access (cd, ls, cat, etc.) but ALLOWS build commands
+ *   - Blocked: cd node_modules, ls build/, cat dist/file.js
+ *   - Allowed: npm build, pnpm build, yarn build, npm run build
+ *
+ * Configuration:
+ * - Edit .claude/.scoutignore to customize blocked patterns (one per line, # for comments)
+ *
+ * Platform Detection:
+ * - Windows (win32): Uses PowerShell via scout-block.ps1
+ * - Unix (linux/darwin): Uses Bash via scout-block.sh
+ * - WSL: Automatically detects and uses bash implementation
+ *
+ * Exit Codes:
+ * - 0: Command allowed
+ * - 2: Command blocked or error occurred
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+// __dirname and __filename are already available in CommonJS
+
+try {
+  // Read stdin synchronously
+  const hookInput = fs.readFileSync(0, 'utf-8');
+
+  // Validate input not empty
+  if (!hookInput || hookInput.trim().length === 0) {
+    console.error('ERROR: Empty input');
+    process.exit(2);
+  }
+
+  // Validate JSON structure (basic check)
+  try {
+    const data = JSON.parse(hookInput);
+    if (!data.tool_input || typeof data.tool_input !== 'object') {
+      console.error('ERROR: Invalid JSON structure');
+      process.exit(2);
+    }
+  } catch (parseError) {
+    console.error('ERROR: JSON parse failed:', parseError.message);
+    process.exit(2);
+  }
+
+  // Determine platform
+  const platform = process.platform;
+  const scriptDir = __dirname;
+
+  if (platform === 'win32') {
+    // Windows: Use PowerShell implementation
+    const psScript = path.join(scriptDir, 'scout-block', 'scout-block.ps1');
+
+    // Check if PowerShell script exists
+    if (!fs.existsSync(psScript)) {
+      console.error(`ERROR: PowerShell script not found: ${psScript}`);
+      process.exit(2);
+    }
+
+    // Execute PowerShell script with stdin piped
+    execSync(`powershell -NoProfile -ExecutionPolicy Bypass -File "${psScript}"`, {
+      input: hookInput,
+      stdio: ['pipe', 'inherit', 'inherit'],
+      encoding: 'utf-8'
+    });
+  } else {
+    // Unix (Linux, macOS, WSL): Use bash implementation
+    const bashScript = path.join(scriptDir, 'scout-block', 'scout-block.sh');
+
+    // Check if bash script exists
+    if (!fs.existsSync(bashScript)) {
+      console.error(`ERROR: Bash script not found: ${bashScript}`);
+      process.exit(2);
+    }
+
+    // Execute bash script with stdin piped
+    execSync(`bash "${bashScript}"`, {
+      input: hookInput,
+      stdio: ['pipe', 'inherit', 'inherit'],
+      encoding: 'utf-8'
+    });
+  }
+} catch (error) {
+  // Log error details for debugging
+  if (error.message) {
+    console.error('ERROR:', error.message);
+  }
+
+  // Exit with error code from child process, or 2 if undefined
+  process.exit(error.status || 2);
+}

package/templates/.claude/hooks/scout-block.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+/**
+ * scout-block.js - Cross-platform hook dispatcher
+ *
+ * Blocks access to directories listed in .claude/.scoutignore
+ * (defaults: node_modules, __pycache__, .git, dist, build)
+ *
+ * Blocking Rules:
+ * - File paths: Blocks any file_path/path/pattern containing blocked directories
+ * - Bash commands: Blocks directory access (cd, ls, cat, etc.) but ALLOWS build commands
+ *   - Blocked: cd node_modules, ls build/, cat dist/file.js
+ *   - Allowed: npm build, pnpm build, yarn build, npm run build
+ *
+ * Configuration:
+ * - Edit .claude/.scoutignore to customize blocked patterns (one per line, # for comments)
+ *
+ * Platform Detection:
+ * - Windows (win32): Uses PowerShell via scout-block.ps1
+ * - Unix (linux/darwin): Uses Bash via scout-block.sh
+ * - WSL: Automatically detects and uses bash implementation
+ *
+ * Exit Codes:
+ * - 0: Command allowed
+ * - 2: Command blocked or error occurred
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+try {
+  // Read stdin synchronously
+  const hookInput = fs.readFileSync(0, 'utf-8');
+
+  // Validate input not empty
+  if (!hookInput || hookInput.trim().length === 0) {
+    console.error('ERROR: Empty input');
+    process.exit(2);
+  }
+
+  // Validate JSON structure (basic check)
+  try {
+    const data = JSON.parse(hookInput);
+    if (!data.tool_input || typeof data.tool_input !== 'object') {
+      console.error('ERROR: Invalid JSON structure');
+      process.exit(2);
+    }
+  } catch (parseError) {
+    console.error('ERROR: JSON parse failed:', parseError.message);
+    process.exit(2);
+  }
+
+  // Determine platform
+  const platform = process.platform;
+  const scriptDir = __dirname;
+
+  if (platform === 'win32') {
+    // Windows: Use PowerShell implementation
+    const psScript = path.join(scriptDir, 'scout-block', 'scout-block.ps1');
+
+    // Check if PowerShell script exists
+    if (!fs.existsSync(psScript)) {
+      console.error(`ERROR: PowerShell script not found: ${psScript}`);
+      process.exit(2);
+    }
+
+    // Execute PowerShell script with stdin piped
+    execSync(`powershell -NoProfile -ExecutionPolicy Bypass -File "${psScript}"`, {
+      input: hookInput,
+      stdio: ['pipe', 'inherit', 'inherit'],
+      encoding: 'utf-8'
+    });
+  } else {
+    // Unix (Linux, macOS, WSL): Use bash implementation
+    const bashScript = path.join(scriptDir, 'scout-block', 'scout-block.sh');
+
+    // Check if bash script exists
+    if (!fs.existsSync(bashScript)) {
+      console.error(`ERROR: Bash script not found: ${bashScript}`);
+      process.exit(2);
+    }
+
+    // Execute bash script with stdin piped
+    execSync(`bash "${bashScript}"`, {
+      input: hookInput,
+      stdio: ['pipe', 'inherit', 'inherit'],
+      encoding: 'utf-8'
+    });
+  }
+} catch (error) {
+  // Log error details for debugging
+  if (error.message) {
+    console.error('ERROR:', error.message);
+  }
+
+  // Exit with error code from child process, or 2 if undefined
+  process.exit(error.status || 2);
+}

package/templates/.claude/repomix.config.json

@@ -0,0 +1,34 @@
+{
+  "output": {
+    "filePath": "repomix-output.xml",
+    "style": "xml"
+  },
+  "ignore": {
+    "useGitignore": true,
+    "useDefaultPatterns": true,
+    "customPatterns": [
+      "docs/*",
+      "plans/*",
+      "assets/*",
+      "dist/*",
+      "coverage/*",
+      "build/*",
+      "ios/*",
+      "android/*",
+      "tests/*",
+      "__tests__/*",
+      "__pycache__/*",
+      "node_modules/*",
+      ".opencode/*",
+      ".claude/*",
+      ".serena/*",
+      ".pnpm-store/*",
+      ".github/*",
+      ".dart_tool/*",
+      ".idea/*",
+      ".husky/*",
+      ".venv/*",
+      ".npmrc"
+    ]
+  }
+}

package/templates/.claude/rules/01-core-principles.md

@@ -0,0 +1,81 @@
+# Core Principles
+
+> Foundational software engineering principles that guide all development decisions.
+
+---
+
+## YAGNI - You Aren't Gonna Need It
+
+- Only implement features when they are actually needed, not when you foresee they might be useful
+- Avoid overengineering and premature optimization
+- Focus on current iteration requirements in Agile workflows
+- Delete unused code rather than commenting it out "for later"
+
+---
+
+## KISS - Keep It Simple, Superstar
+
+- Prefer the simplest solution that solves the problem
+- Complex solutions are harder to debug, test, and extend
+- If code requires extensive comments to explain, consider refactoring
+- Break complex logic into smaller, focused functions
+- **Key tip:** If you can't explain your code to a junior developer, it's probably too complex
+- Break complex conditionals into named variables for clarity:
+
+```typescript
+// BAD - Hard to understand
+if (x && y || z && !a) { /* ... */ }
+
+// GOOD - Self-documenting
+const isValid = x && y;
+const isSpecialCase = z && !a;
+if (isValid || isSpecialCase) { /* ... */ }
+```
+
+---
+
+## DRY - Don't Repeat Yourself
+
+- Every piece of knowledge should have a single, authoritative representation
+- Extract repeated logic into reusable functions, classes, or modules
+- Create centralized services for common operations (authentication, validation, formatting)
+- Balance DRY with readability - KISS takes precedence over DRY when they conflict
+- **Key tip:** Create a `utils` or `helpers` module for commonly reused functionality
+- Copy-paste is a code smell - if you're copying, you should be extracting
+
+---
+
+## SOLID Principles (Object-Oriented Design)
+
+### Single Responsibility Principle (SRP)
+
+- A class/module should have only one reason to change
+- Keep each component focused on one job
+- Split large classes with multiple responsibilities
+- **Key tip:** If your function name needs a conjunction (and/or), it's violating this principle
+- Classes with names like `Manager`, `Processor`, or `Helper` often do too much
+- **Class size guideline:** If your class has more than 200 lines, it's probably doing too much
+
+### Open/Closed Principle (OCP)
+
+- Software should be open for extension but closed for modification
+- Add new behavior without changing existing code
+- Use interfaces, abstract classes, and composition
+
+### Liskov Substitution Principle (LSP)
+
+- Subclasses should be substitutable for their parent classes
+- Derived classes must honor the contracts of their base classes
+- Avoid inheritance that breaks expected behavior
+
+### Interface Segregation Principle (ISP)
+
+- Clients should not depend on interfaces they don't use
+- Split large interfaces into smaller, specific ones
+- Prefer many small interfaces over one large interface
+
+### Dependency Inversion Principle (DIP)
+
+- Depend on abstractions, not concrete implementations
+- High-level modules should not depend on low-level modules
+- Use dependency injection to promote loose coupling

package/templates/.claude/rules/02-naming-and-constants.md

@@ -0,0 +1,115 @@
+# Naming Conventions & Constants
+
+> Clear, consistent naming makes code self-documenting and maintainable.
+
+---
+
+## General Naming Rules
+
+- Use meaningful, descriptive names that convey purpose
+- Avoid abbreviations and single-letter variables (except loop counters in small scopes)
+- Names should be pronounceable for easier code reviews
+- Be consistent throughout the codebase
+- **Key tip:** Use searchable names! Try finding all usages of `k` vs `user_age` in a large codebase
+- **Self-test:** Read your code aloud - if it sounds natural, you're on the right track
+
+### Variable Naming
+
+```
+BAD:  x, tmp, data, val, usr, btn, idx, arr, cb, e, d, t, n
+GOOD: totalScore, temporaryFile, userData, calculatedValue, currentUser,
+      submitButton, targetIndex, activeUsers, onCompleteCallback,
+      authenticationError, currentDate, startTimestamp, itemCount
+```
+
+### Function/Method Naming
+
+- Use verbs for actions: `calculateTotal()`, `fetchUserData()`, `validateInput()`
+- Use `is/has/can/should` prefixes for booleans: `isActive()`, `hasPermission()`, `canEdit()`
+- Avoid functions with "and" in the name - split into multiple functions
+- Be consistent: don't mix `fetch`, `get`, and `retrieve` for similar operations
+
+### Class Naming
+
+- Use nouns and noun phrases: `Customer`, `OrderProcessor`, `PaymentGateway`
+- Use PascalCase/UpperCamelCase for class names
+- Avoid generic names like `Manager`, `Handler`, `Data` without context
+
+### Language-Specific Conventions
+
+| Element | Python/Ruby | JavaScript/TypeScript | Java/C# | Go |
+|---------|-------------|----------------------|---------|-----|
+| Variables | snake_case | camelCase | camelCase | camelCase |
+| Functions | snake_case | camelCase | camelCase | PascalCase (exported) |
+| Classes | PascalCase | PascalCase | PascalCase | PascalCase |
+| Constants | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE | PascalCase |
+| Files | snake_case | kebab-case or camelCase | PascalCase | snake_case |
+
+---
+
+## Constants & Magic Values
+
+### Rules
+
+- Extract ALL hardcoded values into named constants
+- Use SCREAMING_SNAKE_CASE: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT_MS`
+- Create dedicated constants files: `constants.ts`, `constants.py`, `Constants.java`
+- Group related constants in objects/enums
+- Document the purpose of non-obvious constants
+- Never use magic numbers or strings in code
+
+### Examples
+
+```typescript
+// BAD - Magic numbers and strings
+if (user.age >= 18) { /* ... */ }
+if (status === 'active') { /* ... */ }
+setTimeout(callback, 3600000);
+if (items.length > 100) { /* ... */ }
+
+// GOOD - Named constants
+export const MINIMUM_ADULT_AGE = 18;
+export const USER_STATUS = {
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+  PENDING: 'pending',
+} as const;
+export const ONE_HOUR_MS = 60 * 60 * 1000;
+export const MAX_ITEMS_PER_PAGE = 100;
+
+if (user.age >= MINIMUM_ADULT_AGE) { /* ... */ }
+if (status === USER_STATUS.ACTIVE) { /* ... */ }
+setTimeout(callback, ONE_HOUR_MS);
+if (items.length > MAX_ITEMS_PER_PAGE) { /* ... */ }
+```
+
+---
+
+## Consistent Patterns - Be Predictable
+
+### Why Consistency Matters
+
+- Makes code easier to understand and maintain
+- Reduces cognitive load when switching between files
+- Enables effective code reviews
+- **Key tip:** Create a style guide for your project and enforce it with linting tools
+
+### Areas to Standardize
+
+- Naming conventions (don't mix `get`, `fetch`, and `retrieve`)
+- File organization and structure
+- Error handling approach
+- API response formats
+- State management patterns
+
+```typescript
+// BAD - Inconsistent naming
+function getUsers() { /* ... */ }
+function fetchProducts() { /* ... */ }
+function retrieveOrders() { /* ... */ }
+
+// GOOD - Consistent naming
+function getUsers() { /* ... */ }
+function getProducts() { /* ... */ }
+function getOrders() { /* ... */ }
+```