claude-toolkit 0.9.0 → 0.11.0

package/src/generator.ts

@@ -1,7 +1,7 @@
-import { copyFile as fsCopyFile } from "node:fs/promises";
+import { copyFile as fsCopyFile, readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { ClaudeToolkitConfig, ResolvedConfig, StackPack } from "./types.js";
-import { copyDir, exists, readJson, writeFileEnsureDir } from "./utils.js";
+import { copyDir, exists, readJson, removePath, writeFileEnsureDir } from "./utils.js";
 
 const TOOLKIT_ROOT = resolve(import.meta.dirname, "..");
 
@@ -48,11 +48,56 @@ async function resolveConfig(config: ClaudeToolkitConfig): Promise<ResolvedConfi
 	return { config, skills, directoryMappings: allMappings, hooks, stacks };
 }
 
+/** Remove only `ct-` prefixed entries in a directory (preserves user-authored files). */
+async function removeCtPrefixed(dir: string): Promise<void> {
+	if (!exists(dir)) return;
+	const entries = await readdir(dir);
+	await Promise.all(
+		entries.filter((e) => e.startsWith("ct-")).map((e) => removePath(join(dir, e))),
+	);
+}
+
+/**
+ * Remove toolkit-generated artifacts from .claude/ before a rebuild, so a stack
+ * removed from the config doesn't leave an orphaned skill behind.
+ *
+ * Scoped to what the toolkit owns: `ct-` prefixed skills/agents, the generated
+ * skills index, the `ct/` command namespace, and the toolkit's own hook files.
+ * `.claude/skills`, `/agents`, and `/hooks` are shared Claude Code namespaces, so
+ * any user-authored files there — and the user files at the .claude root
+ * (settings.local.json, user-team-info.json, tasks/) — are preserved.
+ * (settings.json and .gitignore are single generated files, overwritten by generate.)
+ */
+async function removeGenerated(claudeDir: string): Promise<void> {
+	const coreHooks = join(TOOLKIT_ROOT, "core", "hooks");
+	const hookFiles = exists(coreHooks) ? await readdir(coreHooks) : [];
+	await Promise.all([
+		removeCtPrefixed(join(claudeDir, "skills")),
+		removeCtPrefixed(join(claudeDir, "agents")),
+		removePath(join(claudeDir, "skills", "README.md")),
+		removePath(join(claudeDir, "commands", "ct")),
+		// Toolkit hook files (copied from core/hooks) + the generated skill-rules.json.
+		...hookFiles.map((f) => removePath(join(claudeDir, "hooks", f))),
+		removePath(join(claudeDir, "hooks", "skill-rules.json")),
+		// Stale files from prior installs: skill-eval.js was renamed to .cjs, and the
+		// skill-eval.sh wrapper was dropped in favour of exec-form node registration.
+		removePath(join(claudeDir, "hooks", "skill-eval.js")),
+		removePath(join(claudeDir, "hooks", "skill-eval.sh")),
+	]);
+}
+
 /** Generate the .claude/ directory from resolved config */
-export async function generate(projectDir: string, config: ClaudeToolkitConfig): Promise<void> {
+export async function generate(
+	projectDir: string,
+	config: ClaudeToolkitConfig,
+	options: { quiet?: boolean; scaffold?: boolean } = {},
+): Promise<void> {
 	const resolved = await resolveConfig(config);
 	const claudeDir = join(projectDir, ".claude");
 
+	// 0. Clean previously-generated output so removed stacks don't leave stale skills.
+	await removeGenerated(claudeDir);
+
 	// 1. Copy core hooks
 	await copyDir(join(TOOLKIT_ROOT, "core", "hooks"), join(claudeDir, "hooks"));
 
@@ -73,6 +118,16 @@ export async function generate(projectDir: string, config: ClaudeToolkitConfig):
 		}
 	}
 
+	// 5b. Copy stack-specific commands into the ct/ namespace. Only installs when
+	//     the owning stack is active; removeGenerated() already deletes the whole
+	//     .claude/commands/ct dir each rebuild, so a removed stack leaves no orphan.
+	for (const stackName of config.stacks) {
+		const stackCommandsDir = join(TOOLKIT_ROOT, "stacks", stackName, "commands");
+		if (exists(stackCommandsDir)) {
+			await copyDir(stackCommandsDir, join(claudeDir, "commands", "ct"));
+		}
+	}
+
 	// 6. Generate skill-rules.json
 	await generateSkillRules(claudeDir, resolved);
 
@@ -92,18 +147,30 @@ export async function generate(projectDir: string, config: ClaudeToolkitConfig):
 			"# Task-specific context",
 			"tasks/",
 			"",
+			"# Toolkit regeneration marker",
+			".toolkit-version",
+			"",
 		].join("\n"),
 	);
 
-	// 9. Scaffold base configs
-	await scaffoldConfigs(projectDir, resolved);
+	// 9. Scaffold base configs into the project root (committed files). Skipped for
+	//    automatic/postinstall regeneration so an install never writes committed files.
+	if (options.scaffold !== false) {
+		await scaffoldConfigs(projectDir, resolved, options.quiet);
+	}
 
 	// 10. Generate skills README
 	await generateSkillsReadme(claudeDir, resolved);
 
-	console.log(
-		`Generated .claude/ with ${resolved.stacks.length} stack(s) and ${resolved.skills.length} core skills`,
-	);
+	// Record the toolkit version that produced this output — drives auto-regen on update.
+	const { version } = await readJson<{ version: string }>(join(TOOLKIT_ROOT, "package.json"));
+	await writeFileEnsureDir(join(claudeDir, ".toolkit-version"), `${version}\n`);
+
+	if (!options.quiet) {
+		console.log(
+			`Generated .claude/ with ${resolved.stacks.length} stack(s) and ${resolved.skills.length} core skills`,
+		);
+	}
 }
 
 /** Generate skill-rules.json from resolved config */
@@ -239,7 +306,8 @@ async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Pr
 					hooks: [
 						{
 							type: "command",
-							command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/skill-eval.sh',
+							// biome-ignore lint/suspicious/noTemplateCurlyInString: Claude Code substitutes ${CLAUDE_PROJECT_DIR} at hook-run time; this must be a literal placeholder string.
+							command: 'node "${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-eval.cjs"',
 							timeout: 5,
 						},
 					],
@@ -271,7 +339,11 @@ async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Pr
 }
 
 /** Scaffold base config files (biome.json, tsconfig.json) into the project */
-async function scaffoldConfigs(projectDir: string, resolved: ResolvedConfig): Promise<void> {
+async function scaffoldConfigs(
+	projectDir: string,
+	resolved: ResolvedConfig,
+	quiet = false,
+): Promise<void> {
 	if (resolved.config.scaffoldConfigs === false) return;
 
 	const configsDir = join(TOOLKIT_ROOT, "templates", "configs");
@@ -283,10 +355,10 @@ async function scaffoldConfigs(projectDir: string, resolved: ResolvedConfig): Pr
 	for (const { src, dest } of configs) {
 		const destPath = join(projectDir, dest);
 		if (exists(destPath)) {
-			console.log(`  Skipped ${dest} (already exists)`);
+			if (!quiet) console.log(`  Skipped ${dest} (already exists)`);
 		} else {
 			await fsCopyFile(join(configsDir, src), destPath);
-			console.log(`  Scaffolded ${dest}`);
+			if (!quiet) console.log(`  Scaffolded ${dest}`);
 		}
 	}
 }

package/src/utils.ts

@@ -1,11 +1,5 @@
 import { existsSync } from "node:fs";
-import {
-	copyFile,
-	mkdir,
-	readdir,
-	readFile,
-	writeFile,
-} from "node:fs/promises";
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 /** Recursively copy a directory */
@@ -24,11 +18,13 @@ export async function copyDir(src: string, dest: string): Promise<void> {
 	}
 }
 
+/** Remove a file or directory recursively. No-op if the path doesn't exist. */
+export async function removePath(path: string): Promise<void> {
+	await rm(path, { recursive: true, force: true });
+}
+
 /** Write a file, creating parent directories as needed */
-export async function writeFileEnsureDir(
-	filePath: string,
-	content: string,
-): Promise<void> {
+export async function writeFileEnsureDir(filePath: string, content: string): Promise<void> {
 	await mkdir(dirname(filePath), { recursive: true });
 	await writeFile(filePath, content, "utf-8");
 }
@@ -45,9 +41,6 @@ export function exists(filePath: string): boolean {
 }
 
 /** Simple template replacement: {{key}} → value */
-export function renderTemplate(
-	template: string,
-	vars: Record<string, string>,
-): string {
+export function renderTemplate(template: string, vars: Record<string, string>): string {
 	return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? "");
 }

package/{core/commands/ct → stacks/protobuf/commands}/proto-check.md

@@ -1,7 +1,16 @@
 ---
-description: "Validate protobuf definitions and check for breaking changes"
+description: Validate protobuf definitions and check for breaking changes
 allowed-tools:
-  - Bash
+  - Bash(buf:*)
+  - Bash(protoc:*)
+  - Bash(npm run:*)
+  - Bash(pnpm:*)
+  - Bash(bun run:*)
+  - Bash(yarn:*)
+  - Bash(tsc:*)
+  - Bash(cargo build:*)
+  - Bash(cargo check:*)
+  - Bash(go build:*)
   - Read
   - Glob
   - Grep

package/templates/skill-rules.base.json

@@ -40,8 +40,7 @@
 					"(?:red.green.refactor|tdd)"
 				],
 				"contentPatterns": ["describe\\(", "it\\(", "expect\\(", "vi\\.mock", "jest\\.mock"]
-			},
-			"excludePatterns": ["e2e", "end-to-end"]
+			}
 		},
 		"ct-typescript-conventions": {
 			"description": "TypeScript strict mode and conventions",
@@ -66,33 +65,6 @@
 				],
 				"contextPatterns": ["before claiming", "make sure", "double check"]
 			}
-		},
-		"ct-github-actions": {
-			"description": "GitHub Actions CI/CD workflow patterns",
-			"priority": 6,
-			"triggers": {
-				"keywords": ["github action", "github workflow", "workflow", "ci/cd", "cicd", "pipeline"],
-				"keywordPatterns": ["github.action", "ci/?cd", "\\bworkflow\\b"],
-				"pathPatterns": [".github/workflows/**", ".github/**/*.yml"],
-				"intentPatterns": [
-					"(?:create|add|update).*(?:workflow|action|pipeline)",
-					"(?:ci|cd).*(?:pipeline|workflow)"
-				],
-				"contentPatterns": ["runs-on:", "uses:", "steps:"]
-			}
-		},
-		"ct-code-review": {
-			"description": "Handle code review feedback",
-			"priority": 4,
-			"triggers": {
-				"keywords": ["code review", "pr feedback", "review comment"],
-				"keywordPatterns": ["code.review", "pr.feedback", "review.comment"],
-				"intentPatterns": [
-					"(?:respond|address|handle).*(?:review|feedback|comment)",
-					"(?:reviewer).*(?:said|suggested|asked)"
-				],
-				"contextPatterns": ["from the reviewer", "in the pr", "review feedback"]
-			}
 		}
 	}
 }

package/core/hooks/skill-eval.sh

@@ -1,35 +0,0 @@
-#!/bin/bash
-# Skill Evaluation Hook v2.0
-# Wrapper script that delegates to the Node.js evaluation engine
-#
-# This hook runs on UserPromptSubmit and analyzes the prompt for:
-# - Keywords and patterns indicating skill relevance
-# - File paths mentioned in the prompt
-# - Intent patterns (what the user wants to do)
-# - Directory mappings (what directories map to which skills)
-#
-# Configuration is in skill-rules.json
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-NODE_SCRIPT="$SCRIPT_DIR/skill-eval.js"
-
-# Check if Node.js is available (bun also works)
-if command -v bun &>/dev/null; then
-  RUNTIME="bun"
-elif command -v node &>/dev/null; then
-  RUNTIME="node"
-else
-  # Fallback: exit silently if no runtime found
-  exit 0
-fi
-
-# Check if the Node script exists
-if [[ ! -f "$NODE_SCRIPT" ]]; then
-  exit 0
-fi
-
-# Pipe stdin to the evaluation script (suppress stderr noise from shell init)
-cat | $RUNTIME "$NODE_SCRIPT" 2>/dev/null
-
-# Always exit 0 to allow the prompt through
-exit 0