start-vibing 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "Setup Claude Code agents, skills, and hooks in your project. Smart copy that preserves your custom domains and configurations.",
   "type": "module",
   "bin": {

package/template/.claude/agents/01-orchestration/checkpoint-manager.md

@@ -1,6 +1,6 @@
 ---
 name: checkpoint-manager
-description: "Saves and restores workflow checkpoints. Invoke before risky operations or when resuming interrupted work. Enables resume from failure."
+description: "AUTOMATICALLY invoke BEFORE risky operations. Triggers: before git operations, before file deletions, before major refactors. Saves and restores workflow checkpoints. PROACTIVELY saves state before destructive operations."
 model: haiku
 tools: Read, Write, Grep, Glob
 ---

package/template/.claude/agents/01-orchestration/context-manager.md

@@ -1,6 +1,6 @@
 ---
 name: context-manager
-description: "Manages context between agents. Compresses state, saves checkpoints, prunes irrelevant data. Invoke when context is growing large or between major phases."
+description: "AUTOMATICALLY invoke when context grows large or between major phases. Triggers: agent handoff, long conversation, context bloat. Compresses state, saves checkpoints, prunes irrelevant data. PROACTIVELY manages token budget."
 model: haiku
 tools: Read, Write, Grep, Glob
 ---

package/template/.claude/agents/01-orchestration/error-recovery.md

@@ -1,6 +1,6 @@
 ---
 name: error-recovery
-description: "Handles agent failures and implements recovery strategies. Invoke when an agent fails or returns unexpected results. Implements retry logic and fallbacks."
+description: "AUTOMATICALLY invoke when an agent fails or returns unexpected results. Triggers: tool failure, agent timeout, validation failure, unexpected error. Implements retry logic and fallbacks. PROACTIVELY handles failures in the pipeline."
 model: sonnet
 tools: Read, Bash, Grep, Glob
 ---

package/template/.claude/agents/01-orchestration/orchestrator.md

@@ -1,6 +1,6 @@
 ---
 name: orchestrator
-description: "MAIN ORCHESTRATOR. Invoke for ANY multi-step task. Triggers: 'implement', 'build', 'create', 'fix and test'. Coordinates specialized sub-agents in parallel. Decomposes complex tasks into subtasks."
+description: "AUTOMATICALLY invoke for ANY multi-step task. Triggers: 'implement feature', 'build X', 'create Y', 'fix and test', 'full workflow'. Coordinates ALL other agents in sequence. Use when task requires >2 agents or touches >3 files. PROACTIVELY takes control of complex development flows."
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
 skills: codebase-knowledge

package/template/.claude/agents/01-orchestration/parallel-coordinator.md

@@ -1,6 +1,6 @@
 ---
 name: parallel-coordinator
-description: "Coordinates parallel agent execution. Invoke when multiple independent agents should run simultaneously. Manages fan-out/gather pattern."
+description: "AUTOMATICALLY invoke when multiple independent agents should run simultaneously. Triggers: parallel execution needed, fan-out/gather pattern, independent tasks identified. Coordinates parallel agent execution. PROACTIVELY optimizes multi-agent workflows."
 model: haiku
 tools: Read, Grep, Glob
 ---

package/template/.claude/agents/01-orchestration/task-decomposer.md

@@ -1,6 +1,6 @@
 ---
 name: task-decomposer
-description: "Breaks complex tasks into atomic subtasks. Invoke when task has >3 steps or touches >3 files. Creates structured task breakdown for parallel execution."
+description: "AUTOMATICALLY invoke when task has >3 steps or touches >3 files. Triggers: complex task, multi-domain task, unclear scope, feature implementation. Breaks complex tasks into atomic subtasks for parallel execution. PROACTIVELY decomposes before implementation."
 model: haiku
 tools: Read, Grep, Glob
 skills: codebase-knowledge

package/template/.claude/agents/01-orchestration/workflow-router.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-router
-description: "Routes tasks to correct agent based on keywords, file types, and context. Invoke when unsure which agent handles a request."
+description: "AUTOMATICALLY invoke at task start to route to correct agent. Triggers: new request, unclear which agent, multiple valid routes. Routes tasks based on keywords, file types, and context. PROACTIVELY analyzes requests for optimal routing."
 model: haiku
 tools: Read, Grep, Glob
 ---

package/template/.claude/agents/02-typescript/bun-runtime-expert.md

@@ -1,6 +1,6 @@
 ---
 name: bun-runtime-expert
-description: "Expert in Bun runtime specifics. Triggers: 'bun', runtime issues, package management. Handles Bun-specific APIs and configurations."
+description: "AUTOMATICALLY invoke when using Bun runtime. Triggers: 'bun', runtime issues, package management, node compatibility. Expert in Bun-specific APIs and configurations. PROACTIVELY suggests Bun alternatives to Node.js."
 model: haiku
 tools: Read, Bash, Grep, Glob
 ---

package/template/.claude/agents/02-typescript/esm-resolver.md

@@ -1,6 +1,6 @@
 ---
 name: esm-resolver
-description: "Resolves ESM module issues. Triggers: 'module error', 'import error', 'cannot find module'. Fixes ESM/CJS compatibility."
+description: "AUTOMATICALLY invoke on module errors. Triggers: 'module error', 'import error', 'cannot find module', 'require is not defined'. Fixes ESM/CJS compatibility issues. PROACTIVELY resolves import problems."
 model: haiku
 tools: Read, Grep, Glob
 ---

package/template/.claude/agents/02-typescript/import-alias-enforcer.md

@@ -1,6 +1,6 @@
 ---
 name: import-alias-enforcer
-description: "Enforces path alias usage. Triggers: reviewing imports, 'import error'. Ensures $types/*, @common, @db aliases are used correctly."
+description: "AUTOMATICALLY invoke AFTER editing .ts files. Triggers: new .ts file, imports added, code review. Enforces $types/*, @common, @db aliases. PROACTIVELY checks all imports use correct aliases."
 model: haiku
 tools: Read, Grep, Glob
 ---

package/template/.claude/agents/02-typescript/ts-migration-helper.md

@@ -1,6 +1,6 @@
 ---
 name: ts-migration-helper
-description: "Helps migrate JavaScript to TypeScript. Triggers: 'migrate to ts', 'convert to typescript'. Adds types progressively with strict mode."
+description: "Helps migrate JavaScript to TypeScript. Triggers: 'migrate to ts', 'convert to typescript', .js files in project. Adds types progressively with strict mode."
 model: sonnet
 tools: Read, Write, Edit, Grep, Glob, Bash
 ---

package/template/.claude/agents/02-typescript/ts-strict-checker.md

@@ -1,6 +1,6 @@
 ---
 name: ts-strict-checker
-description: "Enforces TypeScript strict mode rules. Triggers: editing .ts files, 'strict mode', 'type error'. Validates index access, literal types, null checks."
+description: "AUTOMATICALLY invoke AFTER editing any .ts file. Triggers: editing .ts files, new .ts file, process.env access. Validates index access, literal types, null checks. PROACTIVELY enforces TypeScript strict mode rules."
 model: haiku
 tools: Read, Grep, Glob, Bash
 ---

package/template/.claude/agents/02-typescript/ts-types-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: ts-types-analyzer
-description: "Analyzes complex TypeScript types. Triggers: 'type error', 'inference issue', 'generic problem'. Debugs type inference and provides fixes."
+description: "AUTOMATICALLY invoke on type errors. Triggers: 'type error', 'inference issue', 'generic problem', typecheck fails. Analyzes complex TypeScript types and debugs inference. PROACTIVELY fixes type issues."
 model: sonnet
 tools: Read, Grep, Glob, Bash
 ---

package/template/.claude/agents/02-typescript/type-definition-writer.md

@@ -1,6 +1,6 @@
 ---
 name: type-definition-writer
-description: "Writes type definitions for types/ folder. Triggers: new model, new API, 'add types'. Creates interfaces and types following project conventions."
+description: "AUTOMATICALLY invoke BEFORE implementing new entities. Triggers: new model, new API, new entity, interface needed. Writes type definitions for types/ folder. PROACTIVELY creates interfaces following project conventions."
 model: haiku
 tools: Read, Write, Edit, Grep, Glob
 ---

package/template/.claude/agents/02-typescript/zod-schema-designer.md

@@ -1,6 +1,6 @@
 ---
 name: zod-schema-designer
-description: "Designs Zod validation schemas. Triggers: 'zod', 'validation', 'schema', new API endpoint. Creates comprehensive input validation."
+description: "AUTOMATICALLY invoke BEFORE implementing any API endpoint. Triggers: new API endpoint, new route, form input, user input. Designs Zod validation schemas. PROACTIVELY creates comprehensive input validation."
 model: sonnet
 tools: Read, Write, Edit, Grep, Glob
 skills: codebase-knowledge

package/template/.claude/agents/02-typescript/zod-validator.md

@@ -1,6 +1,6 @@
 ---
 name: zod-validator
-description: "Validates existing Zod schemas for completeness. Triggers: 'validate schema', reviewing API. Checks all routes have proper validation."
+description: "AUTOMATICALLY invoke BEFORE commit when API routes exist. Triggers: API route modified, security audit, validation audit. Validates all routes have proper Zod validation. PROACTIVELY checks schema completeness."
 model: haiku
 tools: Read, Grep, Glob
 ---

package/template/.claude/hooks/SETUP.md

@@ -2,21 +2,37 @@
 
 ## Overview
 
-This system provides agent selection guidance by analyzing prompts and suggesting the best agent for the task.
+This system provides agent selection guidance by analyzing prompts and suggesting the best agent for the task. It includes a **universal hook runner** that supports multiple runtimes with automatic fallback.
 
-## Requirements
+## Runtime Support
 
-- Python 3.8+
+The hooks use a universal runner (`run-hook.ts`) that automatically detects and uses the first available runtime:
+
+| Priority | Runtime    | Extension | Notes                      |
+| -------- | ---------- | --------- | -------------------------- |
+| 1        | python3    | .py       | Primary (user's preferred) |
+| 2        | python     | .py       | Fallback                   |
+| 3        | bun        | .ts       | TypeScript fallback        |
+| 4        | npx tsx    | .ts       | Final fallback             |
+
+**If no runtime is available**, the hooks return a safe default (approve/continue) to avoid blocking the user.
 
 ## Files
 
-| File                     | Purpose                                               |
-| ------------------------ | ----------------------------------------------------- |
-| `user-prompt-submit.py`  | Analyzes prompts and suggests appropriate agents      |
+| File                      | Purpose                                                 |
+| ------------------------- | ------------------------------------------------------- |
+| `run-hook.ts`             | Universal runner with runtime detection                 |
+| `run-hook.sh`             | Shell wrapper for Unix/Linux/Mac                        |
+| `run-hook.cmd`            | Batch wrapper for Windows                               |
+| `user-prompt-submit.py`   | Analyzes prompts and suggests agents (Python)           |
+| `user-prompt-submit.ts`   | Same as above (TypeScript fallback)                     |
+| `stop-validator.py`       | Validates before task completion (Python)               |
+| `stop-validator.ts`       | Same as above (TypeScript fallback)                     |
+| `check-documentation.py`  | Verifies file documentation (Python)                    |
 
 ## Claude Code Configuration
 
-The hooks are configured in `.claude/settings.local.json`:
+The hooks are configured in `.claude/settings.json`:
 
 ```json
 {
@@ -27,16 +43,34 @@ The hooks are configured in `.claude/settings.local.json`:
 				"hooks": [
 					{
 						"type": "command",
-						"command": "python .claude/hooks/user-prompt-submit.py",
+						"command": "bun .claude/hooks/run-hook.ts user-prompt-submit",
 						"timeout": 10
 					}
 				]
 			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "bun .claude/hooks/run-hook.ts stop-validator",
+						"timeout": 30
+					}
+				]
+			}
 		]
 	}
 }
 ```
 
+## How It Works
+
+1. Claude Code calls `bun .claude/hooks/run-hook.ts <hook-name>`
+2. `run-hook.ts` checks for available runtimes in priority order
+3. First available runtime executes the corresponding hook file (.py or .ts)
+4. If no runtime is available, returns safe default to avoid blocking
+
 ## Environment Variables
 
 | Variable             | Default       | Description            |
@@ -47,6 +81,46 @@ The hooks are configured in `.claude/settings.local.json`:
 
 ### Hooks not executing
 
-1. Verify Python is in PATH
-2. Check `.claude/settings.local.json` hooks configuration
-3. Ensure hook files have execute permissions
+1. Verify Bun is in PATH: `bun --version`
+2. If Python is preferred, verify: `python3 --version` or `python --version`
+3. Check `.claude/settings.json` hooks configuration
+4. Ensure hook files exist in `.claude/hooks/`
+
+### "python: not found" error
+
+This error occurs when Python is not installed or not in PATH. The universal runner will automatically fallback to TypeScript hooks run by Bun.
+
+**Solutions:**
+
+1. **Install Python** (recommended for full functionality):
+   - Windows: `winget install Python.Python.3.12` or download from python.org
+   - Linux: `apt install python3` or `dnf install python3`
+   - Mac: `brew install python3`
+
+2. **Use Bun only** (already configured):
+   - TypeScript fallback hooks are automatically used when Python is unavailable
+   - No additional setup required
+
+### Runtime detection failed
+
+If you see `[run-hook] No runtime available`:
+
+1. Ensure at least one runtime is installed: python3, python, bun, or Node.js
+2. Verify the runtime is in your system PATH
+3. For Bun: `curl -fsSL https://bun.sh/install | bash`
+4. For Node.js (npx tsx): Install from nodejs.org
+
+## Testing Hooks
+
+Test the hook runner manually:
+
+```bash
+# Test with Bun
+echo '{}' | bun .claude/hooks/run-hook.ts user-prompt-submit
+
+# Test with Python (if available)
+echo '{}' | python3 .claude/hooks/user-prompt-submit.py
+
+# Test stop-validator
+echo '{}' | bun .claude/hooks/run-hook.ts stop-validator
+```

package/template/.claude/hooks/run-hook.cmd

@@ -0,0 +1,46 @@
+@echo off
+REM Universal Hook Runner for Windows
+REM Tries: python -> python3 -> bun -> npx tsx
+
+set HOOK_NAME=%1
+set HOOKS_DIR=%~dp0
+
+REM Try Python first
+where python >nul 2>&1
+if %ERRORLEVEL% EQU 0 (
+    if exist "%HOOKS_DIR%%HOOK_NAME%.py" (
+        python "%HOOKS_DIR%%HOOK_NAME%.py"
+        exit /b %ERRORLEVEL%
+    )
+)
+
+REM Try Python3
+where python3 >nul 2>&1
+if %ERRORLEVEL% EQU 0 (
+    if exist "%HOOKS_DIR%%HOOK_NAME%.py" (
+        python3 "%HOOKS_DIR%%HOOK_NAME%.py"
+        exit /b %ERRORLEVEL%
+    )
+)
+
+REM Try Bun with TypeScript
+where bun >nul 2>&1
+if %ERRORLEVEL% EQU 0 (
+    if exist "%HOOKS_DIR%%HOOK_NAME%.ts" (
+        bun "%HOOKS_DIR%%HOOK_NAME%.ts"
+        exit /b %ERRORLEVEL%
+    )
+)
+
+REM Try npx tsx as final fallback
+where npx >nul 2>&1
+if %ERRORLEVEL% EQU 0 (
+    if exist "%HOOKS_DIR%%HOOK_NAME%.ts" (
+        npx tsx "%HOOKS_DIR%%HOOK_NAME%.ts"
+        exit /b %ERRORLEVEL%
+    )
+)
+
+REM No runtime available - return safe default
+echo {"decision":"approve","reason":"No runtime available for hook, allowing by default"}
+exit /b 0

package/template/.claude/hooks/run-hook.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Universal Hook Runner for Unix/Linux/Mac
+# Tries: python3 -> python -> bun -> npx tsx
+
+HOOK_NAME="$1"
+HOOKS_DIR="$(dirname "$0")"
+
+# Check if a command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Try Python3 first
+if command_exists python3; then
+    if [ -f "$HOOKS_DIR/$HOOK_NAME.py" ]; then
+        exec python3 "$HOOKS_DIR/$HOOK_NAME.py"
+    fi
+fi
+
+# Try Python
+if command_exists python; then
+    if [ -f "$HOOKS_DIR/$HOOK_NAME.py" ]; then
+        exec python "$HOOKS_DIR/$HOOK_NAME.py"
+    fi
+fi
+
+# Try Bun with TypeScript
+if command_exists bun; then
+    if [ -f "$HOOKS_DIR/$HOOK_NAME.ts" ]; then
+        exec bun "$HOOKS_DIR/$HOOK_NAME.ts"
+    fi
+fi
+
+# Try npx tsx as final fallback
+if command_exists npx; then
+    if [ -f "$HOOKS_DIR/$HOOK_NAME.ts" ]; then
+        exec npx tsx "$HOOKS_DIR/$HOOK_NAME.ts"
+    fi
+fi
+
+# No runtime available - return safe default
+echo '{"decision":"approve","reason":"No runtime available for hook, allowing by default"}'
+exit 0

package/template/.claude/hooks/run-hook.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env bun
+/**
+ * Universal Hook Runner
+ *
+ * Runs hooks with multiple runtime fallbacks:
+ * 1. python3 (primary - user's preferred)
+ * 2. python (fallback)
+ * 3. Bun TypeScript (fallback if Python not available)
+ * 4. npx tsx (final fallback)
+ *
+ * Usage: bun run-hook.ts <hook-name>
+ * The hook-name should be without extension (e.g., "stop-validator")
+ */
+
+import { spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Get hooks directory - handle both ESM and CJS contexts
+const getHooksDir = (): string => {
+  try {
+    if (typeof import.meta.url !== 'undefined') {
+      return dirname(fileURLToPath(import.meta.url));
+    }
+  } catch {
+    // Fallback for environments where import.meta is not available
+  }
+  return process.cwd();
+};
+
+const HOOKS_DIR = getHooksDir();
+
+function checkRuntime(cmd: string): boolean {
+  try {
+    const result = spawnSync(cmd, ['--version'], {
+      stdio: 'pipe',
+      shell: true,
+      timeout: 5000,
+      windowsHide: true
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function runWithRuntime(cmd: string, args: string[], input: string): { success: boolean; output: string; error?: string } {
+  try {
+    const result = spawnSync(cmd, args, {
+      input,
+      shell: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 30000,
+      windowsHide: true,
+      encoding: 'utf8'
+    });
+
+    return {
+      success: result.status === 0,
+      output: result.stdout?.toString() || '',
+      error: result.stderr?.toString() || undefined
+    };
+  } catch (err) {
+    return {
+      success: false,
+      output: '',
+      error: err instanceof Error ? err.message : 'Unknown error'
+    };
+  }
+}
+
+async function runHook(hookName: string, stdinData: string): Promise<void> {
+  const tsPath = join(HOOKS_DIR, `${hookName}.ts`);
+  const pyPath = join(HOOKS_DIR, `${hookName}.py`);
+
+  // Runtime detection order - Python FIRST, then fallbacks
+  const runtimes: Array<{ name: string; cmd: string; ext: string }> = [
+    { name: 'python3', cmd: 'python3', ext: '.py' },
+    { name: 'python', cmd: 'python', ext: '.py' },
+    { name: 'bun-ts', cmd: 'bun', ext: '.ts' },
+    { name: 'npx-tsx', cmd: 'npx tsx', ext: '.ts' }
+  ];
+
+  for (const runtime of runtimes) {
+    const hookPath = runtime.ext === '.ts' ? tsPath : pyPath;
+
+    if (!existsSync(hookPath)) {
+      continue;
+    }
+
+    if (!checkRuntime(runtime.cmd.split(' ')[0])) {
+      continue;
+    }
+
+    const result = runWithRuntime(runtime.cmd, [hookPath], stdinData);
+
+    if (result.success || !result.error?.includes('not found')) {
+      // Runtime worked (success or runtime-specific failure)
+      process.stdout.write(result.output);
+      if (result.error && !result.success) {
+        process.stderr.write(result.error);
+      }
+      process.exit(result.success ? 0 : 1);
+    }
+    // Runtime not available, try next
+  }
+
+  // No runtime available - return safe default
+  console.error(`[run-hook] No runtime available to run hook: ${hookName}`);
+  console.error('[run-hook] Please install one of: python3, python, bun, or Node.js');
+  const safeDefault = JSON.stringify({
+    decision: 'approve',
+    continue: true,
+    reason: 'Hook runtime not available, allowing by default'
+  });
+  process.stdout.write(safeDefault);
+  process.exit(0);
+}
+
+async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => resolve('{}'), timeoutMs);
+
+    Bun.stdin.text().then((text) => {
+      clearTimeout(timeout);
+      resolve(text || '{}');
+    }).catch(() => {
+      clearTimeout(timeout);
+      resolve('{}');
+    });
+  });
+}
+
+// Main
+async function main(): Promise<void> {
+  const hookName = process.argv[2];
+  if (!hookName) {
+    console.error('Usage: bun run-hook.ts <hook-name>');
+    process.exit(1);
+  }
+
+  // Read stdin with timeout to avoid hanging
+  const stdinData = await readStdinWithTimeout(2000);
+  await runHook(hookName, stdinData);
+}
+
+main().catch((err) => {
+  console.error('[run-hook] Fatal error:', err);
+  // Return safe default on error
+  const safeDefault = JSON.stringify({
+    decision: 'approve',
+    continue: true,
+    reason: 'Hook runner error, allowing by default'
+  });
+  process.stdout.write(safeDefault);
+  process.exit(0);
+});