start-vibing 2.0.20 → 2.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "start-vibing",
-	"version": "2.0.20",
+	"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

@@ -3,9 +3,13 @@
  * Universal Hook Runner
  *
  * Runs hooks with multiple runtime fallbacks:
- * 1. python3 (primary - user's preferred)
- * 2. python (fallback)
- * 3. npx tsx (TypeScript execution)
+ * 1. bun (primary - fastest TypeScript execution)
+ * 2. npx tsx (TypeScript fallback)
+ * 3. python3 (Python fallback)
+ * 4. python (Python fallback)
+ *
+ * IMPORTANT: TypeScript files are the source of truth.
+ * Python files are only for environments without Node.js/Bun.
  *
  * Usage: npx tsx run-hook.ts <hook-name>
  * The hook-name should be without extension (e.g., "stop-validator")
@@ -63,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,
@@ -79,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',
 		};
@@ -94,20 +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 - 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' },
+
+	// Runtime detection order - TypeScript ONLY (source of truth)
+	// Python files are deprecated and should be removed
+	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;
 		}
 
@@ -115,22 +121,41 @@ async function runHook(hookName: string, stdinData: string): Promise<void> {
 			continue;
 		}
 
-		const result = runWithRuntime(runtime.cmd, [hookPath], stdinData);
+		const result = runWithRuntime(runtime.cmd, [tsPath], stdinData);
 
-		if (result.success || !result.error?.includes('not found')) {
-			// Runtime worked (success or runtime-specific failure)
+		// 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.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
 	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');
+	console.error('[run-hook] Please install bun or Node.js (for npx tsx)');
 	const safeDefault = JSON.stringify({
 		decision: 'approve',
 		continue: true,

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