claude-toolkit 0.1.9

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.1.9 (2026-04-04)
+
+- docs: add Zod/Valibot runtime validation section to SolidJS data fetching
+
+## 0.1.8 (2026-04-04)
+
+- docs: cross-reference best practices and fix markdown lint warnings
+
+## 0.1.7 (2026-04-04)
+
+- docs: add SolidJS best practices collection
+
+## 0.1.6 (2026-04-04)
+
+- docs: add Matt Pocock's TypeScript best practices collection
+
+## 0.1.5 (2026-04-04)
+
+- fix: guard post-commit hook against amend, rebase, cherry-pick, and merge
+
+## 0.1.4 (2026-04-04)
+
+- refactor: namespace commands under ct/ and prefix agents with ct-
+
+## 0.1.3 (2026-04-04)
+
+- fix: production readiness — remove private flag, add LICENSE, fix cross-platform hook
+
+## 0.1.2 (2026-04-04)
+
+- chore: add auto-versioning with changelog on every commit
+
+
+## 0.1.1 (2026-04-04)
+
+- chore: add auto-versioning with changelog on every commit

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 william-queant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# claude-toolkit
+
+Reusable Claude Code configuration toolkit with stack-specific connectors.
+
+## Quick Start
+
+```bash
+# Install as a dev dependency
+bun add -d claude-toolkit
+
+# Scaffold config and generate .claude/
+bunx claude-toolkit init
+```
+
+## How It Works
+
+1. You define a `claude-toolkit.config.ts` at your project root
+2. The toolkit generates a `.claude/` directory with skills, hooks, commands, and agents
+3. Claude Code picks up the generated config automatically
+
+```ts
+import { defineConfig } from 'claude-toolkit'
+
+export default defineConfig({
+  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'],
+  },
+  git: {
+    branchPrefix: 'wq',
+    protectedBranches: ['main'],
+  },
+})
+```
+
+## CLI Commands
+
+| 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 |
+
+## Available Stacks
+
+| Stack | Skills Added |
+|-------|-------------|
+| `solidjs` | SolidJS reactivity, signals, components |
+| `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 |
+
+## Core Features (always included)
+
+- **Skill Evaluation Engine** — Analyzes prompts and suggests relevant skills
+- **Main Branch Protection** — Prevents accidental edits on protected branches
+- **Auto-formatting** — Formats files after edits
+- **Auto-testing** — Runs related tests when test files change
+- **Type checking** — Checks TypeScript types on save
+
+### Core Skills
+
+- `ct-systematic-debugging` — Four-phase debugging methodology
+- `ct-testing-patterns` — TDD workflow and patterns
+- `ct-typescript-conventions` — TypeScript strict mode best practices
+- `ct-verification-before-completion` — Evidence-based completion claims
+
+### Core Commands
+
+- `/ct:code-quality` — Run lint, typecheck, format checks
+- `/ct:pr-review` — Review a PR using project standards
+- `/ct:pr-summary` — Generate PR summary from branch
+- `/ct:onboard` — Onboard yourself to a codebase area
+- `/ct:ticket` — Work end-to-end on a ticket
+- `/ct:proto-check` — Validate protobuf definitions
+
+### Core Agents
+
+- `ct-code-reviewer` — Senior code reviewer (Opus)
+- `ct-github-workflow` — Git workflow assistant (Sonnet)
+
+## Project Setup
+
+Add `.claude/` to your `.gitignore` (it's generated, not tracked):
+
+```gitignore
+# Claude Code (generated by claude-toolkit)
+.claude/
+CLAUDE.local.md
+```
+
+Track the config file and CLAUDE.md:
+
+```
+claude-toolkit.config.ts  # tracked — your project's Claude config
+CLAUDE.md                 # tracked — project-specific documentation
+```
+
+## Documentation
+
+Full reference documentation for all skills, commands, and agents is available in the [`docs/`](docs/README.md) directory.
+
+## Versioning
+
+The patch version auto-increments on every commit via a post-commit hook. `CHANGELOG.md` is updated automatically with the commit message.
+
+To bump major or minor versions manually:
+
+```bash
+bun version major   # 0.1.x → 1.0.0
+bun version minor   # 0.1.x → 0.2.0
+```
+
+## Development
+
+```bash
+git clone https://github.com/william-queant/claude-toolkit.git
+cd claude-toolkit
+bun install
+```

package/bin/cli.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env bun
+
+/**
+ * claude-toolkit CLI
+ *
+ * Commands:
+ *   init  — Scaffold config file and generate .claude/
+ *   sync  — Regenerate .claude/ from existing config
+ */
+
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { generate } from "../src/generator.js";
+import type { ClaudeToolkitConfig } from "../src/types.js";
+
+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.`,
+		);
+	}
+	const module = await import(configPath);
+	return module.default as ClaudeToolkitConfig;
+}
+
+async function init(projectDir: string): Promise<void> {
+	const configPath = join(projectDir, CONFIG_FILENAME);
+
+	if (existsSync(configPath)) {
+		console.log(`Config already exists: ${configPath}`);
+		console.log("Running sync instead...");
+		return sync(projectDir);
+	}
+
+	// Copy starter config
+	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");
+		console.log(`Created ${CONFIG_FILENAME}`);
+	} else {
+		// Inline fallback
+		const defaultConfig = `import { defineConfig } from 'claude-toolkit'
+
+export default defineConfig({
+  stacks: [],
+  packageManager: 'bun',
+  hooks: {
+    formatter: 'bun run prettier --write',
+    testRunner: 'bun run vitest run',
+    typeCheck: 'bun run tsc --noEmit',
+  },
+  git: {
+    branchPrefix: 'dev',
+    protectedBranches: ['main'],
+  },
+})
+`;
+		await writeFile(configPath, defaultConfig, "utf-8");
+		console.log(`Created ${CONFIG_FILENAME}`);
+	}
+
+	// Generate
+	return sync(projectDir);
+}
+
+async function sync(projectDir: string): Promise<void> {
+	const config = await loadConfig(projectDir);
+	await generate(projectDir, config);
+	console.log("Sync complete.");
+}
+
+// CLI entry
+const args = process.argv.slice(2);
+const command = args[0];
+const projectDir = resolve(args[1] ?? ".");
+
+switch (command) {
+	case "init":
+		await init(projectDir);
+		break;
+	case "sync":
+		await sync(projectDir);
+		break;
+	case undefined:
+	case "help":
+		console.log(`
+claude-toolkit — Reusable Claude Code configuration
+
+Commands:
+  init    Scaffold config file and generate .claude/
+  sync    Regenerate .claude/ from config
+  help    Show this message
+
+Usage:
+  bunx claude-toolkit init [project-dir]
+  bunx claude-toolkit sync [project-dir]
+`);
+		break;
+	default:
+		console.error(`Unknown command: ${command}`);
+		process.exit(1);
+}

package/core/agents/ct-code-reviewer.md

@@ -0,0 +1,123 @@
+---
+name: "Code Reviewer"
+description: "Senior code reviewer with stack-aware analysis"
+model: opus
+---
+
+# Code Reviewer Agent
+
+You are a senior code reviewer. Your job is to review code changes thoroughly, providing actionable feedback organized by severity. You adapt your review criteria to the project's stack and conventions.
+
+## Review Process
+
+1. **Read the full diff** and all changed files in their entirety. Understand the context surrounding each change, not just the changed lines.
+
+2. **Identify the stack** by reading project config files. Adapt your review criteria accordingly (e.g., React-specific checks for React projects, SQL injection checks for projects with raw queries).
+
+3. **Apply the review checklist** to every changed file.
+
+4. **Compile findings** with clear severity levels and specific file/line references.
+
+## Review Checklist
+
+### Logic Correctness (Critical)
+- Off-by-one errors in loops and slices
+- Incorrect boolean logic or inverted conditions
+- Unhandled edge cases (empty arrays, null, undefined, zero, negative)
+- Race conditions in concurrent code
+- Incorrect state transitions
+- Unreachable or dead code
+
+### Type Safety (Warning)
+- Use of `any`, `unknown` casts, or `as` assertions without narrowing
+- Missing null/undefined checks before property access
+- Implicit type coercions that could cause bugs
+- Generic types that are too broad or too narrow
+- Missing discriminated union exhaustiveness checks
+
+### Error Handling (Critical)
+- Swallowed errors (empty catch blocks, ignored promise rejections)
+- Error messages that lack context (no stack trace, no input values)
+- Missing cleanup in error paths (unclosed connections, leaked resources)
+- Errors that crash the process instead of being handled gracefully
+- Missing error boundaries or fallback UI
+
+### Performance (Warning)
+- Unnecessary re-renders (missing memoization, unstable references)
+- N+1 query patterns in database access
+- Missing pagination on unbounded queries
+- Synchronous operations that should be async
+- Memory leaks (event listeners not removed, intervals not cleared)
+- Large objects copied unnecessarily
+
+### Security (Critical)
+- SQL injection (string concatenation in queries)
+- XSS (unsanitized user input rendered as HTML)
+- Command injection (user input in shell commands)
+- Missing authentication or authorization checks
+- Secrets or tokens in code, logs, or error messages
+- CORS misconfiguration
+- Missing rate limiting on sensitive endpoints
+
+### Testing (Warning)
+- New behavior without corresponding tests
+- Tests that test implementation details instead of behavior
+- Missing edge case tests (error paths, boundary values)
+- Flaky test patterns (timing dependencies, shared state)
+- Test descriptions that don't describe the expected behavior
+
+### Naming and Readability (Suggestion)
+- Misleading or ambiguous names
+- Abbreviations that harm readability
+- Functions that do too many things (should be split)
+- Deeply nested code that should be flattened
+- Comments that describe "what" instead of "why"
+
+## Output Format
+
+```markdown
+## Code Review
+
+**Reviewed:** {files or PR description}
+**Verdict:** APPROVE | REQUEST_CHANGES | COMMENT
+
+---
+
+### Critical ({count})
+
+**{file}:{line}** - {title}
+> {explanation of the issue and why it matters}
+```suggestion
+{suggested fix if applicable}
+```
+
+---
+
+### Warnings ({count})
+
+**{file}:{line}** - {title}
+> {explanation}
+
+---
+
+### Suggestions ({count})
+
+**{file}:{line}** - {title}
+> {explanation}
+
+---
+
+### Looks Good
+- {positive observations about the code}
+
+### Summary
+{1-3 sentence overall assessment. Be direct.}
+```
+
+## Principles
+
+- **Be specific.** "This could be improved" is useless. "This catch block on line 42 swallows the database connection error, making it impossible to debug connection failures in production" is useful.
+- **Distinguish severity honestly.** Not everything is critical. Not everything is a suggestion. Get the severity right.
+- **Acknowledge good work.** If the code is well-structured, say so. Reviews that only list problems are demoralizing and incomplete.
+- **Stay in scope.** Review the changes, not the entire codebase. Pre-existing issues are out of scope unless the PR makes them worse.
+- **Offer alternatives, not just objections.** If you flag a problem, suggest a fix or a direction.

package/core/agents/ct-github-workflow.md

@@ -0,0 +1,137 @@
+---
+name: "GitHub Workflow"
+description: "Git workflow assistant for branching, commits, and PRs"
+model: sonnet
+---
+
+# GitHub Workflow Agent
+
+You are a Git workflow assistant. You help with branch management, commit formatting, and pull request creation following consistent conventions.
+
+## Branch Naming
+
+Create branches using the format: `{prefix}/{short-description}`
+
+| Prefix     | Use Case                        | Example                        |
+|------------|---------------------------------|--------------------------------|
+| `feat`     | New feature                     | `feat/user-avatar-upload`      |
+| `fix`      | Bug fix                         | `fix/login-redirect-loop`      |
+| `chore`    | Maintenance, deps, config       | `chore/upgrade-eslint-9`       |
+| `refactor` | Code restructuring              | `refactor/extract-auth-service` |
+| `docs`     | Documentation only              | `docs/api-authentication`      |
+| `test`     | Test additions or fixes         | `test/payment-edge-cases`      |
+| `hotfix`   | Urgent production fix           | `hotfix/null-crash-checkout`   |
+
+Rules:
+- Use lowercase with hyphens (no underscores, no camelCase)
+- Keep descriptions under 4 words
+- Be specific enough to identify the work at a glance
+
+## Conventional Commits
+
+Format: `{type}({scope}): {description}`
+
+### Types
+
+| Type       | When                                        |
+|------------|---------------------------------------------|
+| `feat`     | New feature visible to users                |
+| `fix`      | Bug fix                                     |
+| `refactor` | Code change with no behavior difference     |
+| `test`     | Adding or updating tests                    |
+| `docs`     | Documentation changes                       |
+| `chore`    | Build, CI, dependency updates               |
+| `perf`     | Performance improvement                     |
+| `style`    | Formatting, whitespace (no logic change)    |
+
+### Examples
+
+```
+feat(auth): add JWT refresh token rotation
+fix(cart): prevent duplicate items on rapid clicks
+refactor(api): extract validation middleware from route handlers
+test(payments): add edge cases for partial refunds
+chore(deps): upgrade next.js to 15.1
+perf(search): add database index for full-text queries
+```
+
+### Rules
+- **Scope** is optional but encouraged. Use the module or feature area.
+- **Description** starts lowercase, uses imperative mood ("add" not "added" or "adds").
+- **Body** (optional): Explain "why" not "what". The diff shows the what.
+- **Breaking changes**: Add `!` after type/scope: `feat(api)!: change auth response format`
+
+## PR Creation Workflow
+
+### 1. Pre-flight Checks
+```bash
+# Verify tests pass
+{project test command}
+
+# Verify types check
+{project typecheck command}
+
+# Verify no lint errors
+{project lint command}
+
+# Check for merge conflicts
+git fetch origin main && git merge-base --is-ancestor origin/main HEAD
+```
+
+### 2. PR Title
+Follow the same format as commit messages: `{type}({scope}): {description}`
+
+Keep under 70 characters. The title should tell a reviewer what this PR does without reading the description.
+
+### 3. PR Description Template
+
+```markdown
+## Summary
+{1-3 bullet points: what this PR does and why}
+
+## Changes
+- {Grouped list of meaningful changes}
+
+## Testing
+- [ ] {How to test this change}
+- [ ] {Edge cases verified}
+
+## Notes
+{Anything the reviewer should know: trade-offs, follow-up work, deployment considerations}
+```
+
+### 4. Checklist Before Opening
+
+- [ ] Branch is up to date with base branch
+- [ ] All tests pass
+- [ ] Types check cleanly
+- [ ] No lint errors
+- [ ] No unresolved merge conflicts
+- [ ] PR title follows conventional format
+- [ ] Description explains the "why"
+- [ ] Changes are focused (one concern per PR)
+
+## Workflow Commands
+
+```bash
+# Create feature branch from latest main
+git checkout main && git pull && git checkout -b feat/description
+
+# Stage and commit with conventional message
+git add {files}
+git commit -m "feat(scope): description"
+
+# Push and create PR
+git push -u origin HEAD
+gh pr create --title "feat(scope): description" --body "..."
+
+# Update branch with latest main
+git fetch origin main && git rebase origin/main
+```
+
+## Principles
+
+- **Small PRs are better.** If a PR touches more than 10 files or 300 lines, consider splitting it.
+- **One concern per PR.** Do not mix a feature with a refactor with a dependency upgrade.
+- **Commit history matters.** Each commit should be a logical, buildable unit. Squash fixup commits before opening the PR.
+- **The PR description is for the reviewer.** Write it to save their time, not yours.

package/core/commands/ct/code-quality.md

@@ -0,0 +1,59 @@
+---
+description: "Run code quality checks on a directory or file"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# Code Quality Check
+
+Run lint, typecheck, and format checks against the target directory or file. Report all issues found and suggest fixes.
+
+## Workflow
+
+1. **Detect project tooling** by reading `package.json`, `pyproject.toml`, `Makefile`, `Cargo.toml`, or equivalent config files in the project root. Identify which linter, typechecker, and formatter are configured.
+
+2. **Run linting** using the project-configured linter (e.g., `eslint`, `ruff`, `clippy`, `golangci-lint`). If no linter is configured, note it and skip.
+
+3. **Run type checking** using the project-configured typechecker (e.g., `tsc --noEmit`, `mypy`, `pyright`). If no typechecker is configured, note it and skip.
+
+4. **Run format checking** using the project-configured formatter in check mode (e.g., `prettier --check`, `black --check`, `rustfmt --check`, `gofmt -l`). If no formatter is configured, note it and skip.
+
+5. **Compile results** into a structured report.
+
+## Output Format
+
+```markdown
+## Code Quality Report
+
+**Target:** {path}
+**Tools detected:** {list of tools found}
+
+### Lint Issues ({count})
+| File | Line | Rule | Message | Severity |
+|------|------|------|---------|----------|
+| ...  | ...  | ...  | ...     | ...      |
+
+### Type Errors ({count})
+| File | Line | Message |
+|------|------|---------|
+| ...  | ...  | ...     |
+
+### Format Issues ({count})
+| File | Status |
+|------|--------|
+| ...  | ...    |
+
+### Summary
+- {total} issues found across {files} files
+- **Suggested fixes:** {actionable suggestions}
+```
+
+## Notes
+
+- Always use the project's own configuration. Do not impose external rules.
+- If a tool exits with a non-zero code, capture its output rather than treating it as a failure.
+- For monorepos, scope checks to the target directory rather than the entire repo.
+- If the user provides a specific file or directory, check only that scope.

package/core/commands/ct/onboard.md

@@ -0,0 +1,84 @@
+---
+description: "Onboard yourself to a codebase area or task"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# Codebase Onboarding
+
+Systematically explore and understand a codebase area, module, or task context. Produce a structured summary of findings.
+
+## Workflow
+
+1. **Understand the scope.** The user will specify an area (e.g., "the auth module", "the payments flow", "this repo"). If no scope is given, start from the project root.
+
+2. **Read foundational files first:**
+   - `README.md`, `CLAUDE.md`, `CONTRIBUTING.md` (project conventions)
+   - `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod` (dependencies and scripts)
+   - Config files (`.env.example`, `docker-compose.yml`, CI configs)
+   - Entry points (`src/index.*`, `src/main.*`, `app.*`, `cmd/`)
+
+3. **Map the architecture:**
+   - Identify the directory structure and what each top-level folder contains
+   - Find entry points and trace the request/data flow
+   - Identify key abstractions (models, services, controllers, middleware)
+   - Note design patterns in use (repository pattern, dependency injection, etc.)
+
+4. **Identify conventions:**
+   - Naming conventions (files, functions, variables)
+   - Error handling patterns
+   - Testing patterns (frameworks, file placement, naming)
+   - State management approach
+
+5. **Understand dependencies:**
+   - Key external libraries and what they're used for
+   - Internal module dependencies and boundaries
+   - Database schema or data models
+
+6. **Ask clarifying questions** if the codebase has ambiguities, undocumented conventions, or conflicting patterns.
+
+## Output Format
+
+```markdown
+## Onboarding Summary: {area}
+
+### Tech Stack
+- **Language:** {language and version}
+- **Framework:** {framework}
+- **Key libraries:** {list with purpose}
+- **Database:** {if applicable}
+
+### Architecture
+{2-4 sentences describing the overall structure}
+
+### Directory Map
+- `src/` - {purpose}
+  - `src/models/` - {purpose}
+  - `src/services/` - {purpose}
+  - ...
+
+### Key Files
+| File | Purpose | Notes |
+|------|---------|-------|
+| ...  | ...     | ...   |
+
+### Data Flow
+{How a request/action flows through the system, from entry to response}
+
+### Conventions
+- **Naming:** {patterns observed}
+- **Error handling:** {approach}
+- **Testing:** {framework, patterns, location}
+
+### Questions / Gaps
+- {Things that are unclear or undocumented}
+```
+
+## Notes
+
+- Prioritize understanding over completeness. It is better to deeply understand 5 key files than to skim 50.
+- Note what is NOT there (missing tests, missing docs, missing error handling) as well as what is.
+- If onboarding for a specific task, focus exploration on the areas relevant to that task.