claude-toolkit 0.10.0 → 0.15.0

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

@@ -17,6 +17,7 @@
 		"config": {
 			"type": "object",
 			"description": "Global configuration options",
+			"additionalProperties": false,
 			"required": ["minConfidenceScore", "showMatchReasons", "maxSkillsToShow"],
 			"properties": {
 				"minConfidenceScore": {
@@ -39,6 +40,7 @@
 		"scoring": {
 			"type": "object",
 			"description": "Points assigned to each match type",
+			"additionalProperties": false,
 			"required": [
 				"keyword",
 				"keywordPattern",
@@ -68,6 +70,7 @@
 			"description": "Skill definitions and their triggers",
 			"additionalProperties": {
 				"type": "object",
+				"additionalProperties": false,
 				"required": ["description", "triggers"],
 				"properties": {
 					"description": { "type": "string" },
@@ -79,6 +82,7 @@
 					},
 					"triggers": {
 						"type": "object",
+						"additionalProperties": false,
 						"properties": {
 							"keywords": { "type": "array", "items": { "type": "string" } },
 							"keywordPatterns": {

package/core/skills/ct-code-style/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: ct-code-style
+description: Code structure & style — guard clauses, lookup tables, destructuring, no classes, no magic values
+---
+
+# Code Style
+
+Write small, flat, data-driven functions. These conventions apply to all JS/TS. Stack skills override where noted below.
+
+## Guard clauses / early returns
+
+Return early on edge cases; never nest the happy path inside `else`.
+
+```ts
+// Bad — nested, else-heavy
+const price = (user) => {
+  if (user) {
+    if (user.active) {
+      return user.plan.price;
+    } else {
+      return 0;
+    }
+  } else {
+    return 0;
+  }
+};
+
+// Good — guard clauses, flat
+const price = (user) => {
+  if (!user) return 0;
+  if (!user.active) return 0;
+  return user.plan.price;
+};
+```
+
+Rule: no `else` / `else if` after a `return`.
+
+## Lookup tables over chained conditionals
+
+```ts
+// Bad
+const getDiscount = (type) => {
+  if (type === "student") return 0.1;
+  else if (type === "senior") return 0.15;
+  else if (type === "employee") return 0.2;
+  else return 0;
+};
+
+// Good
+const getDiscount = (type) => {
+  const discounts = { student: 0.1, senior: 0.15, employee: 0.2 };
+  return discounts[type] ?? 0;
+};
+```
+
+For an exhaustive **typed** union where every case must be handled, prefer an exhaustive `switch` — see `ct-typescript-conventions`.
+
+## Ternaries — one level, never nested
+
+A ternary must not contain another ternary. Nesting → extract a lookup table or guard clauses.
+
+```ts
+// Bad — nested ternary
+const label = a ? "x" : b ? "y" : "z";
+
+// Good — lookup or guards
+const labels = { a: "x", b: "y" };
+const label = labels[key] ?? "z";
+```
+
+## Destructuring — use it fully
+
+```ts
+const { id, name: title, role = "guest", address: { city } = {}, ...rest } = user;
+//       basic  rename        default         nested (+ default)        rest
+const greet = ({ name, lang = "en" }) => `${GREETING[lang]} ${name}`; // in params
+```
+
+**⚠️ Never destructure reactive framework props.** In SolidJS, `const { value } = props` breaks reactivity — read `props.value` at the point of use. This carve-out is authoritative: see `ct-solidjs-patterns`. Destructuring is for plain data objects.
+
+## Functions — arrow-only, no `class`, no `this`
+
+Model behavior as functions and closures over state. No `class`, no `this` in your own code.
+
+```ts
+// Bad — class + this
+class Counter {
+  count = 0;
+  inc() {
+    this.count++;
+  }
+}
+
+// Good — closure
+const makeCounter = () => {
+  let count = 0;
+  return { inc: () => ++count, value: () => count };
+};
+```
+
+**⚠️ Exception:** use `class` / `this` only when a third-party lib or platform leaves no functional alternative — e.g. Cloudflare Durable Objects / `WorkerEntrypoint` (`export class Room extends DurableObject`), or subclassing built-ins (`class AppError extends Error`). See `ct-cloudflare-d1-kv`.
+
+## No magic numbers or strings
+
+Name every literal that carries meaning. User-facing text → i18n keys, never inline strings.
+
+```ts
+// Bad
+if (retries > 3) show("Trop de tentatives");
+
+// Good
+const MAX_RETRIES = 3;
+if (retries > MAX_RETRIES) show(LL.errors.tooManyRetries()); // i18n key, not a literal
+```
+
+User-facing strings belong in the locale layer — see `ct-i18n-typesafe`.
+
+## Anti-Patterns
+
+| Bad | Good |
+| --- | --- |
+| `else` after a `return` | guard clauses |
+| `if/else if` chain on a value | object lookup table + `??` |
+| nested ternary | lookup table or guards |
+| `class` + `this` for your own logic | arrow functions + closures |
+| destructuring SolidJS `props` | read `props.x` (see `ct-solidjs-patterns`) |
+| magic number / inline UI string | named const / i18n key |
+
+## See Also
+
+- `ct-typescript-conventions` — exhaustive `switch` for typed unions; typing destructured params.
+- `ct-esnext-idioms` — modern features these patterns pair with (`??`, `Object.groupBy`).
+- `ct-solidjs-patterns` — props are reactive; do not destructure them.
+- `ct-i18n-typesafe` — where user-facing strings live.

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

@@ -1,6 +1,6 @@
 ---
 name: ct-systematic-debugging
-description: Four-phase methodology for diagnosing and fixing bugs efficiently without guesswork.
+description: Four-phase methodology for diagnosing and fixing bugs efficiently without guesswork. Use when investigating a bug, test failure, or unexpected behavior before proposing a fix
 ---
 
 # Systematic Debugging

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

@@ -1,6 +1,6 @@
 ---
 name: ct-testing-patterns
-description: Generic test-driven development practices and patterns applicable to any language or test framework.
+description: Generic test-driven development practices and patterns applicable to any language or test framework. Use when writing tests, setting up a test suite, or deciding what to test at which layer
 ---
 
 # Testing Patterns
@@ -28,6 +28,8 @@ description: Generic test-driven development practices and patterns applicable t
 | Interaction | ~20%         | Component variants, user interactions, accessibility, visual regression      |
 | E2E         | ~10%         | Critical user journeys, authentication flows, cross-page workflows           |
 
+> **Scope:** This core skill owns the layering _decision_ below, the unit and interaction layers, and the cross-cutting E2E principles. Runner-specific E2E setup and execution live in the stack skills (e.g. `ct-playwright-patterns`) when a matching stack is installed.
+
 ### When to Use Which Layer
 
 | Question                                          | Layer                                  |
@@ -103,13 +105,9 @@ bun test path/to/file.test.ts  # single file
 
 Bun supports `describe`, `it`/`test`, `expect`, lifecycle hooks, and snapshot testing out of the box with no additional dependencies.
 
-## Test Pyramid
-
-See 3-Layer Testing Strategy above. Many unit tests (fast, focused) > some interaction tests (component sandbox) > few E2E tests (full flow). Aim for 70/20/10 distribution.
-
 ## Test Speed
 
-Three levers recur across every runner (Vitest, Playwright, Storybook browser mode). Stated once here; each stack skill carries the framework-specific syntax.
+Three levers recur across common runners (Vitest, Playwright, Storybook browser mode). Stated once here; each stack skill carries the framework-specific syntax.
 
 - **Parallelism sized to the runner.** Enable file-level parallelism (Vitest `fileParallelism`, Playwright `fullyParallel`), but cap workers to the runner's *real* vCPUs (`"50%"` or a measured count). GitHub standard runners are 2 vCPU (private) / 4 (public); oversubscribing thrashes.
 - **Shard across CI jobs, then merge the blob reports.** Sharding splits at the *file* level (`--shard=i/n`), so wall-clock is gated by the slowest shard -- balance file sizes. Always emit a blob report per shard (`--reporter=blob`) and merge it (`merge-reports` / `--merge-reports`) in a dependent job, or results and coverage are fragmented and incomplete.
@@ -117,7 +115,7 @@ Three levers recur across every runner (Vitest, Playwright, Storybook browser mo
 
 Profile before tuning, and never `sleep` to mask timing -- use the framework's auto-waiting (see Shared Principles).
 
-Per-runner config: `ct-vite-vitest-patterns`, `ct-playwright-patterns`, `ct-storybook-patterns`.
+Per-runner config, if the corresponding stack is installed: `ct-vite-vitest-patterns`, `ct-playwright-patterns`, `ct-storybook-patterns`.
 
 ## Anti-Patterns
 

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

@@ -1,6 +1,6 @@
 ---
 name: ct-typescript-conventions
-description: Strict TypeScript patterns for type safety, readability, and maintainable codebases.
+description: Strict TypeScript patterns for type safety, readability, and maintainable codebases. Use when writing or reviewing TypeScript, adding or tightening types, or deciding between type and interface
 ---
 
 # TypeScript Conventions
@@ -10,7 +10,7 @@ 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.
+- **Default to `type`.** Use `interface` only when you need `extends` (object inheritance). `type` aliases have an implicit index signature, so they stay assignable to `Record<string, unknown>`; interfaces do not.
 - **`as const`** for literal types and readonly tuples.
 - **Never disable strict checks.** Hard-to-type code = design issue.
 
@@ -42,19 +42,21 @@ type AsyncState<T> =
 
 ## `satisfies` Operator
 
-Validate a value matches a type without widening it. Preserves the narrowest inferred type while ensuring conformance.
+Validate a value conforms to a type while keeping the *narrowest inferred type* per property, instead of widening every property to the target's value type (as an explicit annotation would). Against a union-typed target, the matching literal is preserved.
 
 ```typescript
-type Route = { path: string; children?: Route[] };
-
-const routes = {
-  home: { path: "/" },
-  user: { path: "/user/:id", children: [{ path: "settings" }] },
-} satisfies Record<string, Route>;
-
-// routes.home.path is still "/" (literal), not string
+const config = {
+  mode: "production",
+  level: 3,
+} satisfies { mode: "development" | "production"; level: number };
+
+// config.mode is the literal "production" (not widened to string),
+// because the target property is a union of literals. A plain
+// annotation `const config: {...}` would widen it to the full union.
 ```
 
+Note: `satisfies` does not by itself narrow to literals against a _wide_ target -- e.g. `satisfies Record<string, string>` still infers `string` for each value, and `satisfies Record<string, { path: string }>` leaves each `path` as `string`. Combine with `as const` when you need literals preserved against a `string`-typed target.
+
 ## `const` Type Parameters
 
 Infer literal types from arguments without requiring callers to write `as const`:
@@ -68,6 +70,8 @@ function createConfig<const T extends readonly string[]>(names: T): Record<T[num
 const flags = createConfig(["debug", "verbose"]);
 ```
 
+The `as Record<T[number], boolean>` above is the narrow exception to anti-pattern #1: `Object.fromEntries` is typed to return a wide `Record<string, boolean>`, so a localized cast _at a generic helper's return_ -- where the signature already proves the tighter type -- is acceptable. Reach for type guards everywhere else.
+
 ## Template Literal Types
 
 Build precise string types from unions:

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

@@ -1,6 +1,6 @@
 ---
 name: ct-verification-before-completion
-description: Evidence-based completion claims -- never say "done" without proof that the work is correct.
+description: Evidence-based completion claims -- never say "done" without proof that the work is correct. Use when about to claim a task is done, fixed, or passing, or before committing or opening a PR
 ---
 
 # Verification Before Completion
@@ -21,6 +21,7 @@ Before claiming complete, run and show output for each:
 - Empty inputs (empty string, empty array, null, undefined)
 - Boundary values (zero, negative, max, off-by-one)
 - Invalid inputs (wrong types, malformed data, missing fields)
+- Concurrent access (simultaneous requests or operations)
 - Error paths (network failure, permission denied)
 
 Do not assume edge cases work because the happy path works.

package/docs/README.md

@@ -16,6 +16,7 @@ Skills that are always included regardless of stack configuration.
 | [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     |
+| [ct-code-style](skills/code-style.md)                                         | Code structure & style: guard clauses, lookup tables, no magic values       |
 
 ## Commands
 
@@ -55,3 +56,4 @@ Stack-specific skills activated based on your `claude-toolkit.config.ts` configu
 | [ct-playwright-patterns](stacks/playwright-patterns.md)           | `playwright`      | E2E testing with Page Objects, fixtures, auth, network mocking, CI/CD          |
 | [ct-storybook-patterns](stacks/storybook-patterns.md)             | `storybook`       | Interaction testing, CSF 3, play functions, a11y, visual regression            |
 | [ct-capacitor-ota](stacks/capacitor-ota.md)                       | `capacitor`       | Capacitor 8 native runtime and Capgo OTA live updates, channels, encryption    |
+| [ct-esnext-idioms](stacks/esnext-idioms.md)                       | `esnext`          | Modern ECMAScript runtime idioms: Temporal, iterator helpers, using, structuredClone |

package/docs/commands/code-quality.md

@@ -1,4 +1,4 @@
-# /code-quality
+# /ct:code-quality
 
 > Run code quality checks (lint, typecheck, format) on a directory or file.
 
@@ -9,7 +9,7 @@
 ## Usage
 
 ```bash
-/code-quality [path]
+/ct:code-quality [path]
 ```
 
 ## Workflow
@@ -29,12 +29,6 @@ The command produces a structured report with:
 - **Format Issues** -- table with file and status
 - **Summary** -- total issues across files with actionable suggestions
 
-## Best Practices Reference
-
-| Topic | Guide |
-| --- | --- |
-| Recommended `tsconfig.json` settings | [TSConfig Cheat Sheet](../best-practices/typescript/tsconfig-cheat-sheet.md) |
-
 ## Notes
 
 - Always uses the project's own configuration; does not impose external rules

package/docs/commands/onboard.md

@@ -1,4 +1,4 @@
-# /onboard
+# /ct:onboard
 
 > Systematically explore and understand a codebase area, module, or task context.
 
@@ -9,7 +9,7 @@
 ## Usage
 
 ```bash
-/onboard [area]
+/ct:onboard [area]
 ```
 
 If no area is specified, starts from the project root.
@@ -56,15 +56,6 @@ If no area is specified, starts from the project root.
 - {Things that are unclear or undocumented}
 ```
 
-## Best Practices Reference
-
-Conventions to look for during onboarding:
-
-| Topic | Guide |
-| --- | --- |
-| TypeScript conventions and patterns | [TypeScript Best Practices](../best-practices/typescript/README.md) |
-| SolidJS conventions and patterns | [SolidJS Best Practices](../best-practices/solidjs/README.md) |
-
 ## Notes
 
 - Prioritizes understanding over completeness -- deeply understand 5 key files rather than skim 50

package/docs/commands/pr-review.md

@@ -1,4 +1,4 @@
-# /pr-review
+# /ct:pr-review
 
 > Perform a checklist-based code review on the current PR or a specified PR number.
 
@@ -9,7 +9,7 @@
 ## Usage
 
 ```bash
-/pr-review [pr-number]
+/ct:pr-review [pr-number]
 ```
 
 If no PR number is provided, diffs the current branch against the base branch.
@@ -83,17 +83,6 @@ The command evaluates all changed files against these criteria:
 ### Summary
 ```
 
-## Best Practices Reference
-
-Review criteria informed by these guides:
-
-| Review Area | Guide |
-| --- | --- |
-| Type safety: `any` usage, unsafe casts | [any & unknown](../best-practices/typescript/any-and-unknown.md) |
-| State modeling with unions | [Discriminated Unions](../best-practices/typescript/discriminated-unions.md) |
-| SolidJS-specific issues (props, reactivity) | [SolidJS Anti-Patterns](../best-practices/solidjs/anti-patterns.md) |
-| Performance: re-renders, reactivity mistakes | [SolidJS Performance](../best-practices/solidjs/performance.md) |
-
 ## Notes
 
 - References specific file names and line numbers

package/docs/commands/pr-summary.md

@@ -1,4 +1,4 @@
-# /pr-summary
+# /ct:pr-summary
 
 > Generate a structured pull request summary from the current branch.
 
@@ -9,7 +9,7 @@
 ## Usage
 
 ```
-/pr-summary
+/ct:pr-summary
 ```
 
 ## Workflow

package/docs/commands/proto-check.md

@@ -1,15 +1,15 @@
-# /proto-check
+# /ct:proto-check
 
 > Validate protobuf definitions for correctness, lint compliance, and backward compatibility.
 
 **Type:** Command (slash command)
-**Source:** [`core/commands/ct/proto-check.md`](../core/commands/ct/proto-check.md)
-**Allowed Tools:** Bash, Read, Glob, Grep
+**Source:** [`stacks/protobuf/commands/proto-check.md`](../stacks/protobuf/commands/proto-check.md) (installed only with the protobuf stack)
+**Allowed Tools:** Bash (scoped to `buf`/`protoc` and build commands), Read, Glob, Grep
 
 ## Usage
 
 ```
-/proto-check
+/ct:proto-check
 ```
 
 ## Workflow

package/docs/commands/ticket.md

@@ -1,4 +1,4 @@
-# /ticket
+# /ct:ticket
 
 > Work end-to-end on a ticket or issue: understand, explore, plan, implement, deliver.
 
@@ -9,7 +9,7 @@
 ## Usage
 
 ```
-/ticket [issue-number-or-description]
+/ct:ticket [issue-number-or-description]
 ```
 
 ## Phases

package/docs/skills/code-style.md

@@ -0,0 +1,26 @@
+# Code Style
+
+> Code structure & style: guard clauses, lookup tables, destructuring, no classes, no magic values.
+
+**Type:** Core Skill (always included)
+**Source:** [`core/skills/ct-code-style/SKILL.md`](../../core/skills/ct-code-style/SKILL.md)
+
+## Overview
+
+Universal, target-independent conventions for writing small, flat, data-driven functions. Always active — no stack required. It complements `ct-typescript-conventions` (types) and `ct-esnext-idioms` (modern features). Stack skills win where they overlap.
+
+## Rules
+
+- **Guard clauses / early returns** — no `else`/`else if` after a `return`.
+- **Lookup tables** over `if/else if` chains keyed on a value (`discounts[type] ?? 0`).
+- **Ternaries** — one level, never nested.
+- **Full ES6 destructuring** — basic, renaming, defaults, nested, rest, in parameters.
+- **Arrow-only, no `class`, no `this`** — model behavior as functions + closures.
+- **No magic numbers/strings** — named constants; user-facing text → i18n keys.
+
+## Carve-outs (stack skills win)
+
+- **SolidJS props:** never destructure reactive `props` — it breaks reactivity. See [`ct-solidjs-patterns`](../best-practices/solidjs/props-patterns.md).
+- **Platform classes:** `class`/`this` only where a third-party lib/platform requires it (Cloudflare Durable Objects, `class X extends Error`).
+
+Three of these rules are additionally enforced by Biome in the scaffolded `biome.json` (`noUselessElse`, `noNestedTernary`, `useArrowFunction`). "No magic numbers" stays guidance-only — it is too noisy to enforce mechanically.

package/docs/skills/systematic-debugging.md

@@ -1,6 +1,6 @@
 # Systematic Debugging
 
-> Four-phase methodology for diagnosing and fixing bugs efficiently without guesswork.
+> Four-phase methodology for diagnosing and fixing bugs efficiently without guesswork. Use when investigating a bug, test failure, or unexpected behavior before proposing a fix
 
 **Type:** Core Skill (always included)
 **Source:** [`core/skills/ct-systematic-debugging/SKILL.md`](../core/skills/ct-systematic-debugging/SKILL.md)