claude-toolkit 0.1.9

package/core/hooks/skill-eval.sh

@@ -0,0 +1,35 @@
+#!/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

package/core/hooks/skill-rules.schema.json

@@ -0,0 +1,112 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "Skill Rules Configuration",
+	"description": "Configuration for automatic skill activation based on prompt analysis",
+	"type": "object",
+	"required": ["version", "config", "scoring", "skills"],
+	"properties": {
+		"$schema": {
+			"type": "string",
+			"description": "JSON Schema reference"
+		},
+		"version": {
+			"type": "string",
+			"description": "Schema version",
+			"pattern": "^\\d+\\.\\d+$"
+		},
+		"config": {
+			"type": "object",
+			"description": "Global configuration options",
+			"required": ["minConfidenceScore", "showMatchReasons", "maxSkillsToShow"],
+			"properties": {
+				"minConfidenceScore": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Minimum score required to suggest a skill"
+				},
+				"showMatchReasons": {
+					"type": "boolean",
+					"description": "Whether to show why each skill was matched"
+				},
+				"maxSkillsToShow": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 10,
+					"description": "Maximum number of skills to show in output"
+				}
+			}
+		},
+		"scoring": {
+			"type": "object",
+			"description": "Points assigned to each match type",
+			"required": [
+				"keyword",
+				"keywordPattern",
+				"pathPattern",
+				"directoryMatch",
+				"intentPattern",
+				"contentPattern",
+				"contextPattern"
+			],
+			"properties": {
+				"keyword": { "type": "integer", "minimum": 1 },
+				"keywordPattern": { "type": "integer", "minimum": 1 },
+				"pathPattern": { "type": "integer", "minimum": 1 },
+				"directoryMatch": { "type": "integer", "minimum": 1 },
+				"intentPattern": { "type": "integer", "minimum": 1 },
+				"contentPattern": { "type": "integer", "minimum": 1 },
+				"contextPattern": { "type": "integer", "minimum": 1 }
+			}
+		},
+		"directoryMappings": {
+			"type": "object",
+			"description": "Map directory paths to skill names",
+			"additionalProperties": { "type": "string" }
+		},
+		"skills": {
+			"type": "object",
+			"description": "Skill definitions and their triggers",
+			"additionalProperties": {
+				"type": "object",
+				"required": ["description", "triggers"],
+				"properties": {
+					"description": { "type": "string" },
+					"priority": {
+						"type": "integer",
+						"minimum": 1,
+						"maximum": 10,
+						"default": 5
+					},
+					"triggers": {
+						"type": "object",
+						"properties": {
+							"keywords": { "type": "array", "items": { "type": "string" } },
+							"keywordPatterns": {
+								"type": "array",
+								"items": { "type": "string" }
+							},
+							"pathPatterns": {
+								"type": "array",
+								"items": { "type": "string" }
+							},
+							"intentPatterns": {
+								"type": "array",
+								"items": { "type": "string" }
+							},
+							"contentPatterns": {
+								"type": "array",
+								"items": { "type": "string" }
+							},
+							"contextPatterns": {
+								"type": "array",
+								"items": { "type": "string" }
+							}
+						}
+					},
+					"excludePatterns": { "type": "array", "items": { "type": "string" } },
+					"relatedSkills": { "type": "array", "items": { "type": "string" } }
+				}
+			}
+		}
+	}
+}

package/core/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ct-systematic-debugging
+description: Four-phase methodology for diagnosing and fixing bugs efficiently without guesswork.
+---
+
+# Systematic Debugging
+
+Replace trial-and-error with structured investigation. Follow phases in order.
+
+## Phase 1: Observe
+
+- Reproduce reliably with minimal steps. No repro = no verified fix.
+- Read the full stack trace and error message. Do not skim.
+- `git log`/`git diff` to identify what changed since last known-good state.
+- Record observations (environment, input, timing), not theories.
+
+## Phase 2: Hypothesize
+
+- List 2-3 possible causes before investigating any.
+- Rank by: what changed recently, simplest explanation, where evidence points.
+- Trace data flow from input to error. Check assumptions about dependencies/configs.
+
+## Phase 3: Test
+
+- Change one variable per experiment. Multiple changes = ambiguous results.
+- Write minimal reproduction (unit test, script, reduced input).
+- Add logging at function boundaries and data transformations.
+- Design tests that would **disprove** each hypothesis.
+- Binary search large problem spaces systematically.
+
+## Phase 4: Fix
+
+- Fix root cause, not symptom. A null check that hides a null source is not a fix.
+- Smallest change possible. Run reproduction to confirm fix.
+- Run full test suite for regressions. Add a test for this bug class.
+- Commit message explains cause and why fix is correct.
+
+## Anti-Patterns
+
+1. **Shotgun debugging** -- Random changes without hypotheses.
+2. **Fixing symptoms** -- Null checks/try-catch without understanding the unexpected state.
+3. **Debug by rewriting** -- Bug may survive the rewrite; new bugs may appear.
+4. **"It works now"** -- Intermittent bugs are race conditions or state leaks. Investigate.
+5. **Assuming the bug is elsewhere** -- Check your own code first. The framework is rarely the problem.

package/core/skills/testing-patterns/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ct-testing-patterns
+description: Generic test-driven development practices and patterns applicable to any language or test framework.
+---
+
+# Testing Patterns
+
+## TDD Cycle
+
+1. **Red** -- Write a failing test for desired behavior. Confirm it fails for the right reason.
+2. **Green** -- Minimal code to pass. No optimization yet.
+3. **Refactor** -- Clean up while keeping tests green. Commit at each stage.
+
+## Test Behavior, Not Implementation
+
+Test *what* code does (public interface, observable outputs), not *how* (internal state, call counts). Implementation-coupled tests break on every refactor.
+
+## Factory Pattern
+
+```
+function getMockUser(overrides = {}) {
+  return { id: "user-1", email: "test@example.com", name: "Test User", role: "member", ...overrides };
+}
+const admin = getMockUser({ role: "admin" });
+```
+
+New required fields update the factory once, not every test.
+
+## Organization
+
+- Co-locate tests or mirror source structure. One test file per module (`module.test.ext`).
+- Group with `describe`, name as sentences: `it("rejects expired tokens")`.
+
+## Mocking Rules
+
+- Prefer real dependencies (in-memory DB, local server) when feasible.
+- Mock at boundaries only (external APIs, email, payments), not internal modules.
+- Keep mocks minimal -- only methods your code calls. Reset between tests.
+- Verify mocks match the real API. Update when APIs change.
+
+## Test Pyramid
+
+Many unit tests (fast, focused) > some integration tests (multi-component) > few E2E tests (full flow).
+
+## Anti-Patterns
+
+1. **Testing implementation** -- Asserting internal state or call counts breaks on refactors.
+2. **Overmocking** -- If most of the test is mock setup, you're testing mocks.
+3. **Copy-paste tests** -- Use factories and parameterized tests.
+4. **No assertions** -- Worse than no test. False confidence.
+5. **Ignoring flaky tests** -- Fix or delete; never skip indefinitely.
+6. **Happy path only** -- Error cases and boundary conditions are where bugs live.

package/core/skills/typescript-conventions/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ct-typescript-conventions
+description: Strict TypeScript patterns for type safety, readability, and maintainable codebases.
+---
+
+# TypeScript Conventions
+
+Strict mode enabled. Catch errors at compile time, not runtime.
+
+## Rules
+
+- **No `any`** -- Use `unknown` + narrowing, generics, or specific types.
+- **`interface` for objects**, `type` for unions/intersections/utilities.
+- **`as const`** for literal types and readonly tuples.
+- **Never disable strict checks.** Hard-to-type code = design issue.
+
+## Exhaustive Switch
+
+```typescript
+function getPerms(role: UserRole): string[] {
+  switch (role) {
+    case "admin": return ["read", "write", "delete"];
+    case "member": return ["read", "write"];
+    case "guest": return ["read"];
+    default: { const _: never = role; throw new Error(`Unhandled: ${_}`); }
+  }
+}
+```
+
+Adding a new `UserRole` value causes a compile error at `never`, forcing handling.
+
+## Discriminated Unions
+
+Model states with different data as unions. Narrowing on the discriminant gives type-safe access.
+
+```typescript
+type AsyncState<T> =
+  | { status: "loading" }
+  | { status: "success"; data: T }
+  | { status: "error"; error: Error };
+```
+
+## Generic Constraints
+
+```typescript
+function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
+  return items.find(item => item.id === id);
+}
+```
+
+## Anti-Patterns
+
+1. **`as` casts** -- Use type guards and narrowing instead.
+2. **Non-null assertion `!`** -- Handle the null case explicitly.
+3. **Enums** -- Prefer string literal unions. Enums generate runtime code with surprising behavior.
+4. **`Object`, `Function`, `{}`** -- Use specific interfaces or `Record<string, unknown>`.
+5. **`@ts-ignore`** -- Without an explanatory comment and tracking issue, the error will be forgotten.

package/core/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ct-verification-before-completion
+description: Evidence-based completion claims -- never say "done" without proof that the work is correct.
+---
+
+# Verification Before Completion
+
+**Never claim "done" without evidence.** "I wrote the code" is not evidence. "Tests pass, types check, here is the output" is evidence.
+
+## Checklist
+
+Before claiming complete, run and show output for each:
+
+1. **Tests pass** -- Full suite or related tests. Show actual output, not just "tests pass".
+2. **Types check** -- `tsc --noEmit` with zero errors on changed files.
+3. **Lint passes** -- Fix violations introduced by your changes.
+4. **Feature works** -- Show actual output (API response, CLI output, screenshot) for user-facing changes.
+
+## Edge Cases to Verify
+
+- Empty inputs (empty string, empty array, null, undefined)
+- Boundary values (zero, negative, max, off-by-one)
+- Invalid inputs (wrong types, malformed data, missing fields)
+- Error paths (network failure, permission denied)
+
+Do not assume edge cases work because the happy path works.
+
+## Regression Check
+
+- Run tests for modules that depend on changed code.
+- Verify consumers of changed APIs/schemas still work.
+- Smoke test the running application if applicable.
+
+## Evidence Format
+
+```
+## Completed: [task name]
+- Tests: X passing (Y new, Z existing) -- [command output]
+- Types: tsc --noEmit: 0 errors
+- Manual: [endpoint/action]: [status/result]
+- Edge cases: [what was verified]
+```

package/docs/README.md

@@ -0,0 +1,49 @@
+# claude-toolkit Documentation
+
+Complete reference for all skills, commands, and agents provided by claude-toolkit.
+
+## Core Skills
+
+Skills that are always included regardless of stack configuration.
+
+| Skill                                                                      | Description                                                                 |
+| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| [ct-systematic-debugging](skills/systematic-debugging.md)                     | Four-phase methodology for diagnosing and fixing bugs without guesswork     |
+| [ct-testing-patterns](skills/testing-patterns.md)                             | Framework-agnostic TDD practices, mocking strategies, and test organization |
+| [ct-typescript-conventions](skills/typescript-conventions.md)                 | Strict TypeScript patterns for type safety and maintainability              |
+| [ct-verification-before-completion](skills/verification-before-completion.md) | Evidence-based completion claims with structured verification checklist     |
+
+## Commands
+
+Slash commands available in Claude Code sessions.
+
+| Command                                   | Description                                                                |
+| ----------------------------------------- | -------------------------------------------------------------------------- |
+| [/ct:code-quality](commands/code-quality.md) | Run lint, typecheck, and format checks with structured reporting           |
+| [/ct:pr-review](commands/pr-review.md)       | Checklist-based code review against project standards                      |
+| [/ct:pr-summary](commands/pr-summary.md)     | Generate a structured PR summary from branch diff and commits              |
+| [/ct:onboard](commands/onboard.md)           | Systematically explore and understand a codebase area                      |
+| [/ct:ticket](commands/ticket.md)             | Work end-to-end on a ticket: understand, explore, plan, implement, deliver |
+| [/ct:proto-check](commands/proto-check.md)   | Validate protobuf definitions, lint, breaking changes, and code generation |
+
+## Agents
+
+Specialized agents with dedicated models and review capabilities.
+
+| Agent                                        | Model  | Description                                                                |
+| -------------------------------------------- | ------ | -------------------------------------------------------------------------- |
+| [ct-code-reviewer](agents/ct-code-reviewer.md)     | Opus   | Senior code reviewer with stack-aware analysis and severity-based feedback |
+| [ct-github-workflow](agents/ct-github-workflow.md) | Sonnet | Git workflow assistant for branching, commits, and PR creation             |
+
+## Stack Skills
+
+Stack-specific skills activated based on your `claude-toolkit.config.ts` configuration.
+
+| Skill                                                          | Stack             | Description                                                                    |
+| -------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------ |
+| [ct-solidjs-patterns](stacks/solidjs-patterns.md)                 | `solidjs`         | Reactivity, signals, effects, component patterns, and props handling           |
+| [ct-vanilla-extract-patterns](stacks/vanilla-extract-patterns.md) | `vanilla-extract` | Type-safe CSS with zero runtime: styles, recipes, themes, sprinkles            |
+| [ct-rust-wasm-patterns](stacks/rust-wasm-patterns.md)             | `rust-wasm`       | Rust WASM for Cloudflare Workers: routing, handlers, env bindings              |
+| [ct-protobuf-contracts](stacks/protobuf-contracts.md)             | `protobuf`        | Protocol Buffers for API contracts: schema design, versioning, code generation |
+| [ct-cloudflare-d1-kv](stacks/cloudflare-d1-kv.md)                 | `cloudflare`      | D1 database and KV cache: queries, migrations, caching patterns                |
+| [ct-i18n-typesafe](stacks/i18n-typesafe.md)                       | `i18n-typesafe`   | Type-safe internationalization with compile-time key checking                  |

package/docs/agents/code-reviewer.md

@@ -0,0 +1,76 @@
+# Code Reviewer Agent
+
+> Senior code reviewer with stack-aware analysis.
+
+**Type:** Agent
+**Model:** Opus (highest capability)
+**Source:** [`core/agents/ct-code-reviewer.md`](../core/agents/ct-code-reviewer.md)
+
+## Overview
+
+A senior code reviewer agent that thoroughly reviews code changes, providing actionable feedback organized by severity. It adapts review criteria to the project's stack and conventions.
+
+## Review Process
+
+1. **Read the full diff** and all changed files in their entirety -- understands surrounding context, not just changed lines
+2. **Identify the stack** by reading project config files -- adapts criteria accordingly
+3. **Apply the review checklist** to every changed file
+4. **Compile findings** with severity levels and specific file/line references
+
+## Review Checklist
+
+### Critical Issues
+
+| Category | Checks |
+| --- | --- |
+| **Logic Correctness** | Off-by-one errors, inverted conditions, unhandled edge cases, race conditions, incorrect state transitions, dead code |
+| **Error Handling** | Swallowed errors, missing context in error messages, leaked resources, unhandled crashes, missing error boundaries |
+| **Security** | SQL/XSS/command injection, missing auth, secrets in code, CORS issues, missing rate limiting |
+
+### Warnings
+
+| Category | Checks |
+| --- | --- |
+| **Type Safety** | `any` usage, unsafe casts, missing null checks, implicit coercions, overly broad generics |
+| **Performance** | Unnecessary re-renders, N+1 queries, missing pagination, sync-when-should-be-async, memory leaks |
+| **Testing** | New behavior without tests, implementation-detail tests, missing edge cases, flaky patterns |
+
+### Suggestions
+
+| Category | Checks |
+| --- | --- |
+| **Naming and Readability** | Misleading names, abbreviations, functions doing too much, deep nesting, comments describing "what" instead of "why" |
+
+## Output Format
+
+```markdown
+## Code Review
+
+**Reviewed:** {files or PR description}
+**Verdict:** APPROVE | REQUEST_CHANGES | COMMENT
+
+### Critical ({count})
+### Warnings ({count})
+### Suggestions ({count})
+### Looks Good
+### Summary
+```
+
+## Best Practices Reference
+
+Stack-aware review informed by these guides:
+
+| Review Area | Guide |
+| --- | --- |
+| `any` usage, type safety patterns | [any & unknown](../best-practices/typescript/any-and-unknown.md) |
+| `type` vs `interface` conventions | [Type vs Interface](../best-practices/typescript/type-vs-interface.md) |
+| SolidJS-specific mistakes (destructuring, effects) | [SolidJS Anti-Patterns](../best-practices/solidjs/anti-patterns.md) |
+| Props reactivity issues | [SolidJS Props Patterns](../best-practices/solidjs/props-patterns.md) |
+
+## Principles
+
+- **Be specific** -- "This catch block on line 42 swallows the database connection error" is useful; "This could be improved" is not
+- **Distinguish severity honestly** -- not everything is critical, not everything is a suggestion
+- **Acknowledge good work** -- reviews that only list problems are incomplete
+- **Stay in scope** -- review the changes, not the entire codebase
+- **Offer alternatives, not just objections** -- suggest a fix or direction for every problem flagged

package/docs/agents/github-workflow.md

@@ -0,0 +1,98 @@
+# GitHub Workflow Agent
+
+> Git workflow assistant for branching, commits, and PRs.
+
+**Type:** Agent
+**Model:** Sonnet
+**Source:** [`core/agents/ct-github-workflow.md`](../core/agents/ct-github-workflow.md)
+
+## Overview
+
+A Git workflow assistant that helps with branch management, commit formatting, and pull request creation following consistent conventions.
+
+## Branch Naming
+
+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:** lowercase with hyphens, under 4 words, specific enough to identify at a glance.
+
+## Conventional Commits
+
+Format: `{type}({scope}): {description}`
+
+| 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
+chore(deps): upgrade next.js to 15.1
+```
+
+**Rules:**
+- Scope is optional but encouraged (module or feature area)
+- Description starts lowercase, imperative mood ("add" not "added")
+- Body explains "why" not "what"
+- Breaking changes: add `!` after type/scope (e.g., `feat(api)!: change auth response format`)
+
+## PR Creation Workflow
+
+### 1. Pre-flight Checks
+- Tests pass
+- Types check
+- No lint errors
+- No merge conflicts
+
+### 2. PR Title
+Same conventional format as commits, under 70 characters.
+
+### 3. PR Description
+```markdown
+## Summary
+{1-3 bullet points: what and why}
+
+## Changes
+- {Grouped list of meaningful changes}
+
+## Testing
+- [ ] {How to test}
+- [ ] {Edge cases verified}
+
+## Notes
+{Trade-offs, follow-up work, deployment considerations}
+```
+
+### 4. Pre-Open Checklist
+- Branch up to date with base
+- All tests pass
+- Types check cleanly
+- No lint errors
+- PR title follows conventional format
+- Changes are focused (one concern per PR)
+
+## Principles
+
+- **Small PRs** -- if a PR touches more than 10 files or 300 lines, consider splitting
+- **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
+- **PR description is for the reviewer** -- write it to save their time

package/docs/best-practices/solidjs/README.md

@@ -0,0 +1,43 @@
+# SolidJS Best Practices
+
+> A curated collection of SolidJS best practices, patterns, and guidance sourced from the [official SolidJS documentation](https://docs.solidjs.com/), [Ryan Carniato](https://dev.to/ryansolid) (SolidJS creator), and the SolidJS community.
+
+SolidJS uses **fine-grained reactivity** with no virtual DOM. Components run once; only reactive expressions re-execute when dependencies change. This is fundamentally different from virtual DOM frameworks — and most best practices stem from this core difference.
+
+## Reactivity
+
+Understanding reactivity is the foundation of everything in Solid.
+
+| Guide | Summary |
+|---|---|
+| [Reactivity Model](reactivity-model.md) | How fine-grained reactivity works — signals, tracking, subscriptions. |
+| [Signals & State](signals-and-state.md) | `createSignal`, `createMemo`, derived values, and when to use what. |
+| [Stores & Nested State](stores-and-nested-state.md) | `createStore`, path syntax, `produce`, `reconcile` for complex state. |
+| [Effects & Lifecycle](effects-and-lifecycle.md) | `createEffect`, `onMount`, `onCleanup` — and when NOT to use effects. |
+
+## Components
+
+Patterns for building and composing components.
+
+| Guide | Summary |
+|---|---|
+| [Props Patterns](props-patterns.md) | Never destructure. Use `mergeProps`, `splitProps`, `children` helper. |
+| [Component Patterns](component-patterns.md) | Composition, typed components, generic components, refs. |
+| [Control Flow](control-flow.md) | `<Show>`, `<For>`, `<Switch>`/`<Match>`, `<ErrorBoundary>`, `<Suspense>`. |
+
+## Architecture
+
+Scaling patterns for real applications.
+
+| Guide | Summary |
+|---|---|
+| [Data Fetching](data-fetching.md) | `createResource`, `createAsync`, Suspense, error handling, optimistic updates. |
+| [Context & Global State](context-and-global-state.md) | Context + stores pattern, provider factories, avoiding prop drilling. |
+| [TypeScript Integration](typescript-integration.md) | Component types, typed signals/stores/context, event handling, TSConfig. |
+
+## Performance & Pitfalls
+
+| Guide | Summary |
+|---|---|
+| [Performance](performance.md) | `lazy`, `batch`, `untrack`, code splitting, and what Solid optimizes for you. |
+| [Anti-Patterns](anti-patterns.md) | The most common mistakes and how to avoid them. |