claude-toolkit 0.1.18 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.22 (2026-04-11)
+
+- feat: add stack auto-detection with drift reporting
+
+## 0.1.21 (2026-04-11)
+
+- docs: improve README intro and standardize formatting
+
+## 0.1.20 (2026-04-06)
+
+- docs: update storybook docs with Vitest 4 addon-vitest config
+
+## 0.1.19 (2026-04-06)
+
+- fix: update storybook addon-vitest config for Vitest 4 compatibility
+
 ## 0.1.18 (2026-04-05)
 
 - docs: update cross-references for vite, playwright, and storybook stacks

package/README.md

@@ -1,6 +1,12 @@
 # claude-toolkit
 
-Reusable Claude Code configuration toolkit with stack-specific connectors.
+**claude-toolkit is a toolbox that Claude Code picks up and uses on its own — no prompting required, saving tokens and ensuring consistent behavior across your team.**
+
+The toolkit auto-detects your tech stacks (SolidJS, Vite, Playwright, Cloudflare, etc.) and generates a `.claude/` directory that Claude Code automatically loads. Instead of every team member re-explaining project conventions, tooling, and patterns each session (burning tokens every time), Claude already knows — the knowledge is baked into the generated config. As your project evolves, the toolkit detects stack drift and suggests config updates to stay in sync.
+
+This means any developer on your team gets the same Claude behavior for a given project, regardless of how they prompt. The toolkit is project-specific but team-consistent: Claude follows the same debugging methodology, the same testing patterns, and the same code quality standards for everyone.
+
+Whether you're starting a new project from scratch or consolidating an existing one, the toolkit gives Claude immediate context about your stack and conventions — so it produces code that fits from day one, or aligns with what's already in place.
 
 ## Quick Start
 
@@ -19,45 +25,73 @@ bunx claude-toolkit init
 3. Claude Code picks up the generated config automatically
 
 ```ts
-import { defineConfig } from 'claude-toolkit'
+import { defineConfig } from "claude-toolkit";
 
 export default defineConfig({
-  stacks: ['solidjs', 'rust-wasm', 'cloudflare', 'protobuf'],
-  packageManager: 'bun',
+  stacks: ["solidjs", "rust-wasm", "cloudflare", "protobuf"],
+  packageManager: "bun",
   hooks: {
-    formatter: 'bun run prettier --write',
-    testRunner: 'bun run vitest run',
-    typeCheck: 'bun run tsc --noEmit',
-    extraChecks: ['cargo check --target wasm32-unknown-unknown'],
+    formatter: "bun run prettier --write",
+    testRunner: "bun run vitest run",
+    typeCheck: "bun run tsc --noEmit",
+    extraChecks: ["cargo check --target wasm32-unknown-unknown"],
   },
   git: {
-    branchPrefix: 'wq',
-    protectedBranches: ['main'],
+    branchPrefix: "feat",
+    protectedBranches: ["main"],
   },
-})
+});
 ```
 
 ## CLI Commands
 
-| Command | Description |
-|---------|-------------|
-| `bunx claude-toolkit init` | Scaffold config file and generate `.claude/` |
+| Command                    | Description                                              |
+| -------------------------- | -------------------------------------------------------- |
+| `bunx claude-toolkit init` | Scaffold config file and generate `.claude/`             |
 | `bunx claude-toolkit sync` | Regenerate `.claude/` from config (after toolkit update) |
-| `bunx claude-toolkit help` | Show available commands |
+| `bunx claude-toolkit help` | Show available commands                                  |
+
+## Stack Auto-Detection
+
+The toolkit automatically detects which stacks your project uses by scanning `package.json` dependencies, config files, and project structure.
+
+**On `init`** (new project), detected stacks are pre-filled in the generated config:
+
+```text
+Detected stacks:
+  solidjs    — found solid-js in dependencies
+  vite       — found vite.config.ts
+  cloudflare — found wrangler.toml
+
+Created claude-toolkit.config.ts
+```
+
+**On `sync`** (existing config), the toolkit compares your configured stacks against what it detects and reports any drift:
+
+```text
+Stack drift detected:
+  + playwright — found @playwright/test in dependencies (not in config)
+  - rust-wasm  — in config but not detected in project
+
+Suggested update in claude-toolkit.config.ts:
+  stacks: ["solidjs", "vite", "cloudflare", "playwright"]
+```
+
+This keeps your config aligned as your project evolves — stacks you add or remove are surfaced automatically. The suggestion is informational; your config is not modified unless you update it yourself.
 
 ## Available Stacks
 
-| Stack | Skills Added |
-|-------|-------------|
-| `solidjs` | SolidJS reactivity, signals, components |
-| `vite` | Vite build config, plugins, Vitest testing, coverage, browser mode |
-| `vanilla-extract` | Type-safe CSS, sprinkles, recipes, themes |
-| `rust-wasm` | Rust WASM for Cloudflare Workers |
-| `protobuf` | Protocol Buffers, code generation, contracts |
-| `cloudflare` | D1 database, KV cache, Wrangler |
-| `i18n-typesafe` | typesafe-i18n internationalization |
-| `playwright` | Playwright E2E testing, Page Objects, fixtures, CI/CD |
-| `storybook` | Storybook interaction testing, CSF 3, visual regression |
+| Stack             | Skills Added                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| `solidjs`         | SolidJS reactivity, signals, components                            |
+| `vite`            | Vite build config, plugins, Vitest testing, coverage, browser mode |
+| `vanilla-extract` | Type-safe CSS, sprinkles, recipes, themes                          |
+| `rust-wasm`       | Rust WASM for Cloudflare Workers                                   |
+| `protobuf`        | Protocol Buffers, code generation, contracts                       |
+| `cloudflare`      | D1 database, KV cache, Wrangler                                    |
+| `i18n-typesafe`   | typesafe-i18n internationalization                                 |
+| `playwright`      | Playwright E2E testing, Page Objects, fixtures, CI/CD              |
+| `storybook`       | Storybook interaction testing, CSF 3, visual regression            |
 
 ## Core Features (always included)
 

package/bin/cli.ts

@@ -11,6 +11,7 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { detectStacks } from "../src/detect.js";
 import { generate } from "../src/generator.js";
 import type { ClaudeToolkitConfig } from "../src/types.js";
 
@@ -19,9 +20,7 @@ const CONFIG_FILENAME = "claude-toolkit.config.ts";
 async function loadConfig(projectDir: string): Promise<ClaudeToolkitConfig> {
 	const configPath = join(projectDir, CONFIG_FILENAME);
 	if (!existsSync(configPath)) {
-		throw new Error(
-			`Config not found: ${configPath}\nRun "claude-toolkit init" first.`,
-		);
+		throw new Error(`Config not found: ${configPath}\nRun "claude-toolkit init" first.`);
 	}
 	const module = await import(configPath);
 	return module.default as ClaudeToolkitConfig;
@@ -36,23 +35,37 @@ async function init(projectDir: string): Promise<void> {
 		return sync(projectDir);
 	}
 
-	// Copy starter config
-	const templatePath = join(
-		import.meta.dirname,
-		"..",
-		"templates",
-		"claude-toolkit.config.ts",
-	);
+	// Detect stacks
+	const detected = detectStacks(projectDir);
+	if (detected.length > 0) {
+		console.log("Detected stacks:");
+		const maxLen = Math.max(...detected.map((d) => d.name.length));
+		for (const d of detected) {
+			console.log(`  ${d.name.padEnd(maxLen)} — ${d.reason}`);
+		}
+	} else {
+		console.log(`No stacks detected. You can add them manually in ${CONFIG_FILENAME}`);
+	}
+
+	// Build stacks literal for config injection
+	const stacksLiteral =
+		detected.length > 0
+			? `stacks: [${detected.map((d) => `"${d.name}"`).join(", ")}]`
+			: "stacks: []";
+
+	// Copy starter config with detected stacks injected
+	const templatePath = join(import.meta.dirname, "..", "templates", "claude-toolkit.config.ts");
 	if (existsSync(templatePath)) {
 		const template = await readFile(templatePath, "utf-8");
-		await writeFile(configPath, template, "utf-8");
+		const configContent = template.replace("stacks: []", stacksLiteral);
+		await writeFile(configPath, configContent, "utf-8");
 		console.log(`Created ${CONFIG_FILENAME}`);
 	} else {
 		// Inline fallback
 		const defaultConfig = `import { defineConfig } from 'claude-toolkit'
 
 export default defineConfig({
-  stacks: [],
+  ${stacksLiteral},
   packageManager: 'bun',
   hooks: {
     formatter: 'bun run prettier --write',
@@ -75,6 +88,38 @@ export default defineConfig({
 
 async function sync(projectDir: string): Promise<void> {
 	const config = await loadConfig(projectDir);
+
+	// Compare detected stacks against config
+	const detected = detectStacks(projectDir);
+	const configuredNames = new Set(config.stacks);
+	const detectedNames = new Set(detected.map((d) => d.name));
+
+	const missing = detected.filter((d) => !configuredNames.has(d.name));
+	const stale = config.stacks.filter((s) => !detectedNames.has(s));
+
+	if (missing.length > 0 || stale.length > 0) {
+		console.log("\nStack drift detected:");
+		if (missing.length > 0) {
+			const maxLen = Math.max(...missing.map((d) => d.name.length));
+			for (const d of missing) {
+				console.log(`  + ${d.name.padEnd(maxLen)} — ${d.reason} (not in config)`);
+			}
+		}
+		if (stale.length > 0) {
+			for (const s of stale) {
+				console.log(`  - ${s} — in config but not detected in project`);
+			}
+		}
+		const suggested = [
+			...new Set([
+				...config.stacks.filter((s) => !stale.includes(s)),
+				...missing.map((d) => d.name),
+			]),
+		];
+		console.log(`\nSuggested update in ${CONFIG_FILENAME}:`);
+		console.log(`  stacks: [${suggested.map((s) => `"${s}"`).join(", ")}]\n`);
+	}
+
 	await generate(projectDir, config);
 	console.log("Sync complete.");
 }

package/docs/best-practices/testing/storybook-interaction.md

@@ -149,23 +149,33 @@ The **Vitest addon** (`@storybook/addon-vitest`) replaces the old `@storybook/te
 
 ### Configuration (Vitest 4.x)
 
-Use a separate test project:
+Required dependencies: `@storybook/addon-vitest`, `@vitest/browser`, `@vitest/browser-playwright`, `@vitest/coverage-v8`.
+
+Add as an inline project in your main Vite config using `test.projects`:
 
 ```typescript
-// vitest.config.storybook.ts
-import { defineConfig } from "vitest/config";
+// vite.config.ts
 import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
+import { playwright } from "@vitest/browser-playwright";
 
 export default defineConfig({
-  plugins: [storybookTest()],
+  plugins: [/* ...app plugins */],
   test: {
-    name: "storybook",
-    browser: {
-      enabled: true,
-      provider: "playwright",
-      instances: [{ browser: "chromium" }],
-    },
-    setupFiles: [".storybook/vitest.setup.ts"],
+    projects: [
+      {
+        extends: true,
+        test: { name: "unit", environment: "jsdom", setupFiles: ["./tests/setup.ts"] },
+      },
+      {
+        extends: true,
+        plugins: [storybookTest({ configDir: ".storybook" })],
+        test: {
+          name: "storybook",
+          browser: { enabled: true, headless: true, provider: playwright(), instances: [{ browser: "chromium" }] },
+          setupFiles: [".storybook/vitest.setup.ts"],
+        },
+      },
+    ],
   },
 });
 ```

package/docs/stacks/storybook-patterns.md

@@ -81,16 +81,33 @@ export const SubmitForm: Story = {
 
 Use `@storybook/addon-vitest` (replaces old test-runner). No running Storybook instance needed.
 
+Required dependencies: `@storybook/addon-vitest`, `@vitest/browser`, `@vitest/browser-playwright`, `@vitest/coverage-v8`.
+
+Add as an inline project in your main Vite config using `test.projects`:
+
 ```typescript
-// vitest.config.storybook.ts
+// vite.config.ts
 import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
+import { playwright } from "@vitest/browser-playwright";
 
 export default defineConfig({
-  plugins: [storybookTest()],
+  plugins: [/* ...app plugins */],
   test: {
-    name: "storybook",
-    browser: { enabled: true, provider: "playwright", instances: [{ browser: "chromium" }] },
-    setupFiles: [".storybook/vitest.setup.ts"],
+    projects: [
+      {
+        extends: true,
+        test: { name: "unit", environment: "jsdom", setupFiles: ["./tests/setup.ts"] },
+      },
+      {
+        extends: true,
+        plugins: [storybookTest({ configDir: ".storybook" })],
+        test: {
+          name: "storybook",
+          browser: { enabled: true, headless: true, provider: playwright(), instances: [{ browser: "chromium" }] },
+          setupFiles: [".storybook/vitest.setup.ts"],
+        },
+      },
+    ],
   },
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.1.18",
+	"version": "0.1.22",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {

package/src/detect.ts

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { StackName } from "./types.js";
+
+/** Result of detecting a stack in a project */
+export interface DetectedStack {
+	name: StackName;
+	reason: string;
+}
+
+interface PackageJson {
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+}
+
+interface StackDetector {
+	name: StackName;
+	detect: (projectDir: string, pkg: PackageJson | null) => DetectedStack | null;
+}
+
+function loadPackageJson(projectDir: string): PackageJson | null {
+	const pkgPath = join(projectDir, "package.json");
+	if (!existsSync(pkgPath)) return null;
+	try {
+		return JSON.parse(readFileSync(pkgPath, "utf-8")) as PackageJson;
+	} catch {
+		return null;
+	}
+}
+
+function hasDep(pkg: PackageJson | null, name: string): boolean {
+	if (!pkg) return false;
+	return name in (pkg.dependencies ?? {}) || name in (pkg.devDependencies ?? {});
+}
+
+function fileExists(projectDir: string, ...segments: string[]): boolean {
+	return existsSync(join(projectDir, ...segments));
+}
+
+function rootConfigExists(projectDir: string, prefix: string): string | null {
+	const glob = new Bun.Glob(`${prefix}.*`);
+	for (const match of glob.scanSync({ cwd: projectDir, onlyFiles: true })) {
+		return match;
+	}
+	return null;
+}
+
+const DETECTORS: StackDetector[] = [
+	{
+		name: "solidjs",
+		detect: (_dir, pkg) =>
+			hasDep(pkg, "solid-js")
+				? { name: "solidjs", reason: "found solid-js in dependencies" }
+				: null,
+	},
+	{
+		name: "vite",
+		detect: (dir, pkg) => {
+			if (hasDep(pkg, "vite")) return { name: "vite", reason: "found vite in dependencies" };
+			const viteConfig = rootConfigExists(dir, "vite.config");
+			if (viteConfig) return { name: "vite", reason: `found ${viteConfig}` };
+			const vitestConfig = rootConfigExists(dir, "vitest.config");
+			if (vitestConfig) return { name: "vite", reason: `found ${vitestConfig}` };
+			return null;
+		},
+	},
+	{
+		name: "vanilla-extract",
+		detect: (_dir, pkg) =>
+			hasDep(pkg, "@vanilla-extract/css")
+				? { name: "vanilla-extract", reason: "found @vanilla-extract/css in dependencies" }
+				: null,
+	},
+	{
+		name: "rust-wasm",
+		detect: (dir) =>
+			fileExists(dir, "Cargo.toml") ? { name: "rust-wasm", reason: "found Cargo.toml" } : null,
+	},
+	{
+		name: "protobuf",
+		detect: (dir) => {
+			if (fileExists(dir, "buf.yaml")) return { name: "protobuf", reason: "found buf.yaml" };
+			if (fileExists(dir, "buf.gen.yaml"))
+				return { name: "protobuf", reason: "found buf.gen.yaml" };
+			const glob = new Bun.Glob("**/*.proto");
+			for (const _match of glob.scanSync({ cwd: dir, onlyFiles: true })) {
+				return { name: "protobuf", reason: "found .proto files" };
+			}
+			return null;
+		},
+	},
+	{
+		name: "cloudflare",
+		detect: (dir) => {
+			if (fileExists(dir, "wrangler.toml"))
+				return { name: "cloudflare", reason: "found wrangler.toml" };
+			if (fileExists(dir, "wrangler.jsonc"))
+				return { name: "cloudflare", reason: "found wrangler.jsonc" };
+			return null;
+		},
+	},
+	{
+		name: "i18n-typesafe",
+		detect: (_dir, pkg) =>
+			hasDep(pkg, "typesafe-i18n")
+				? { name: "i18n-typesafe", reason: "found typesafe-i18n in dependencies" }
+				: null,
+	},
+	{
+		name: "playwright",
+		detect: (dir, pkg) => {
+			if (hasDep(pkg, "@playwright/test"))
+				return { name: "playwright", reason: "found @playwright/test in dependencies" };
+			const config = rootConfigExists(dir, "playwright.config");
+			if (config) return { name: "playwright", reason: `found ${config}` };
+			return null;
+		},
+	},
+	{
+		name: "storybook",
+		detect: (dir, pkg) => {
+			if (hasDep(pkg, "storybook"))
+				return { name: "storybook", reason: "found storybook in dependencies" };
+			if (fileExists(dir, ".storybook"))
+				return { name: "storybook", reason: "found .storybook/ directory" };
+			return null;
+		},
+	},
+];
+
+/** Scan a project directory and detect which stacks are present */
+export function detectStacks(projectDir: string): DetectedStack[] {
+	const pkg = loadPackageJson(projectDir);
+	const detected: DetectedStack[] = [];
+	for (const detector of DETECTORS) {
+		const result = detector.detect(projectDir, pkg);
+		if (result) detected.push(result);
+	}
+	return detected;
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+export type { DetectedStack } from "./detect.js";
+export { detectStacks } from "./detect.js";
 export type {
 	ClaudeToolkitConfig,
 	GitConfig,

package/src/types.ts

@@ -6,6 +6,9 @@ export type StackName =
 	| "protobuf"
 	| "cloudflare"
 	| "i18n-typesafe"
+	| "vite"
+	| "playwright"
+	| "storybook"
 	| (string & {});
 
 /** Hook configuration for post-tool-use automation */
@@ -24,7 +27,7 @@ export interface HookConfig {
 
 /** Git workflow configuration */
 export interface GitConfig {
-	/** Branch name prefix (e.g., "wq" → "wq/feature-name") */
+	/** Branch name prefix (e.g., "feat" → "feat/feature-name") */
 	branchPrefix?: string;
 	/** Branches protected from direct edits */
 	protectedBranches?: string[];

package/stacks/storybook/skills/ct-storybook-patterns/SKILL.md

@@ -77,16 +77,33 @@ export const SubmitForm: Story = {
 
 Use `@storybook/addon-vitest` (replaces old test-runner). No running Storybook instance needed.
 
+Required dependencies: `@storybook/addon-vitest`, `@vitest/browser`, `@vitest/browser-playwright`, `@vitest/coverage-v8`.
+
+Add as an inline project in your main Vite config using `test.projects`:
+
 ```typescript
-// vitest.config.storybook.ts
+// vite.config.ts
 import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
+import { playwright } from "@vitest/browser-playwright";
 
 export default defineConfig({
-  plugins: [storybookTest()],
+  plugins: [/* ...app plugins */],
   test: {
-    name: "storybook",
-    browser: { enabled: true, provider: "playwright", instances: [{ browser: "chromium" }] },
-    setupFiles: [".storybook/vitest.setup.ts"],
+    projects: [
+      {
+        extends: true,
+        test: { name: "unit", environment: "jsdom", setupFiles: ["./tests/setup.ts"] },
+      },
+      {
+        extends: true,
+        plugins: [storybookTest({ configDir: ".storybook" })],
+        test: {
+          name: "storybook",
+          browser: { enabled: true, headless: true, provider: playwright(), instances: [{ browser: "chromium" }] },
+          setupFiles: [".storybook/vitest.setup.ts"],
+        },
+      },
+    ],
   },
 });
 ```