start-vibing 2.0.21 → 2.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.21",
+	"version": "2.0.22",
 	"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/hooks/run-hook.ts

@@ -67,11 +67,17 @@ function checkRuntime(cmd: string): boolean {
 	}
 }
 
+interface RuntimeResult {
+	exitCode: number;
+	output: string;
+	error?: string;
+}
+
 function runWithRuntime(
 	cmd: string,
 	args: string[],
 	input: string
-): { success: boolean; output: string; error?: string } {
+): RuntimeResult {
 	try {
 		const result = spawnSync(cmd, args, {
 			input,
@@ -83,13 +89,13 @@ function runWithRuntime(
 		});
 
 		return {
-			success: result.status === 0,
+			exitCode: result.status ?? 1,
 			output: result.stdout?.toString() || '',
 			error: result.stderr?.toString() || undefined,
 		};
 	} catch (err) {
 		return {
-			success: false,
+			exitCode: 1,
 			output: '',
 			error: err instanceof Error ? err.message : 'Unknown error',
 		};
@@ -98,19 +104,16 @@ function runWithRuntime(
 
 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 - TypeScript ONLY (source of truth)
 	// Python files are deprecated and should be removed
-	const runtimes: Array<{ name: string; cmd: string; ext: string }> = [
-		{ name: 'bun', cmd: 'bun', ext: '.ts' },
-		{ name: 'npx-tsx', cmd: 'npx tsx', ext: '.ts' },
+	const runtimes: Array<{ name: string; cmd: string }> = [
+		{ name: 'bun', cmd: 'bun' },
+		{ name: 'npx-tsx', cmd: 'npx tsx' },
 	];
 
 	for (const runtime of runtimes) {
-		const hookPath = runtime.ext === '.ts' ? tsPath : pyPath;
-
-		if (!existsSync(hookPath)) {
+		if (!existsSync(tsPath)) {
 			continue;
 		}
 
@@ -118,17 +121,36 @@ async function runHook(hookName: string, stdinData: string): Promise<void> {
 			continue;
 		}
 
-		const result = runWithRuntime(runtime.cmd, [hookPath], stdinData);
+		const result = runWithRuntime(runtime.cmd, [tsPath], stdinData);
+
+		// Handle exit codes according to Claude Code hook specification:
+		// - Exit code 0: Success (stdout in transcript)
+		// - Exit code 2: Blocking error (stderr feeds back to Claude)
+		// - Other: Non-blocking error
 
-		if (result.success || !result.error?.includes('not found')) {
-			// Runtime worked (success or runtime-specific failure)
+		if (result.exitCode === 0) {
+			// Success - output stdout
+			process.stdout.write(result.output);
+			process.exit(0);
+		} else if (result.exitCode === 2) {
+			// Blocking error - stderr goes to Claude for action
+			if (result.error) {
+				process.stderr.write(result.error);
+			}
+			process.exit(2);
+		} else {
+			// Non-blocking error or runtime not found
+			if (result.error?.includes('not found')) {
+				// Runtime not available, try next
+				continue;
+			}
+			// Hook failed but not blocking
 			process.stdout.write(result.output);
-			if (result.error && !result.success) {
+			if (result.error) {
 				process.stderr.write(result.error);
 			}
-			process.exit(result.success ? 0 : 1);
+			process.exit(result.exitCode);
 		}
-		// Runtime not available, try next
 	}
 
 	// No runtime available - return safe default

package/template/.claude/hooks/stop-validator.ts

@@ -936,6 +936,64 @@ interface HookResult {
 	reason: string;
 }
 
+/**
+ * Maps error types to the subagent that should be launched to fix them.
+ */
+const ERROR_TO_SUBAGENT: Record<string, { agent: string; prompt: string }> = {
+	FEATURE_BRANCH_NOT_MERGED: {
+		agent: 'commit-manager',
+		prompt: 'Complete the git workflow: commit all changes, merge to main, sync with remote',
+	},
+	NOT_ON_MAIN_BRANCH: {
+		agent: 'commit-manager',
+		prompt: 'Merge current branch to main and checkout main',
+	},
+	DIRECT_MAIN_COMMIT_FORBIDDEN: {
+		agent: 'branch-manager',
+		prompt: 'Create a feature branch from the current changes on main',
+	},
+	GIT_TREE_NOT_CLEAN: {
+		agent: 'commit-manager',
+		prompt: 'Commit all pending changes with appropriate conventional commit message',
+	},
+	CLAUDE_MD_MISSING: {
+		agent: 'documenter',
+		prompt: 'Create CLAUDE.md with required sections: Last Change, 30s Overview, Stack, Architecture',
+	},
+	CLAUDE_MD_SIZE_EXCEEDED: {
+		agent: 'claude-md-compactor',
+		prompt: 'Compact CLAUDE.md to under 40k characters while preserving critical project knowledge',
+	},
+	CLAUDE_MD_TEMPLATE_MERGE_NEEDED: {
+		agent: 'documenter',
+		prompt: 'Merge existing CLAUDE.md with template in .claude/CLAUDE.template.md, then delete template',
+	},
+	CLAUDE_MD_MISSING_SECTIONS: {
+		agent: 'documenter',
+		prompt: 'Add missing required sections to CLAUDE.md',
+	},
+	CLAUDE_MD_LAST_CHANGE_EMPTY: {
+		agent: 'documenter',
+		prompt: 'Update the Last Change section in CLAUDE.md with current session info',
+	},
+	CLAUDE_MD_STACKED_CHANGES: {
+		agent: 'documenter',
+		prompt: 'Remove stacked Last Change sections in CLAUDE.md, keep only the latest',
+	},
+	CLAUDE_MD_NOT_UPDATED: {
+		agent: 'documenter',
+		prompt: 'Update CLAUDE.md Last Change section with current session summary',
+	},
+	SOURCE_FILES_NOT_DOCUMENTED: {
+		agent: 'documenter',
+		prompt: 'Update documentation for all modified source files',
+	},
+	DOMAIN_DOCUMENTATION_INCOMPLETE: {
+		agent: 'documenter',
+		prompt: 'Update domain documentation for all modified files in .claude/skills/codebase-knowledge/domains/',
+	},
+};
+
 async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
 	return new Promise((resolve) => {
 		const timeout = setTimeout(() => {
@@ -964,21 +1022,75 @@ async function readStdinWithTimeout(timeoutMs: number): Promise<string> {
 	});
 }
 
+/**
+ * Run validations in priority order and return the FIRST error found.
+ * This ensures Claude fixes one issue at a time in the correct sequence.
+ */
+function runValidationsInOrder(
+	currentBranch: string,
+	modifiedFiles: string[],
+	sourceFiles: string[],
+	isMainBranch: boolean,
+	isCleanTree: boolean
+): ValidationError | null {
+	// PRIORITY ORDER - most critical first, one at a time
+	// Each validation returns early on first error
+
+	// 1. Branch validation - can't complete on feature branch
+	const branchError = validateBranch(currentBranch, modifiedFiles);
+	if (branchError) return branchError;
+
+	// 2. Git tree - must be clean (only check if on main)
+	if (isMainBranch) {
+		const treeError = validateGitTree(modifiedFiles);
+		if (treeError) return treeError;
+	}
+
+	// 3. CLAUDE.md must exist
+	const claudeMdExistsError = validateClaudeMdExists();
+	if (claudeMdExistsError) return claudeMdExistsError;
+
+	// 4. Check if template merge is needed
+	const templateMergeError = validateClaudeMdTemplateMerge();
+	if (templateMergeError) return templateMergeError;
+
+	// 5. CLAUDE.md size - must be under 40k
+	const sizeError = validateClaudeMdSize();
+	if (sizeError) return sizeError;
+
+	// 6. CLAUDE.md structure - must have required sections
+	const structureError = validateClaudeMdStructure();
+	if (structureError) return structureError;
+
+	// 7. Last Change must not be stacked
+	const lastChangeError = validateClaudeMdLastChange();
+	if (lastChangeError) return lastChangeError;
+
+	// 8. CLAUDE.md must be updated if files changed
+	const updatedError = validateClaudeMdUpdated(modifiedFiles);
+	if (updatedError) return updatedError;
+
+	// 9. Source files must be documented
+	const docError = validateDocumentation(sourceFiles);
+	if (docError) return docError;
+
+	// 10. Domain documentation must be complete
+	const domainDocError = validateDomainDocumentation(modifiedFiles);
+	if (domainDocError) return domainDocError;
+
+	return null; // All validations passed
+}
+
 async function main(): Promise<void> {
-	// Debug logging - always output to stderr for visibility
-	console.error('[stop-validator] ========================================');
+	// Debug logging - writes to stderr (visible in claude debug mode)
 	console.error('[stop-validator] Starting validation...');
-	console.error(`[stop-validator] CWD: ${process.cwd()}`);
 	console.error(`[stop-validator] PROJECT_DIR: ${PROJECT_DIR}`);
-	console.error(`[stop-validator] CLAUDE_MD exists: ${existsSync(CLAUDE_MD_PATH)}`);
 
 	let hookInput: HookInput = {};
 	try {
 		const stdin = await readStdinWithTimeout(1000);
-		console.error(`[stop-validator] stdin received: ${stdin.length} chars`);
 		if (stdin && stdin.trim()) {
 			hookInput = JSON.parse(stdin);
-			console.error(`[stop-validator] Parsed input keys: ${Object.keys(hookInput).join(', ') || 'none'}`);
 		}
 	} catch {
 		hookInput = {};
@@ -1001,101 +1113,54 @@ async function main(): Promise<void> {
 	const isMainBranch = currentBranch === 'main' || currentBranch === 'master';
 	const isCleanTree = modifiedFiles.length === 0;
 
-	// Run all validations
-	console.error('[stop-validator] Running validations...');
-	console.error(`[stop-validator] Branch: ${currentBranch}, isMain: ${isMainBranch}`);
-	console.error(`[stop-validator] Modified files: ${modifiedFiles.length}`);
-	console.error(`[stop-validator] Source files: ${sourceFiles.length}`);
-
-	const errors: ValidationError[] = [];
-
-	// Validation order matters - most critical first
-	const branchError = validateBranch(currentBranch, modifiedFiles);
-	if (branchError) errors.push(branchError);
+	console.error(`[stop-validator] Branch: ${currentBranch}, Modified: ${modifiedFiles.length}`);
 
-	// Only check these if we're close to completion (on main or clean tree)
-	if (isMainBranch || isCleanTree) {
-		const treeError = validateGitTree(modifiedFiles);
-		if (treeError) errors.push(treeError);
-	}
-
-	const claudeMdExistsError = validateClaudeMdExists();
-	if (claudeMdExistsError) errors.push(claudeMdExistsError);
-
-	if (!claudeMdExistsError) {
-		// Check if there's a template pending merge (from start-vibing install)
-		const templateMergeError = validateClaudeMdTemplateMerge();
-		if (templateMergeError) errors.push(templateMergeError);
-
-		const sizeError = validateClaudeMdSize();
-		if (sizeError) errors.push(sizeError);
-
-		const structureError = validateClaudeMdStructure();
-		if (structureError) errors.push(structureError);
-
-		const lastChangeError = validateClaudeMdLastChange();
-		if (lastChangeError) errors.push(lastChangeError);
-
-		const updatedError = validateClaudeMdUpdated(modifiedFiles);
-		if (updatedError) errors.push(updatedError);
-	}
-
-	const docError = validateDocumentation(sourceFiles);
-	if (docError) errors.push(docError);
-
-	const domainDocError = validateDomainDocumentation(modifiedFiles);
-	if (domainDocError) errors.push(domainDocError);
+	// Run validations in order - get FIRST error only
+	const error = runValidationsInOrder(
+		currentBranch,
+		modifiedFiles,
+		sourceFiles,
+		isMainBranch,
+		isCleanTree
+	);
 
 	// ============================================================================
-	// OUTPUT RESULTS
+	// OUTPUT RESULTS - ONE ERROR AT A TIME
 	// ============================================================================
 
-	console.error(`[stop-validator] Validation complete. Errors found: ${errors.length}`);
-	if (errors.length > 0) {
-		console.error(`[stop-validator] Error types: ${errors.map((e) => e.type).join(', ')}`);
-	}
+	if (error) {
+		const subagentInfo = ERROR_TO_SUBAGENT[error.type] || {
+			agent: 'general-purpose',
+			prompt: 'Fix the validation error',
+		};
 
-	if (errors.length > 0) {
-		let output = `
+		const output = `
 ################################################################################
-#                    STOP VALIDATOR - TASK COMPLETION BLOCKED                  #
+#                    STOP VALIDATOR - BLOCKED                                  #
 ################################################################################
 
-${errors.length} validation(s) failed. You MUST fix these before the task can complete.
+ERROR: ${error.type}
 
-`;
+${error.message}
+
+${error.action}
 
-		for (let i = 0; i < errors.length; i++) {
-			const err = errors[i];
-			output += `
 --------------------------------------------------------------------------------
-ERROR ${i + 1}/${errors.length}: ${err.type}
+REQUIRED ACTION: Launch the following subagent to fix this issue
 --------------------------------------------------------------------------------
 
-${err.message}
+  Task(subagent_type="${subagentInfo.agent}", prompt="${subagentInfo.prompt}")
 
-${err.action}
-`;
-		}
+After fixing this issue, the stop hook will run again to check for remaining issues.
 
-		output += `
-################################################################################
-#               FIX ALL ERRORS ABOVE BEFORE TASK CAN COMPLETE                  #
 ################################################################################
-
-SYNTHESIS REMINDER:
-Before completing, ask yourself:
-- Did the user mention any preferences I should remember?
-- Did I learn any patterns that should be documented?
-- Were there any corrections I should add as rules?
-
-Update CLAUDE.md with any learnings from this session.
 `;
 
-		// IMPORTANT: For blocking, output to STDERR and exit with code 2
-		const result: HookResult = { decision: 'block', reason: output.trim() };
-		console.error(JSON.stringify(result));
-		process.exit(2); // Exit code 2 = block and show to Claude
+		// Write block reason to stderr (Claude sees this)
+		process.stderr.write(output);
+
+		// Exit with code 2 = blocking error, stderr goes to Claude
+		process.exit(2);
 	}
 
 	// All validations passed

package/template/.claude/skills/hook-development/SKILL.md

@@ -0,0 +1,320 @@
+# Hook Development for Claude Code
+
+> Event-driven automation scripts for Claude Code. Hooks execute in response to system events, enabling validation, policy enforcement, context loading, and workflow integration.
+
+---
+
+## Hook Types
+
+### Prompt-Based Hooks (Recommended)
+
+Use LLM-driven decision making for context-aware validation. Natural language reasoning for complex decisions.
+
+**Supported Events:** Stop, SubagentStop, UserPromptSubmit, PreToolUse
+
+### Command Hooks
+
+Execute bash/shell scripts for deterministic operations. Fast, predictable, no LLM calls.
+
+**Best For:** File system operations, external tool integration, quick validations
+
+---
+
+## Hook Events
+
+| Event | Purpose | Use Case |
+|-------|---------|----------|
+| **PreToolUse** | Validate/modify tool calls before execution | Block dangerous operations, inject context |
+| **PostToolUse** | React to tool completion | Log results, trigger follow-up actions |
+| **Stop** | Validate task completeness before agent halts | Enforce branch rules, documentation checks |
+| **SubagentStop** | Validate subagent completion | Quality gates for agent outputs |
+| **UserPromptSubmit** | Process incoming prompts | Add context, block invalid requests |
+| **SessionStart** | Initialize session | Load project context, set environment |
+| **SessionEnd** | Cleanup on session close | Save state, cleanup temp files |
+| **PreCompact** | Before context compaction | Preserve critical information |
+| **Notification** | React to Claude notifications | Custom notification handling |
+
+---
+
+## Configuration
+
+### Plugin Format (hooks/hooks.json)
+
+```json
+{
+  "description": "Optional explanation",
+  "hooks": {
+    "PreToolUse": [...],
+    "Stop": [...]
+  }
+}
+```
+
+### Settings Format (.claude/settings.json)
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx tsx .claude/hooks/stop-validator.ts",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Input/Output
+
+### Standard Input (JSON via stdin)
+
+All hooks receive:
+
+```json
+{
+  "session_id": "string",
+  "transcript_path": "string",
+  "cwd": "string",
+  "permission_mode": "string",
+  "hook_event_name": "string"
+}
+```
+
+Event-specific fields:
+- **PreToolUse/PostToolUse**: `tool_name`, `tool_input`
+- **UserPromptSubmit**: `user_prompt`
+- **Stop**: Current state info
+
+### Standard Output
+
+```json
+{
+  "continue": true,
+  "suppressOutput": false,
+  "systemMessage": "Optional context for Claude"
+}
+```
+
+### Exit Codes
+
+| Code | Meaning | Behavior |
+|------|---------|----------|
+| 0 | Success | stdout appears in transcript |
+| 2 | Blocking error | stderr feeds back to Claude for action |
+| Other | Non-blocking error | Hook failed, but doesn't block |
+
+---
+
+## Environment Variables
+
+Available in all command hooks:
+
+| Variable | Description |
+|----------|-------------|
+| `$CLAUDE_PROJECT_DIR` | Project root directory |
+| `$CLAUDE_PLUGIN_ROOT` | Plugin directory (for portability) |
+| `$CLAUDE_ENV_FILE` | SessionStart persistence file |
+| `$CLAUDE_CODE_REMOTE` | Remote execution flag |
+
+---
+
+## Matcher Patterns
+
+Matchers determine which tools trigger hooks:
+
+| Pattern | Example | Matches |
+|---------|---------|---------|
+| Exact | `"Write"` | Only Write tool |
+| Multiple | `"Read\|Write\|Edit"` | Any of these tools |
+| Wildcard | `"*"` | All tools |
+| Regex | `"mcp__.*__delete.*"` | MCP delete operations |
+
+---
+
+## Best Practices
+
+### Security
+
+```typescript
+// Always validate paths
+if (filePath.includes('..') || filePath.startsWith('/etc')) {
+  throw new Error('Path traversal blocked');
+}
+
+// Always quote variables in bash
+const cmd = `cat "${filePath}"`; // Correct
+const cmd = `cat ${filePath}`;   // WRONG - injection risk
+```
+
+### Performance
+
+- All matching hooks execute **in parallel**
+- Use command hooks for quick, deterministic checks
+- Use prompt hooks for complex reasoning
+- Default timeout: 60s (command), 30s (prompt)
+
+### Error Handling
+
+```typescript
+// For blocking errors - use exit code 2
+if (validationFailed) {
+  process.stderr.write(errorMessage);
+  process.exit(2); // Blocks and shows to Claude
+}
+
+// For non-blocking errors
+if (warningCondition) {
+  console.error('Warning:', message);
+  process.exit(1); // Logs but doesn't block
+}
+```
+
+---
+
+## Stop Hook Template
+
+```typescript
+#!/usr/bin/env node
+import { execSync } from 'child_process';
+
+interface HookResult {
+  decision: 'approve' | 'block';
+  reason: string;
+}
+
+async function main(): Promise<void> {
+  // Read stdin
+  const stdin = await readStdin();
+  const input = JSON.parse(stdin);
+
+  // Validation logic
+  const error = validateSomething();
+
+  if (error) {
+    // Block with actionable message
+    const message = `
+ERROR: ${error.type}
+
+${error.message}
+
+REQUIRED ACTION:
+  Task(subagent_type="${error.agent}", prompt="${error.prompt}")
+`;
+    process.stderr.write(message);
+    process.exit(2); // Blocking
+  }
+
+  // Success
+  const result: HookResult = { decision: 'approve', reason: 'All checks passed' };
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}
+
+main();
+```
+
+---
+
+## PreToolUse Hook Template
+
+```typescript
+#!/usr/bin/env node
+interface PreToolUseInput {
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+async function main(): Promise<void> {
+  const input: PreToolUseInput = JSON.parse(await readStdin());
+
+  // Check if this is a dangerous operation
+  if (input.tool_name === 'Write' && input.tool_input.file_path?.includes('.env')) {
+    process.stderr.write('BLOCKED: Cannot write to .env files');
+    process.exit(2);
+  }
+
+  // Allow operation
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+```
+
+---
+
+## Debugging
+
+**Important:** Hooks load at session startup. Config changes require restarting Claude Code.
+
+```bash
+# Debug hook execution
+claude --debug
+
+# View hook registration
+claude --debug 2>&1 | grep -i hook
+```
+
+---
+
+## Implementation Checklist
+
+1. [ ] Identify target events (Stop, PreToolUse, etc.)
+2. [ ] Choose hook type (prompt-based vs command)
+3. [ ] Write configuration in settings.json
+4. [ ] Create hook script with proper exit codes
+5. [ ] Test with `claude --debug`
+6. [ ] Document in project README
+
+---
+
+## Common Patterns
+
+### Validation Gate (Stop Hook)
+
+Check conditions before task completion:
+
+```typescript
+const validations = [
+  checkBranch(),      // Must be on main
+  checkGitClean(),    // No uncommitted changes
+  checkDocumentation() // All files documented
+];
+
+const firstError = validations.find(v => v !== null);
+if (firstError) {
+  process.stderr.write(formatError(firstError));
+  process.exit(2);
+}
+```
+
+### Context Injection (UserPromptSubmit)
+
+Add context to user prompts:
+
+```typescript
+const context = loadProjectContext();
+const result = {
+  continue: true,
+  systemMessage: `Project context: ${context}`
+};
+console.log(JSON.stringify(result));
+```
+
+### Tool Blocking (PreToolUse)
+
+Block dangerous operations:
+
+```typescript
+const BLOCKED_PATHS = ['.env', 'credentials', 'secrets'];
+if (BLOCKED_PATHS.some(p => input.tool_input.path?.includes(p))) {
+  process.stderr.write('Blocked: Cannot access sensitive files');
+  process.exit(2);
+}
+```