claude-toolkit 0.1.9

package/docs/skills/typescript-conventions.md

@@ -0,0 +1,137 @@
+# TypeScript Conventions
+
+> Strict TypeScript patterns for type safety, readability, and maintainable codebases.
+
+**Type:** Core Skill (always included)
+**Source:** [`core/skills/typescript-conventions/SKILL.md`](../core/skills/typescript-conventions/SKILL.md)
+
+## Overview
+
+Rules for writing TypeScript that leverages the type system fully. These assume strict mode is enabled and prioritize catching errors at compile time over runtime.
+
+## Key Patterns
+
+### Strict Mode
+
+Enable all strict checks in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}
+```
+
+Never disable strict checks for convenience.
+
+### No `any`
+
+Never use `any`. It disables type checking entirely.
+
+- Use `unknown` when the type is genuinely not known, then narrow before use
+- Use generics when the type varies but has a consistent shape
+- Use specific types when you know the data shape
+
+### Interface vs Type
+
+- **Prefer `interface`** for object shapes -- extendable, clearer error messages
+- **Use `type`** for unions, intersections, mapped types, and utility types
+
+```typescript
+// Object shape: use interface
+interface User {
+  id: string;
+  email: string;
+  role: UserRole;
+}
+
+// Union: use type
+type UserRole = "admin" | "member" | "guest";
+```
+
+### `as const` for Literal Types
+
+Use `as const` to narrow literal values and create readonly tuples:
+
+```typescript
+const ROLES = ["admin", "member", "guest"] as const;
+type Role = (typeof ROLES)[number]; // "admin" | "member" | "guest"
+```
+
+### Exhaustive Switch with `never`
+
+Handle every case in a switch and use `never` to catch missing branches at compile time:
+
+```typescript
+function getPermissions(role: UserRole): string[] {
+  switch (role) {
+    case "admin":
+      return ["read", "write", "delete"];
+    case "member":
+      return ["read", "write"];
+    case "guest":
+      return ["read"];
+    default: {
+      const _exhaustive: never = role;
+      throw new Error(`Unhandled role: ${_exhaustive}`);
+    }
+  }
+}
+```
+
+### Discriminated Unions for State Modeling
+
+Model states with different associated data as discriminated unions to make illegal states unrepresentable:
+
+```typescript
+type AsyncState<T> =
+  | { status: "loading" }
+  | { status: "success"; data: T }
+  | { status: "error"; error: Error };
+```
+
+### Generic Constraints
+
+Use `extends` to constrain generics, documenting expectations and catching misuse:
+
+```typescript
+function findById<T extends { id: string }>(items: T[], id: string): T | undefined {
+  return items.find((item) => item.id === id);
+}
+```
+
+## Anti-patterns
+
+| Anti-pattern | Description |
+|---|---|
+| **Type assertions (`as`)** | Tells the compiler "trust me" -- use type guards and narrowing instead. |
+| **Non-null assertion (`!`)** | Suppresses null checks. Handle the null case explicitly. |
+| **Enum overuse** | Prefer string literal unions. Enums generate runtime code and have surprising behavior. |
+| **`Object`, `Function`, `{}`** | Almost never what you want. Use specific interfaces or function signatures. |
+| **`@ts-ignore`** | Suppressing errors without tracking means the error will be forgotten. |
+
+## Best Practices Reference
+
+For deeper guidance on the patterns referenced above (sourced from Matt Pocock / Total TypeScript):
+
+| Topic | Guide |
+|---|---|
+| Default to `type`, use `interface` for `extends` | [Type vs Interface](../best-practices/typescript/type-vs-interface.md) |
+| Why enums are problematic, `as const` alternative | [Enums & Alternatives](../best-practices/typescript/enums-alternatives.md) |
+| When `any` is acceptable (two exceptions) | [any & unknown](../best-practices/typescript/any-and-unknown.md) |
+| State modeling with discriminated unions | [Discriminated Unions](../best-practices/typescript/discriminated-unions.md) |
+| Three patterns for generics | [Generics Patterns](../best-practices/typescript/generics-patterns.md) |
+| Recommended `tsconfig.json` settings | [TSConfig Cheat Sheet](../best-practices/typescript/tsconfig-cheat-sheet.md) |
+| Branded types, assertion functions, type predicates | [Essential Patterns](../best-practices/typescript/essential-patterns.md) |
+
+See the full collection: [TypeScript Best Practices](../best-practices/typescript/README.md)
+
+## Trigger Conditions
+
+- **Keywords:** `typescript`, `type`, `interface`, `generic`
+- **File patterns:** `**/*.d.ts`, `**/types/**`
+- **Intent patterns:** "define/create type/interface"

package/docs/skills/verification-before-completion.md

@@ -0,0 +1,91 @@
+# Verification Before Completion
+
+> Evidence-based completion claims -- never say "done" without proof that the work is correct.
+
+**Type:** Core Skill (always included)
+**Source:** [`core/skills/verification-before-completion/SKILL.md`](../core/skills/verification-before-completion/SKILL.md)
+
+## Overview
+
+The most common source of rework is claiming completion without verification. Every "done" claim must be backed by evidence that the code works correctly. "I wrote the code" is not evidence. "The tests pass, the types check, and here is the output" is evidence.
+
+## Verification Checklist
+
+### 1. Tests Pass
+
+Run the full test suite (or related tests) and show the output. If any test fails, fix it before claiming complete.
+
+### 2. Type Checks Pass
+
+Run the type checker with no errors (`tsc --noEmit` or equivalent). Zero errors, zero warnings on changed files.
+
+### 3. Linting Passes
+
+Run the project's linter on changed files. Fix any violations introduced by your changes.
+
+### 4. The Feature Actually Works
+
+For user-facing changes, demonstrate the feature works with actual output -- API responses, rendered UI, CLI output:
+
+```
+$ curl -s localhost:3000/api/users/1 | jq .
+{
+  "id": "1",
+  "name": "Alice",
+  "email": "alice@example.com"
+}
+```
+
+### 5. Edge Cases Verified
+
+Test boundaries and unusual inputs explicitly:
+
+- **Empty inputs** -- empty strings, empty arrays, null, undefined
+- **Boundary values** -- zero, negative numbers, maximum values, off-by-one
+- **Invalid inputs** -- wrong types, malformed data, missing required fields
+- **Concurrent access** -- simultaneous requests or operations
+- **Error paths** -- network failures, database errors, permission denied
+
+### 6. Regression Check
+
+- Run related tests, not just the tests you wrote
+- Check integration points if you changed a shared utility, API contract, or database schema
+- Smoke test the application if it has a running instance
+
+## Evidence Format
+
+When reporting completion, include concrete evidence:
+
+```markdown
+## Completed: User authentication endpoint
+
+### Tests
+- 12 tests passing (3 new, 9 existing)
+- `npm test -- --grep "auth"` output: all green
+
+### Type check
+- `tsc --noEmit`: 0 errors
+
+### Manual verification
+- POST /api/auth/login with valid credentials: 200 + JWT token
+- POST /api/auth/login with wrong password: 401 + error message
+- POST /api/auth/login with locked account: 423 + lockout message
+
+### Edge cases verified
+- Empty email: 400 validation error
+- SQL injection attempt in email: properly escaped, no error
+- Expired token refresh: 401 with clear message
+```
+
+## What This Prevents
+
+- **"It works on my machine" failures** -- evidence shows it works in a verifiable way
+- **Phantom completions** -- tasks marked done that are actually broken
+- **Regression blindness** -- catching breakage before it reaches review or production
+- **Incomplete implementations** -- edge cases and error handling are verified, not assumed
+
+## Trigger Conditions
+
+- **Keywords:** `verify`, `check`, `confirm`, `done`, `complete`
+- **Intent patterns:** "is it done", "verify it works"
+- **Context patterns:** "before claiming", "make sure"

package/docs/stacks/cloudflare-d1-kv.md

@@ -0,0 +1,110 @@
+# Cloudflare D1 and KV Patterns
+
+> Cloudflare D1 SQL database and KV cache patterns.
+
+**Type:** Stack Skill (requires `cloudflare` stack)
+**Source:** [`stacks/cloudflare/skills/cloudflare-d1-kv/SKILL.md`](../stacks/cloudflare/skills/cloudflare-d1-kv/SKILL.md)
+**Directory Mappings:** `src/db/`, `migrations/`
+**File Extensions:** `.sql`
+
+## Overview
+
+D1 is Cloudflare's serverless SQLite database, and KV is an eventually-consistent key-value store. Together they provide primary data storage and read-heavy caching for Workers.
+
+## D1 Database
+
+### Prepared Statements
+
+Always use prepared statements with `.bind()` -- never concatenate SQL strings.
+
+```rust
+let stmt = db.prepare("SELECT * FROM users WHERE id = ?1")
+    .bind(&[id.into()])?;
+let user = stmt.first::<User>(None).await?;
+```
+
+### Batch Operations
+
+Execute multiple statements in a single round trip. Batch operations are transactional -- all succeed or all fail.
+
+```rust
+let results = db.batch(vec![
+    db.prepare("INSERT INTO events ...").bind(&[...])?,
+    db.prepare("INSERT INTO event_members ...").bind(&[...])?,
+]).await?;
+```
+
+### Migration Workflow
+
+```bash
+wrangler d1 migrations create DB "add_users_table"   # Create migration
+wrangler d1 migrations apply DB --local               # Apply locally
+wrangler d1 migrations apply DB --remote              # Apply to remote
+```
+
+### Schema Conventions
+
+- Use `TEXT` for IDs (UUIDs/nanoids, not auto-increment integers)
+- Use `TEXT` for timestamps in ISO 8601 format
+- Always add `created_at` and `updated_at` columns
+- Create indexes for columns used in WHERE clauses and JOINs
+- Use `IF NOT EXISTS` / `IF EXISTS` for idempotent migrations
+- D1 has a **5MB response size limit** -- always use LIMIT
+
+## KV Namespace
+
+### Read-Through Caching Pattern
+
+```rust
+async fn get_user_cached(kv: &KvStore, db: &D1Database, user_id: &str) -> Result<User> {
+    let cache_key = format!("user:{}", user_id);
+
+    // Try cache first
+    if let Some(cached) = kv.get(&cache_key).text().await? {
+        if let Ok(user) = serde_json::from_str::<User>(&cached) {
+            return Ok(user);
+        }
+    }
+
+    // Cache miss -- query DB, then populate cache with TTL
+    let user = /* query D1 */;
+    kv.put(&cache_key, &json)?.expiration_ttl(3600).execute().await?;
+    Ok(user)
+}
+```
+
+### TTL Strategies
+
+| Data Type | TTL | Rationale |
+|---|---|---|
+| User profile | 1 hour | Changes infrequently |
+| Session data | 24 hours | Matches session lifetime |
+| Config/settings | 5 minutes | Needs faster propagation |
+| Public listings | 15 minutes | Balances freshness and load |
+
+### Key Naming Conventions
+
+Use colon-separated hierarchical keys:
+```
+user:{userId}
+user:{userId}:profile
+event:{eventId}
+event:{eventId}:members
+session:{sessionToken}
+cache:feed:{userId}:page:{pageNum}
+```
+
+### Cache Invalidation
+
+Invalidate on write operations by deleting the corresponding cache key after updating D1.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong |
+|---|---|
+| **Unbounded queries** | Always use LIMIT. D1 has a 5MB response limit. |
+| **Missing indexes** | D1 is SQLite; without indexes, every query is a full table scan. |
+| **KV as primary data store** | KV is eventually consistent with no query capability. Use D1 for primary data. |
+| **Ignoring batch operations** | Each D1 call is a network round trip. Batch for performance. |
+| **KV cache without TTL** | Stale data without TTL persists indefinitely. |
+| **Not testing migrations locally** | Always apply with `--local` before `--remote`. |

package/docs/stacks/i18n-typesafe.md

@@ -0,0 +1,141 @@
+# Typesafe-i18n Patterns
+
+> Typesafe-i18n internationalization patterns for SolidJS.
+
+**Type:** Stack Skill (requires `i18n-typesafe` stack)
+**Source:** [`stacks/i18n-typesafe/skills/i18n-typesafe/SKILL.md`](../stacks/i18n-typesafe/skills/i18n-typesafe/SKILL.md)
+**Directory Mappings:** `src/locales/`, `src/i18n/`
+
+## Overview
+
+typesafe-i18n provides fully type-safe translations with autocompletion. Translation keys are checked at compile time -- missing or misspelled keys cause TypeScript errors.
+
+## Setup
+
+### Directory Structure
+
+```text
+src/i18n/
+  i18n-types.ts       # Auto-generated types
+  i18n-util.ts         # Auto-generated utilities
+  i18n-solid.tsx       # SolidJS adapter
+  en/index.ts          # Base locale (source of truth)
+  fr/index.ts          # French translations
+```
+
+### Configuration (`.typesafe-i18n.json`)
+
+```json
+{
+  "baseLocale": "en",
+  "adapter": "solid",
+  "outputPath": "src/i18n/{locale}/"
+}
+```
+
+### Run the Generator
+
+```bash
+npx typesafe-i18n    # Watches base locale and regenerates types
+```
+
+## Base Locale
+
+The base locale is the source of truth. All types are derived from it.
+
+```ts
+// src/i18n/en/index.ts
+const en = {
+  common: {
+    welcome: 'Welcome, {name:string}!',
+    itemCount: '{count:number} {{item|items}}',
+    save: 'Save',
+  },
+  auth: {
+    signIn: 'Sign in',
+    signOut: 'Sign out',
+  },
+} satisfies BaseTranslation;
+```
+
+## Adding Translations
+
+Other locales use the `Translation` type derived from the base locale. Missing keys or wrong parameter types cause compile errors.
+
+```ts
+// src/i18n/fr/index.ts
+const fr = {
+  common: {
+    welcome: 'Bienvenue, {name} !',
+    itemCount: '{count} {{article|articles}}',
+    save: 'Enregistrer',
+  },
+  auth: {
+    signIn: 'Se connecter',
+    signOut: 'Se deconnecter',
+  },
+} satisfies Translation;
+```
+
+## Usage in Components
+
+```tsx
+const { LL } = useI18nContext();
+
+return (
+  <div>
+    <h1>{LL().events.title()}</h1>
+    <span>{LL().events.attendees({ count: event.memberCount })}</span>
+  </div>
+);
+```
+
+### Provider Setup
+
+```tsx
+<I18nProvider locale="en">
+  <Router />
+</I18nProvider>
+```
+
+## Parameterized Translations
+
+| Syntax                   | Example                      | Description              |
+| ------------------------ | ---------------------------- | ------------------------ |
+| `{name:string}`          | `'Hello {name:string}'`      | Named string parameter   |
+| `{count:number}`         | `'{count:number} items'`     | Named number parameter   |
+| `{{singular\|plural}}`   | `'{count} {{item\|items}}'`  | Plural forms             |
+| `{0:string}`             | `'Click {0:string}'`         | Positional parameter     |
+
+## Namespace Organization
+
+Organize translations by feature/domain. Keep namespaces flat (one level deep):
+
+```ts
+const en = {
+  common: { ... },    // Global
+  auth: { ... },       // Authentication
+  events: { ... },     // Events feature
+  profile: { ... },    // User profile
+  settings: { ... },   // Settings
+  admin: { ... },      // Admin panel
+};
+```
+
+## Anti-patterns
+
+| Anti-pattern                   | Why it's wrong                                                                  |
+| ------------------------------ | ------------------------------------------------------------------------------- |
+| **Hardcoded strings**          | Every user-visible string must go through `LL()`.                               |
+| **Missing translations**       | `Translation` type catches these at compile time -- run `tsc --noEmit` in CI.   |
+| **Interpolating HTML**         | Do not embed HTML in translation strings. Use component composition.            |
+| **Dynamic key access**         | `LL()[dynamicKey]()` bypasses type safety. Use conditional rendering.           |
+| **Forgetting to load locale**  | Call `loadLocale()` before rendering.                                           |
+| **Over-splitting namespaces**  | Too many small namespaces add overhead. Group by feature, not component.        |
+
+## Best Practices Reference
+
+| Topic                                    | Guide                                                                           |
+| ---------------------------------------- | ------------------------------------------------------------------------------- |
+| `satisfies` pattern used in translations | [The satisfies Operator](../best-practices/typescript/satisfies-operator.md)    |
+| i18n provider and context pattern        | [Context & Global State](../best-practices/solidjs/context-and-global-state.md) |

package/docs/stacks/protobuf-contracts.md

@@ -0,0 +1,85 @@
+# Protobuf Contracts
+
+> Protocol Buffer definitions and code generation for frontend/backend contracts.
+
+**Type:** Stack Skill (requires `protobuf` stack)
+**Source:** [`stacks/protobuf/skills/protobuf-contracts/SKILL.md`](../stacks/protobuf/skills/protobuf-contracts/SKILL.md)
+**Directory Mappings:** `proto/`
+**File Extensions:** `.proto`
+
+## Overview
+
+Protocol Buffers (proto3) define the API contract between frontend and backend. Protobuf provides compact binary serialization, type safety across languages, and backward-compatible schema evolution.
+
+## Proto3 Conventions
+
+- Use **PascalCase** for message names, **snake_case** for field names
+- Fields 1-15 use 1 byte (reserve for frequent fields), 16-2047 use 2 bytes
+- **Never reuse** a field number after removing a field
+- When removing fields, reserve the number AND name
+- Enums must always start with `UNSPECIFIED = 0`
+
+## Message Patterns
+
+### Request/Response Pairs
+```protobuf
+message GetUserRequest { string user_id = 1; }
+message GetUserResponse { UserProfile user = 1; }
+```
+
+### Lists with Pagination
+```protobuf
+message ListEventsRequest {
+  int32 page_size = 1;
+  string page_token = 2;
+}
+message ListEventsResponse {
+  repeated Event events = 1;
+  string next_page_token = 2;
+  int32 total_count = 3;
+}
+```
+
+### Service Definitions
+```protobuf
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+}
+```
+
+## Code Generation
+
+| Target | Tool | Command |
+|---|---|---|
+| Frontend (TypeScript) | protoc-gen-ts | `buf generate --template buf.gen.ts.yaml` |
+| Backend (Rust) | prost-build | Via `build.rs` with `prost_build::Config` |
+
+## Buf CLI Commands
+
+| Command | Purpose |
+|---|---|
+| `buf lint` | Lint proto files |
+| `buf format -w` | Format in place |
+| `buf breaking --against .git#branch=main` | Check for breaking changes |
+| `buf generate` | Run code generation |
+
+## Versioning Rules
+
+1. **Never remove or renumber fields** -- use `reserved` instead
+2. **Never change a field type** -- add a new field with the correct type
+3. **Enum values are forever** -- 0 must always be UNSPECIFIED
+4. **Adding fields is safe** -- new fields get default values in old clients
+5. **Run `buf breaking` before merging** -- catch breaking changes in CI
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong |
+|---|---|
+| **Reusing field numbers** | Causes data corruption. Always reserve removed field numbers. |
+| **Overly nested messages** | Deep nesting hurts readability and evolution. Flatten where practical. |
+| **Missing UNSPECIFIED enum** | Proto3 requires 0 as default. Without UNSPECIFIED, 0 maps to a real value. |
+| **Using proto2 syntax** | Always use proto3 for new projects. |
+| **Skipping buf lint** | Inconsistent naming compounds over time. |
+| **Large messages** | Protobuf is not designed for multi-MB payloads. Use streaming or chunking. |

package/docs/stacks/rust-wasm-patterns.md

@@ -0,0 +1,106 @@
+# Rust WASM Patterns
+
+> Rust WASM patterns for Cloudflare Workers with worker-rs.
+
+**Type:** Stack Skill (requires `rust-wasm` stack)
+**Source:** [`stacks/rust-wasm/skills/rust-wasm-patterns/SKILL.md`](../stacks/rust-wasm/skills/rust-wasm-patterns/SKILL.md)
+**Directory Mappings:** `worker/`, `worker/src/`
+**File Extensions:** `.rs`, `.toml`
+
+## Overview
+
+Cloudflare Workers can run Rust compiled to WebAssembly via the `worker` crate (worker-rs). The target is `wasm32-unknown-unknown`. Workers handle HTTP requests at the edge with low latency.
+
+## Project Structure
+
+```
+worker/
+  Cargo.toml
+  src/
+    lib.rs          # Entry point with main router
+    routes/
+    models/
+    error.rs        # Custom error types
+  wrangler.toml     # Cloudflare config
+```
+
+## Key Patterns
+
+### Request Routing
+
+```rust
+#[event(fetch)]
+async fn fetch(req: Request, env: Env, _ctx: Context) -> Result<Response> {
+    Router::new()
+        .get_async("/api/users/:id", get_user)
+        .post_async("/api/users", create_user)
+        .run(req, env)
+        .await
+}
+```
+
+### Handler Pattern
+
+```rust
+async fn get_user(req: Request, ctx: RouteContext<()>) -> Result<Response> {
+    let id = ctx.param("id")
+        .ok_or_else(|| Error::RustError("Missing id parameter".into()))?;
+    let db = ctx.env.d1("DB")?;
+    // ...
+}
+```
+
+### Error Handling
+
+Define a custom `AppError` enum that converts to `worker::Error`:
+
+```rust
+pub enum AppError {
+    NotFound(String),
+    BadRequest(String),
+    Internal(String),
+    Unauthorized,
+}
+
+impl From<AppError> for WorkerError { ... }
+```
+
+### Env Bindings
+
+Access Cloudflare services through the `Env` object:
+
+| Binding | Access |
+|---|---|
+| D1 Database | `env.d1("DB")?` |
+| KV Namespace | `env.kv("MY_KV")?` |
+| R2 Bucket | `env.bucket("MY_BUCKET")?` |
+| Secrets | `env.secret("API_KEY")?.to_string()` |
+| Variables | `env.var("CONFIG_VAR")?.to_string()` |
+
+### Serde for JSON
+
+Use `#[derive(Serialize, Deserialize)]` for request/response types. Parse request bodies with `req.json().await?` and respond with `Response::from_json(&data)`.
+
+## Cargo.toml Essentials
+
+```toml
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+worker = "0.4"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+console_error_panic_hook = "0.1"
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong |
+|---|---|
+| **Panics in production** | Always use `Result`. `unwrap()` and `expect()` crash the worker. |
+| **Blocking operations** | WASM is single-threaded. All I/O must be `async`. |
+| **Large binary sizes** | Keep dependencies minimal. Target under 1MB compressed. |
+| **Ignoring memory limits** | Workers have 128MB memory. Stream large files, don't buffer. |
+| **Raw SQL string concatenation** | Always use prepared statements with `bind()`. |
+| **Missing CORS headers** | Workers serving APIs must handle OPTIONS preflight requests. |