claude-toolkit 0.16.0 → 0.17.0

package/docs/best-practices/typescript/tsconfig-cheat-sheet.md

@@ -1,160 +0,0 @@
-# TSConfig Cheat Sheet
-
-> Source: [The TSConfig Cheat Sheet](https://www.totaltypescript.com/tsconfig-cheat-sheet) — Matt Pocock
-
-## Base Options (Every Project)
-
-These belong in every `tsconfig.json`:
-
-```jsonc
-{
-  "compilerOptions": {
-    // Smooth over CJS/ESM interop differences
-    "esModuleInterop": true,
-
-    // Skip type-checking node_modules .d.ts files for performance
-    "skipLibCheck": true,
-
-    // Stable target — prefer over "esnext"
-    "target": "es2022",
-
-    // Allow importing .js and .json files
-    "allowJs": true,
-    "resolveJsonModule": true,
-
-    // Treat all files as modules (avoids redeclaration errors)
-    "moduleDetection": "force",
-
-    // Prevent unsafe TS features that break per-file transpilation
-    "isolatedModules": true,
-
-    // Enforce import type / export type syntax
-    "verbatimModuleSyntax": true
-  }
-}
-```
-
-## Strictness
-
-Enable all strict checks, plus two extras Matt considers essential:
-
-```jsonc
-{
-  "compilerOptions": {
-    // All strict type-checking options
-    "strict": true,
-
-    // Force checking array/object index access (prevents undefined bugs)
-    "noUncheckedIndexedAccess": true,
-
-    // Make the override keyword functional in classes
-    "noImplicitOverride": true
-  }
-}
-```
-
-Matt **deliberately excludes** noisier options like `noImplicitReturns`, `noUnusedLocals`, and `noUnusedParameters`. Add them only if your team wants them — they create friction during development.
-
-## When TypeScript Transpiles (tsc emits JS)
-
-```jsonc
-{
-  "compilerOptions": {
-    "module": "NodeNext",
-    "outDir": "dist"
-  }
-}
-```
-
-### For Published Libraries
-
-Add `.d.ts` generation so consumers get autocomplete:
-
-```jsonc
-{
-  "compilerOptions": {
-    "declaration": true
-  }
-}
-```
-
-### For Monorepo Packages
-
-```jsonc
-{
-  "compilerOptions": {
-    "composite": true,
-    "sourceMap": true,
-    "declarationMap": true
-  }
-}
-```
-
-## When TypeScript Does NOT Transpile (Linting Mode)
-
-When a bundler (Vite, esbuild, etc.) handles transpilation:
-
-```jsonc
-{
-  "compilerOptions": {
-    // Mimic bundler module resolution
-    "module": "preserve",
-
-    // Don't emit JS files
-    "noEmit": true
-  }
-}
-```
-
-## Environment-Specific `lib`
-
-**DOM environments** (browsers, SSR with DOM APIs):
-
-```jsonc
-{
-  "compilerOptions": {
-    "lib": ["es2022", "dom", "dom.iterable"]
-  }
-}
-```
-
-**Non-DOM environments** (Node.js CLIs, serverless, workers):
-
-```jsonc
-{
-  "compilerOptions": {
-    "lib": ["es2022"]
-  }
-}
-```
-
-## TypeScript 7 Delta
-
-> Not from the source cheat sheet — added for TypeScript 7 (GA 2026-07-08, `typescript@7.0.2`). See [ct-typescript-conventions](../../skills/typescript-conventions.md#tsconfigjson-under-ts7) for the full compiler-selection guidance.
-
-Everything above is TS7-compatible as written, with **two additions** required when the native compiler is in use:
-
-```jsonc
-{
-  "compilerOptions": {
-    // `types` defaults to [] from 6.0 onward. Without this, ambient
-    // globals (`process`, Bun's APIs) fail TS2591 even when
-    // @types/node IS installed. Name only packages you actually have —
-    // a missing one is TS2688.
-    "types": ["node"],
-
-    // `rootDir` defaults to "./" from 6.0 onward. With sources in src/
-    // AND an outDir set, emit fails TS5011 — and `--noEmit` will not
-    // warn you. Without an outDir it does not fire.
-    "rootDir": "./src"
-  }
-}
-```
-
-Both defaults changed in **6.0**, not 7.0 — verified identical on `typescript@6.0.3` and `7.0.2`. `rootDir` matters only when the project emits to an `outDir`; `types` matters always.
-
-`"types": ["*"]` restores the pre-6.0 catch-all behaviour on 6.x and 7.x, but is `TS2688` on 5.x — so it is not a safe value for a config shared across majors.
-
-TS7 also rejects options this sheet never recommends — `baseUrl`, `outFile`, `downlevelIteration`, `target: "es5"`, `module: "amd" | "umd" | "system"`, and `moduleResolution: "node" | "node10" | "classic"`. `ignoreDeprecations` does not silence them.
-
-The TypeScript website's [tsconfig reference](https://www.typescriptlang.org/tsconfig/) has not been updated for TS7 and still documents removed options.

package/docs/best-practices/typescript/type-organization.md

@@ -1,64 +0,0 @@
-# Type Organization
-
-> Source: [Where To Put Your Types in Application Code](https://www.totaltypescript.com/where-to-put-your-types-in-application-code) — Matt Pocock
-
-## Three Rules
-
-### Rule 1: Colocate Single-Use Types
-
-When a type is used in only one place, put it in the same file where it's used.
-
-```typescript
-// components/Avatar.tsx
-type AvatarProps = {
-  imageUrl: string;
-  name: string;
-};
-
-export function Avatar({ imageUrl, name }: AvatarProps) {
-  // ...
-}
-```
-
-Don't extract single-use types into separate files. It's low-cost to refactor later if the type grows in scope. Inlining is fine for truly single-use types.
-
-### Rule 2: Share Types Across Modules
-
-When a type serves multiple files, move it to a shared `*.types.ts` file at the appropriate level:
-
-- **App-wide types** → `src/types.ts` or `src/shared.types.ts`
-- **Folder-specific types** → `src/features/auth/auth.types.ts`
-
-This mirrors how you'd handle shared functions — keep them at the narrowest scope that covers all consumers.
-
-```
-src/
-├── types.ts                    # App-wide types
-├── features/
-│   ├── auth/
-│   │   ├── auth.types.ts       # Shared within auth feature
-│   │   ├── login.tsx
-│   │   └── signup.tsx
-│   └── billing/
-│       ├── billing.types.ts
-│       └── invoice.tsx
-```
-
-### Rule 3: Monorepo-Level Sharing
-
-In a monorepo, types used across multiple packages go in a dedicated shared package:
-
-```
-packages/
-├── types/                      # Shared types package
-│   └── src/
-│       └── index.ts
-├── web-app/
-│   └── src/
-└── api/
-    └── src/
-```
-
-## Core Principle
-
-Share types across the **smallest number of modules** that require them. Don't pre-extract types "just in case" — colocate by default and widen scope only when a second consumer appears.

package/docs/best-practices/typescript/type-vs-interface.md

@@ -1,80 +0,0 @@
-# Type vs Interface
-
-> Source: [Type vs Interface: Which Should You Use?](https://www.totaltypescript.com/type-vs-interface-which-should-you-use) — Matt Pocock
-
-## The Verdict
-
-**Default to `type`. Use `interface` only when you need `extends`.**
-
-This contradicts the official TypeScript team guidance (which defaults to `interface`), but Matt argues the tradeoffs favor `type` for most codebases.
-
-## Why Default to `type`
-
-### 1. Flexibility
-
-Type aliases can express unions, mapped types, and conditional types. Interfaces cannot.
-
-```typescript
-// Only possible with type
-type Result = Success | Failure;
-type Mapped = { [K in keyof T]: boolean };
-type Conditional = T extends string ? "yes" : "no";
-```
-
-### 2. Declaration Merging is Dangerous
-
-If you accidentally declare the same interface name twice in the same scope, TypeScript silently merges them — no error, no warning. You end up with a type that has extra properties you never intended.
-
-```typescript
-interface User {
-  name: string;
-}
-
-interface User {
-  age: number;
-}
-
-// User is now { name: string; age: number } — silently merged
-```
-
-With `type`, a duplicate name throws a compile error immediately.
-
-### 3. Implicit Index Signature
-
-Type aliases have an implicit index signature, making them assignable to `Record<PropertyKey, unknown>`. Interfaces do not, which causes unexpected errors when passing interface-typed objects to functions expecting `Record` types.
-
-## When to Use `interface`
-
-Use `interface` specifically for **object inheritance** with `extends`:
-
-```typescript
-interface Animal {
-  name: string;
-}
-
-interface Dog extends Animal {
-  breed: string;
-}
-```
-
-**Why?** `extends` makes TypeScript's type checker run slightly faster than `&` intersections. TypeScript caches interface relationships in an internal registry, optimizing repeated type checks.
-
-```typescript
-// Prefer this (faster)
-interface Dog extends Animal {
-  breed: string;
-}
-
-// Over this (slower)
-type Dog = Animal & {
-  breed: string;
-};
-```
-
-## Summary
-
-| Scenario | Use |
-|---|---|
-| Object shapes (no inheritance) | `type` |
-| Unions, mapped types, conditionals | `type` |
-| Object inheritance | `interface` with `extends` |

package/docs/commands/code-quality.md

@@ -1,36 +0,0 @@
-# /ct:code-quality
-
-> Run code quality checks (lint, typecheck, format) on a directory or file.
-
-**Type:** Command (slash command)
-**Source:** [`core/commands/ct/code-quality.md`](../core/commands/ct/code-quality.md)
-**Allowed Tools:** Bash, Read, Glob, Grep
-
-## Usage
-
-```bash
-/ct:code-quality [path]
-```
-
-## Workflow
-
-1. **Detect project tooling** -- reads `package.json`, `pyproject.toml`, `Makefile`, `Cargo.toml`, or equivalent to identify the linter, typechecker, and formatter configured in the project
-2. **Run linting** -- uses the project-configured linter (e.g., `eslint`, `ruff`, `clippy`, `golangci-lint`)
-3. **Run type checking** -- uses the project-configured typechecker (e.g., `tsc --noEmit`, `mypy`, `pyright`)
-4. **Run format checking** -- uses the project-configured formatter in check mode (e.g., `prettier --check`, `black --check`, `rustfmt --check`)
-5. **Compile results** -- produces a structured report
-
-## Output Format
-
-The command produces a structured report with:
-
-- **Lint Issues** -- table with file, line, rule, message, and severity
-- **Type Errors** -- table with file, line, and message
-- **Format Issues** -- table with file and status
-- **Summary** -- total issues across files with actionable suggestions
-
-## Notes
-
-- Always uses the project's own configuration; does not impose external rules
-- For monorepos, scopes checks to the target directory rather than the entire repo
-- If a tool is not configured, it is noted and skipped

package/docs/commands/onboard.md

@@ -1,63 +0,0 @@
-# /ct:onboard
-
-> Systematically explore and understand a codebase area, module, or task context.
-
-**Type:** Command (slash command)
-**Source:** [`core/commands/ct/onboard.md`](../core/commands/ct/onboard.md)
-**Allowed Tools:** Bash, Read, Glob, Grep
-
-## Usage
-
-```bash
-/ct:onboard [area]
-```
-
-If no area is specified, starts from the project root.
-
-## Workflow
-
-1. **Understand the scope** -- the user specifies an area (e.g., "the auth module", "the payments flow") or the entire repo
-2. **Read foundational files** -- `README.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `package.json`, config files, entry points
-3. **Map the architecture** -- directory structure, entry points, request/data flow, key abstractions, design patterns
-4. **Identify conventions** -- naming, error handling, testing patterns, state management
-5. **Understand dependencies** -- key external libraries, internal module boundaries, database schema
-6. **Ask clarifying questions** if ambiguities or undocumented conventions exist
-
-## 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}
-
-### Key Files
-| File | Purpose | Notes |
-
-### Data Flow
-{How a request/action flows through the system}
-
-### Conventions
-- **Naming:** {patterns observed}
-- **Error handling:** {approach}
-- **Testing:** {framework, patterns, location}
-
-### Questions / Gaps
-- {Things that are unclear or undocumented}
-```
-
-## Notes
-
-- Prioritizes understanding over completeness -- deeply understand 5 key files rather than skim 50
-- Notes what is NOT there (missing tests, docs, error handling) as well as what is
-- If onboarding for a specific task, focuses exploration on the relevant areas

package/docs/commands/pr-review.md

@@ -1,91 +0,0 @@
-# /ct:pr-review
-
-> Perform a checklist-based code review on the current PR or a specified PR number.
-
-**Type:** Command (slash command)
-**Source:** [`core/commands/ct/pr-review.md`](../core/commands/ct/pr-review.md)
-**Allowed Tools:** Bash, Read, Glob, Grep
-
-## Usage
-
-```bash
-/ct:pr-review [pr-number]
-```
-
-If no PR number is provided, diffs the current branch against the base branch.
-
-## Review Checklist
-
-The command evaluates all changed files against these criteria:
-
-### Logic Correctness
-
-- Conditionals and branches correct, no off-by-one errors
-- Edge cases handled (empty inputs, null values, boundary conditions)
-- Control flow matches intended behavior
-- No unreachable code paths
-
-### Type Safety
-
-- Precise types (no `any`, no unsafe casts, no overly broad unions)
-- Type narrowing used correctly before accessing properties
-- Generic constraints appropriate
-- Return types explicit where needed
-
-### Error Handling
-
-- Errors caught and handled meaningfully (not swallowed)
-- Error messages provide enough context for debugging
-- Error boundaries or fallbacks in place where needed
-- Cleanup logic (finally blocks, defer) correct
-
-### Test Coverage
-
-- New behaviors covered by tests
-- Tests focus on behavior, not implementation details
-- Edge cases and error paths tested
-- Test descriptions clear and descriptive
-
-### Performance
-
-- No unnecessary re-renders, recomputations, or allocations
-- No N+1 query patterns or missing pagination
-- No missing memoization for expensive operations
-- No potential memory leaks
-
-### Security
-
-- No injection vulnerabilities (SQL, XSS, command injection)
-- User inputs validated and sanitized
-- Auth checks present on protected operations
-- Secrets and sensitive data properly handled
-
-### Code Style
-
-- Naming follows project conventions
-- Code readable without excessive comments
-- Abstractions at the right level
-- No unnecessary duplication
-
-## Output Format
-
-```markdown
-## PR Review: {title}
-
-**Branch:** {branch} -> {base}
-**Files changed:** {count}
-**Verdict:** APPROVE | REQUEST_CHANGES | COMMENT
-
-### Critical Issues
-### Warnings
-### Suggestions
-### Positive Notes
-### Summary
-```
-
-## Notes
-
-- References specific file names and line numbers
-- Distinguishes between opinion and objective issues
-- Acknowledges good patterns, not just problems
-- Suggests splitting if the PR is too large to review effectively

package/docs/commands/pr-summary.md

@@ -1,50 +0,0 @@
-# /ct:pr-summary
-
-> Generate a structured pull request summary from the current branch.
-
-**Type:** Command (slash command)
-**Source:** [`core/commands/ct/pr-summary.md`](../core/commands/ct/pr-summary.md)
-**Allowed Tools:** Bash, Read
-
-## Usage
-
-```
-/ct:pr-summary
-```
-
-## Workflow
-
-1. **Identify the base branch** -- checks for `main` or `master`, uses `git merge-base` to find the common ancestor
-2. **Gather the diff** -- runs `git diff {base}...HEAD --stat` for overview and full diff for details
-3. **Gather commit history** -- runs `git log {base}...HEAD --oneline --no-merges`
-4. **Analyze changes** -- reads modified files to understand the "why" behind each change
-5. **Generate the summary**
-
-## Output Format
-
-```markdown
-## Summary
-{1-3 bullet points describing the high-level purpose}
-
-## What Changed
-
-### {Category} (e.g., "Authentication", "Database", "UI")
-- `{file}` - {what changed and why}
-
-## Impact Assessment
-- **Risk level:** low | medium | high
-- **Affected areas:** {list of features or systems impacted}
-- **Breaking changes:** none, or description
-- **Migration needed:** none, or description
-
-## Testing Notes
-- {How to test this change}
-- {Key scenarios to verify}
-```
-
-## Notes
-
-- Infers the "why" from commit messages, code comments, and the nature of changes
-- Groups related file changes under meaningful categories
-- Honest about risk level -- flags potential issues in Testing Notes
-- Designed to be scannable in under 60 seconds

package/docs/commands/proto-check.md

@@ -1,59 +0,0 @@
-# /ct:proto-check
-
-> Validate protobuf definitions for correctness, lint compliance, and backward compatibility.
-
-**Type:** Command (slash command)
-**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
-
-```
-/ct:proto-check
-```
-
-## Workflow
-
-1. **Find proto files** -- locates all `.proto` files and identifies buf configuration (`buf.yaml`, `buf.gen.yaml`)
-2. **Run lint checks** -- executes `buf lint` or the project-configured linter
-3. **Check for breaking changes** -- runs `buf breaking --against .git#branch=main` to detect backward-incompatible changes:
-   - Removing or renaming fields
-   - Changing field numbers or types
-   - Removing services or RPCs
-   - Changing RPC signatures
-4. **Regenerate types** -- runs `buf generate` or the project-configured generation command
-5. **Verify generated code compiles** -- runs the project's typecheck or build command
-6. **Report results**
-
-## Output Format
-
-```markdown
-## Protobuf Validation Report
-
-**Proto files found:** {count}
-**Buf config:** {path or "not found"}
-
-### Lint Results
-- **Status:** pass | fail
-- **Issues:** {count}
-
-### Breaking Change Check
-- **Status:** pass | fail
-- **Against:** {branch or reference}
-
-### Code Generation
-- **Status:** success | failure
-- **Files generated:** {count}
-
-### Compilation Check
-- **Status:** pass | fail
-
-### Summary
-{Overall status and recommended actions}
-```
-
-## Notes
-
-- Checks for alternative protobuf tooling (`protoc`, `grpc_tools`) if `buf` is not installed
-- Reports clearly if no proto files are found
-- Breaking changes are flagged for human review, not automatically treated as errors

package/docs/commands/ticket.md

@@ -1,56 +0,0 @@
-# /ct:ticket
-
-> Work end-to-end on a ticket or issue: understand, explore, plan, implement, deliver.
-
-**Type:** Command (slash command)
-**Source:** [`core/commands/ct/ticket.md`](../core/commands/ct/ticket.md)
-**Allowed Tools:** Bash, Read, Write, Edit, Glob, Grep
-
-## Usage
-
-```
-/ct:ticket [issue-number-or-description]
-```
-
-## Phases
-
-### Phase 1: Understand
-
-- Read the ticket (fetches via `gh issue view` if a GitHub issue number is provided)
-- Clarify requirements -- identify acceptance criteria, edge cases, and constraints
-- Identify scope -- what needs to change, what should NOT change
-
-### Phase 2: Explore
-
-- Find relevant code -- search for files, functions, and patterns related to the ticket
-- Understand the test landscape -- existing tests, framework, patterns, coverage
-- Check for related changes -- recent commits or PRs in the affected area
-
-### Phase 3: Plan
-
-- Draft an implementation plan listing specific changes needed:
-  - Files to create or modify
-  - Functions to add or change
-  - Tests to write
-  - Migrations or config changes
-- Share the plan with the user and get confirmation before proceeding
-
-### Phase 4: Implement
-
-- Create a feature branch following project conventions
-- Write tests first when applicable (TDD)
-- Implement changes following project conventions
-- Run quality checks (lint, typecheck, tests)
-
-### Phase 5: Deliver
-
-- Commit with conventional commit messages
-- Create a PR with clear title and description
-- Report back with the PR link and summary
-
-## Notes
-
-- Always asks before making architectural decisions (new tables, new services, changing frameworks)
-- Does not gold-plate -- implements what the ticket asks for, nothing more
-- Proposes splitting if the ticket is too large for a single PR
-- Notes bugs or issues outside the ticket scope but does not fix them unless they block the ticket

package/docs/skills/code-style.md

@@ -1,26 +0,0 @@
-# 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.