claude-toolkit 0.1.9

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

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

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

@@ -0,0 +1,72 @@
+# /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
+/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}
+```
+
+## 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
+- 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

@@ -0,0 +1,102 @@
+# /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
+/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
+```
+
+## 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
+- 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

@@ -0,0 +1,50 @@
+# /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
+
+```
+/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

@@ -0,0 +1,59 @@
+# /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
+
+## Usage
+
+```
+/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

@@ -0,0 +1,56 @@
+# /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
+
+```
+/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/systematic-debugging.md

@@ -0,0 +1,70 @@
+# Systematic Debugging
+
+> Four-phase methodology for diagnosing and fixing bugs efficiently without guesswork.
+
+**Type:** Core Skill (always included)
+**Source:** [`core/skills/systematic-debugging/SKILL.md`](../core/skills/systematic-debugging/SKILL.md)
+
+## Overview
+
+A disciplined approach to debugging that replaces trial-and-error with structured investigation. Apply the four phases in order -- skipping phases leads to wasted time and incomplete fixes.
+
+## Phases
+
+### Phase 1: Observe
+
+Reproduce the issue and gather evidence before forming any theories.
+
+- **Reproduce reliably** -- find the minimal steps to trigger the bug
+- **Read the actual error** -- full stack trace, error message, and relevant logs
+- **Check recent changes** -- use `git log` and `git diff` to identify what changed
+- **Gather context** -- note the environment, input data, user actions, and timing
+- **Record observations** -- write down what you see, not what you think is happening
+
+### Phase 2: Hypothesize
+
+Form theories based on evidence, not intuition.
+
+- **List possible causes** -- generate at least 2-3 hypotheses before investigating any
+- **Rank by likelihood** -- what changed recently? What is the simplest explanation?
+- **Consider the data flow** -- trace the path from input to error
+- **Check assumptions** -- the bug is often in the code you trust most
+
+### Phase 3: Test
+
+Isolate variables and verify one hypothesis at a time.
+
+- **Test one thing at a time** -- change a single variable per experiment
+- **Use the smallest possible test** -- write a minimal reproduction
+- **Add logging at boundaries** -- log inputs and outputs at function boundaries
+- **Disprove hypotheses** -- design tests that would show the hypothesis is wrong
+- **Binary search large spaces** -- bisect systematically when the problem could be anywhere
+
+### Phase 4: Fix
+
+Apply the minimal correct fix, then verify thoroughly.
+
+- **Fix the root cause, not the symptom** -- if a null check prevents a crash but the value should never be null, fix the source
+- **Make the smallest change possible** -- large fixes introduce new bugs
+- **Verify the fix** -- run the reproduction case and confirm the bug is gone
+- **Check for regressions** -- run the full test suite
+- **Add a test for the bug** -- prevent the same class of bug from recurring
+- **Document the fix** -- explain what caused the bug and why the fix is correct in the commit message
+
+## Anti-patterns
+
+| Anti-pattern | Description |
+|---|---|
+| **Shotgun debugging** | Making random changes hoping something works. Every change should be driven by a hypothesis. |
+| **Fixing symptoms** | Adding null checks, try/catch blocks, or default values without understanding why the unexpected state occurs. |
+| **Debugging by rewriting** | Rewriting a module because you cannot find the bug. The bug may survive the rewrite. |
+| **Ignoring intermittent failures** | "It works now" is not a fix. Intermittent bugs are usually race conditions, state leaks, or environment dependencies. |
+| **Assuming the bug is elsewhere** | Check your own code first. The framework or library is almost never the problem. |
+
+## Trigger Conditions
+
+This skill is automatically suggested when Claude detects:
+
+- **Keywords:** `bug`, `debug`, `fix`, `error`, `issue`, `broken`, `crash`
+- **Intent patterns:** "fix/debug/resolve the bug/error/issue"
+- **Excludes:** "fix typo", "fix formatting", "fix lint"

package/docs/skills/testing-patterns.md

@@ -0,0 +1,89 @@
+# Testing Patterns
+
+> Generic test-driven development practices and patterns applicable to any language or test framework.
+
+**Type:** Core Skill (always included)
+**Source:** [`core/skills/testing-patterns/SKILL.md`](../core/skills/testing-patterns/SKILL.md)
+
+## Overview
+
+Principles and patterns for writing tests that catch bugs, enable refactoring, and serve as documentation. These are framework-agnostic -- adapt the syntax to your project's test runner.
+
+## TDD Cycle: Red, Green, Refactor
+
+1. **Red** -- Write a failing test that describes the desired behavior. Confirm it fails for the right reason.
+2. **Green** -- Write the minimal code to make the test pass. Do not optimize yet.
+3. **Refactor** -- Improve the code while keeping all tests green. Remove duplication, improve naming, simplify logic.
+
+Commit at each stage. The cycle keeps scope small and provides a safety net for every change.
+
+## Key Principles
+
+### Test Behavior, Not Implementation
+
+Tests should describe *what* the code does, not *how* it does it internally.
+
+- **Good:** "returns the user's full name when first and last name are provided"
+- **Bad:** "calls `String.prototype.concat` with first name and space and last name"
+
+### Factory Pattern for Test Data
+
+Create factory functions that produce valid test objects with sensible defaults. Accept overrides for the fields relevant to each test.
+
+```
+function getMockUser(overrides = {}) {
+  return {
+    id: "user-1",
+    email: "test@example.com",
+    name: "Test User",
+    role: "member",
+    createdAt: new Date("2024-01-01"),
+    ...overrides,
+  };
+}
+
+// Usage: only specify what matters for this test
+const admin = getMockUser({ role: "admin" });
+```
+
+### Test File Organization
+
+- **Co-locate tests with source** or mirror the source directory structure
+- **One test file per module** -- name it `module.test.ext` or `module.spec.ext`
+- **Group related tests** using `describe` blocks
+- **Use descriptive test names** that read as sentences
+
+### Mocking Strategies
+
+- **Prefer real dependencies** when feasible (in-memory database, local test server)
+- **Mock at boundaries** -- external services only, not internal modules
+- **Keep mocks minimal** -- only mock the methods your code actually calls
+- **Verify mock contracts** -- ensure mocks match real API behavior
+- **Reset mocks between tests** -- prevent shared state and order-dependent failures
+
+## Test Categories
+
+| Category | Scope | Speed | Quantity |
+|---|---|---|---|
+| **Unit tests** | Single function or class | Fast | Many |
+| **Integration tests** | Multiple components together | Slower | Some |
+| **End-to-end tests** | Full user flow | Slowest | Few |
+
+The ratio should be roughly pyramid-shaped: many unit tests, some integration tests, few E2E tests.
+
+## Anti-patterns
+
+| Anti-pattern | Description |
+|---|---|
+| **Testing implementation details** | Asserting on internal state or private methods. Breaks on every refactor. |
+| **Overmocking** | When most of the test is mock setup, you are testing mocks, not code. |
+| **Copy-paste test cases** | Duplicated test code becomes a maintenance burden. Use factories and parameterized tests. |
+| **No assertions** | A test that runs code but asserts nothing provides false confidence. |
+| **Ignoring flaky tests** | A sometimes-failing test is either wrong or exposing a real bug. Fix or delete it. |
+| **Testing only the happy path** | Error cases, edge cases, and boundary conditions are where bugs live. |
+
+## Trigger Conditions
+
+- **Keywords:** `test`, `spec`, `tdd`, `mock`, `factory`
+- **File patterns:** `**/*.test.ts`, `**/*.spec.ts`
+- **Excludes:** "e2e", "end-to-end"