claude-toolkit 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.16.0 (2026-08-08)
+
+`ct-typescript-conventions` now selects a compiler as well as types: prefer the TypeScript 7 native compiler where a project already ships it, fall back cleanly where it does not, and never upgrade a project unprompted. Availability-aware in the same spirit as `ct-esnext-idioms`.
+
+- feat: prioritise the TypeScript 7 native compiler in `ct-typescript-conventions` — TS7 reached GA on 2026-07-08 as `typescript@7.0.2`, with Microsoft reporting 8x–12x faster full builds. The skill detects the *installed* version (`require('typescript/package.json').version`) rather than the declared semver range, which `overrides`/`resolutions`/catalogs routinely defeat, and names the three detection traps: the binary is `tsc` not `tsgo` (that was the pre-GA `@typescript/native-preview` name), range-sniffing is unreliable, and an API probe gives a false negative because TS7 exposes only `version`/`versionMajorMinor`.
+- feat: document when *not* to switch — TS7.0 ships no stable programmatic API, so `typescript-eslint`, `ts-jest`, `ts-node`, `vue-tsc`, `svelte-check`, `@astrojs/check` and `@angular/compiler-cli` break at install or lint time rather than at `tsc --noEmit`, which means a green type-check proves nothing. The skill prescribes the documented side-by-side alias install instead of a downgrade.
+- feat: add the TS7 `tsconfig.json` deltas — the options TS7 rejects outright (`ignoreDeprecations` no longer silences them), plus the two changed defaults behind most real breakage. Verified empirically against 5.9.3 / 6.0.3 / 7.0.2: both defaults land in 6.0 and carry forward, `types` fails `TS2591` even with `@types/node` installed, `rootDir` only bites when an `outDir` is set, and `types: ["*"]` is `TS2688` on 5.x — so no literal value is safe across majors.
+- feat: skill triggers now fire on typecheck, tsconfig, and compiler work — added the `tsc`, `tsgo`, `tsconfig`, `typecheck` and `compiler` keywords, the `**/tsconfig*.json` path pattern, and intents for running a typecheck or upgrading TypeScript.
+- docs: TSConfig cheat sheet gains a TypeScript 7 delta section; the skill's new remit is reflected in the generated skills index, README, and docs index.
+
 ## 0.15.0 (2026-07-04)
 
 Two new authoring-convention assets — an opt-in `esnext` stack and an always-on `ct-code-style` core skill — plus Biome enforcement of the mechanically-checkable style rules.

package/README.md

@@ -121,7 +121,7 @@ Stacks in your config that are no longer detected are reported but left unchange
 
 - `ct-systematic-debugging` — Four-phase debugging methodology
 - `ct-testing-patterns` — TDD workflow and patterns
-- `ct-typescript-conventions` — TypeScript strict mode best practices
+- `ct-typescript-conventions` — TypeScript strict mode best practices, and preferring the TS7 native compiler where available
 - `ct-verification-before-completion` — Evidence-based completion claims
 - `ct-code-style` — Code structure & style: guard clauses, lookup tables, no magic values
 

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

@@ -1,12 +1,70 @@
 ---
 name: ct-typescript-conventions
-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
+description: Strict TypeScript patterns and compiler selection -- prefer the TypeScript 7 native compiler when a project ships it. Use when writing or reviewing TypeScript, running a typecheck, adding or tightening types, or deciding between type and interface
 ---
 
 # TypeScript Conventions
 
 Strict mode enabled. Catch errors at compile time, not runtime.
 
+## Compiler -- prefer TypeScript 7 when the project has it
+
+TypeScript 7 (GA 2026-07-08, `typescript@7.0.2`) is the Go-native compiler; Microsoft reports **8x--12x faster full builds**. In a project that already ships it, use it for every type-check and build. Never install or bump it unprompted.
+
+**Detect the installed version, not the declared range:**
+
+```bash
+node -p "require('typescript/package.json').version"   # major >= 7 -> TS7
+```
+
+Resolve from the directory you are editing -- monorepo workspaces can pin different majors. Three traps:
+
+- The TS7 binary is **`tsc`**. `tsgo` was the pre-GA `@typescript/native-preview` name -- never put it in a script.
+- `package.json` ranges lie: `overrides`, `resolutions`, catalogs, and stale lockfiles all win, and `*` / `latest` / `>=5` resolve to 7.x today.
+- Don't probe the API -- on TS7 `require("typescript")` exposes only `version` and `versionMajorMinor`, so a `ts.createProgram` check gives a false negative.
+
+**Using it** -- same flags as 6.x:
+
+```bash
+tsc --noEmit                  # type-check
+tsc -b                        # build mode / project references
+tsc --checkers 1 --noEmit     # CI: pin the worker count
+```
+
+`--checkers` defaults to 4. Pin it in CI -- Microsoft warns that varying it can surface order-dependent results.
+
+**Stay on 6.x when a tool embeds the compiler.** TS7.0 ships no stable programmatic API (7.1 targets a new one), so `typescript-eslint`, `ts-jest`, `ts-node`, `vue-tsc`, `svelte-check`, `@astrojs/check`, and `@angular/compiler-cli` all break -- at install or lint time, *not* at `tsc --noEmit`. A green type-check proves nothing here. Vite, Bun, `tsx`, Vitest, and Biome are unaffected. Run both rather than downgrading:
+
+```json
+{
+  "devDependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  }
+}
+```
+
+Keep `typescript` pointed at the 6.0 package -- blocked tools import it by peer dependency. Where TS7 is absent, the floor is `typescript@6.0.3`, the bridge release; its readiness gate is a clean build with `"stableTypeOrdering": true` and no `ignoreDeprecations`.
+
+**`tsconfig.json` rules TS7 enforces** -- `ignoreDeprecations` no longer silences any of them:
+
+| Now rejected | Fix |
+|---|---|
+| `baseUrl` | project-root-relative `paths` |
+| `outFile`, `downlevelIteration` | remove |
+| `target: "es5"` | `"es2015"` or later |
+| `module: "amd" \| "umd" \| "system" \| "none" \| "systemjs"` | `"esnext"`, `"preserve"`, or `"nodenext"` |
+| `moduleResolution: "node" \| "node10" \| "classic"` | `"bundler"`, `"node16"`, or `"nodenext"` |
+| `esModuleInterop` / `allowSyntheticDefaultImports` / `alwaysStrict` set to `false` | drop the override |
+| `out`, `charset`, `keyofStringsOnly`, `importsNotUsedAsValues`, `preserveValueImports`, `suppressImplicitAnyIndexErrors`, `suppressExcessPropertyErrors`, `noStrictGenericChecks`, `noImplicitUseStrict` | gone -- `TS5023: Unknown compiler option` |
+
+Two changed defaults cause most real-world breakage. Both arrived in 6.0 and carry forward, so they bite on either major -- verified identical on 6.0.3 and 7.0.2:
+
+- **`types` defaults to `[]`** -- `process`, `Bun` and friends disappear (`TS2591`) *even with `@types/node` installed*. Set `"types": ["node"]` / `["bun"]` explicitly, naming only packages that are actually installed (a missing one is `TS2688`). `"types": ["*"]` restores the old catch-all on 6.x/7.x but is itself `TS2688` on 5.x.
+- **`rootDir` defaults to `./`** -- with sources in `src/` and an `outDir`, emit fails `TS5011`. Set `"rootDir": "./src"`. `--noEmit` does *not* surface this, so type-check CI stays green while the build breaks.
+
+`strict` and `stableTypeOrdering` are on by default; `stableTypeOrdering` cannot be turned off.
+
 ## Rules
 
 - **No `any`** -- Use `unknown` + narrowing, generics, or specific types.

package/docs/README.md

@@ -14,7 +14,7 @@ Skills that are always included regardless of stack configuration.
 | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
 | [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-typescript-conventions](skills/typescript-conventions.md)                 | Strict TypeScript patterns, plus TS7 native-compiler selection              |
 | [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       |
 

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

@@ -127,3 +127,34 @@ When a bundler (Vite, esbuild, etc.) handles transpilation:
   }
 }
 ```
+
+## 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/skills/typescript-conventions.md

@@ -1,6 +1,6 @@
 # TypeScript Conventions
 
-> 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
+> Strict TypeScript patterns and compiler selection — prefer the TypeScript 7 native compiler when a project ships it. Use when writing or reviewing TypeScript, running a typecheck, adding or tightening types, or deciding between type and interface
 
 **Type:** Core Skill (always included)
 **Source:** [`core/skills/ct-typescript-conventions/SKILL.md`](../core/skills/ct-typescript-conventions/SKILL.md)
@@ -9,6 +9,98 @@
 
 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.
 
+The skill also covers **which compiler to run**. TypeScript 7 — the Go-native port — reached GA on 2026-07-08 as `typescript@7.0.2`, with Microsoft reporting 8x–12x faster full builds. The guidance is availability-aware in the same spirit as [ct-esnext-idioms](../stacks/esnext-idioms.md): prefer TS7 where a project already has it, fall back cleanly where it doesn't, and never upgrade a project unprompted.
+
+## Compiler Selection
+
+### Detect before you assume
+
+Read the **installed** version, resolved from the directory being edited (monorepo workspaces can pin different majors):
+
+```bash
+node -p "require('typescript/package.json').version"   # major >= 7 -> TS7
+```
+
+`typescript@7.0.2` whitelists `./package.json` in its `exports` map, and 5.x/6.x have no `exports` map at all, so this subpath resolves on every major.
+
+Three detection traps:
+
+| Trap | Why it misleads |
+|---|---|
+| Looking for a `tsgo` binary | TS7's only CLI binary is `tsc`. `tsgo` belonged to the pre-GA `@typescript/native-preview` package, which is frozen at a `7.0.0-dev` nightly. |
+| Reading the `package.json` semver range | `overrides`, `resolutions`, pnpm/bun catalogs and stale lockfiles all override it — and `*`, `latest`, `>=5` all resolve to 7.x today. |
+| Probing the API (`ts.createProgram`) | On TS7 `require("typescript")` exposes only `version` and `versionMajorMinor`, so an API probe reports a false negative. |
+
+### When TS7 is available
+
+Flags are unchanged from 6.x — `tsc --noEmit`, `tsc -p <path>`, `tsc -b`, `tsc --watch`. New in TS7:
+
+| Flag | Meaning |
+|---|---|
+| `--checkers <n>` | Type-checking workers per project (default 4). Microsoft warns that varying it "may surface order-dependent results" — pin it in CI. |
+| `--builders <n>` | Projects built concurrently in build mode (default 4). |
+| `--singleThreaded` | Most deterministic setting. |
+| `--lsp` | Language server over LSP (there is no `tsserver` binary). |
+
+Note that watch mode is labelled a prototype at the GA tag: it rebuilds but does not incrementally recheck.
+
+### When a tool embeds the compiler — do not switch
+
+TypeScript 7.0 ships **no stable programmatic API**; Microsoft targets 7.1 for "a new (and different) API" with no committed date. Anything that embeds the compiler is blocked:
+
+| Tool | Status on TS7 |
+|---|---|
+| `typescript-eslint` | Peer range `<6.1.0`; install fails `ERESOLVE`, and a forced install crashes during lint |
+| `vue-tsc`, `svelte-check`, `@astrojs/check` | Crash on `ERR_PACKAGE_PATH_NOT_EXPORTED` — TS7 has no `./lib/*` export |
+| `ts-node` | Crashes in config load |
+| `ts-jest` | Peer range `>=4.3 <7` |
+| `@angular/compiler-cli` | Peer range `>=6.0 <6.1` (Microsoft suggests a hybrid: TS7 at the CLI, TS6 for editor support) |
+
+Unaffected — these carry no `typescript` dependency at all: Vite, Bun, `tsx`, Vitest, Jest, Biome.
+
+**A type-check smoke test will not catch these failures.** typescript-eslint's breakage surfaces at `npm ci` and at lint time while `tsc --noEmit` still passes. When a blocked tool is present, install both compilers side by side rather than downgrading — this is Microsoft's documented escape hatch:
+
+```json
+{
+  "devDependencies": {
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  }
+}
+```
+
+The `typescript` key must stay pointed at the 6.0 compatibility package, because blocked tools import from `typescript` by peer dependency.
+
+### When TS7 is absent
+
+The floor is `typescript@6.0.3` — the last 6.x release, and the bridge Microsoft designates between 5.9 and 7.0. It also sits inside every current ecosystem peer range. The readiness gate before moving a project to 7 is a clean 6.0 build with `"stableTypeOrdering": true` and no `ignoreDeprecations` set. That flag is a diagnostic aid only — Microsoft notes it can add up to 25% to type-checking time and is not meant to be left on.
+
+### `tsconfig.json` under TS7
+
+These are rejected outright, and `ignoreDeprecations` no longer silences them (in 6.0 they were silenceable errors; in 7.0 there is no escape hatch):
+
+| Rejected | Replacement |
+|---|---|
+| `baseUrl` | project-root-relative `paths` |
+| `outFile`, `downlevelIteration` | remove |
+| `target: "es5"` | `"es2015"` or later |
+| `module: "amd" \| "umd" \| "system" \| "none" \| "systemjs"` | `"esnext"`, `"preserve"`, or `"nodenext"` |
+| `moduleResolution: "node" \| "node10" \| "classic"` | `"bundler"`, `"node16"`, or `"nodenext"` |
+| `esModuleInterop` / `allowSyntheticDefaultImports` / `alwaysStrict` set to `false` | drop the override |
+
+These are gone entirely — `TS5023: Unknown compiler option`: `out`, `charset`, `keyofStringsOnly`, `suppressImplicitAnyIndexErrors`, `noImplicitUseStrict`, `importsNotUsedAsValues`, `preserveValueImports`, `suppressExcessPropertyErrors`, `noStrictGenericChecks`.
+
+Two changed defaults account for most real-world breakage:
+
+- **`types` defaults to `[]`.** Ambient globals like `process` vanish with `TS2591`. Set it explicitly: `"types": ["node"]`, or `["bun"]` for Bun projects.
+- **`rootDir` defaults to `./`.** With sources under `src/` and an `outDir`, emit fails `TS5011`. Set `"rootDir": "./src"`. This fires **only when the program emits** — `tsc --noEmit` stays silent, so a type-check-only CI job can stay green while the build breaks.
+
+`strict` defaults to `true`, and `stableTypeOrdering` is on and cannot be turned off. `experimentalDecorators` and `emitDecoratorMetadata` both survive.
+
+Project references, `--build` mode, incremental builds, declaration emit, and CommonJS emit all work.
+
+> Reference note: `typescriptlang.org/tsconfig` has not been updated for TS7 and still documents removed options, and there is no TS 7.0 handbook release-notes page. The [GA announcement](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/) is the authoritative what's-new source.
+
 ## Key Patterns
 
 ### Strict Mode

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {

package/src/generator.ts

@@ -373,7 +373,8 @@ async function generateSkillsReadme(claudeDir: string, resolved: ResolvedConfig)
 	content +=
 		"| ct-systematic-debugging | Four-phase debugging methodology, root cause analysis |\n";
 	content += "| ct-testing-patterns | Test-driven development workflow and patterns |\n";
-	content += "| ct-typescript-conventions | TypeScript strict mode and conventions |\n";
+	content +=
+		"| ct-typescript-conventions | TypeScript strict mode, conventions, and TS7 compiler selection |\n";
 	content += "| ct-verification-before-completion | Evidence-based completion claims protocol |\n";
 	content +=
 		"| ct-code-style | Code structure & style: guard clauses, lookup tables, no magic values |\n";

package/templates/skill-rules.base.json

@@ -43,14 +43,37 @@
 			}
 		},
 		"ct-typescript-conventions": {
-			"description": "TypeScript strict mode and conventions",
+			"description": "TypeScript strict mode, conventions, and TS7 compiler selection",
 			"priority": 5,
 			"triggers": {
-				"keywords": ["typescript", "type", "interface", "generic", "strict mode"],
-				"keywordPatterns": ["\\btype\\b", "\\binterface\\b", "\\bgeneric\\b"],
-				"pathPatterns": ["**/*.d.ts", "**/types/**", "**/types.ts"],
-				"intentPatterns": ["(?:define|create).*(?:type|interface)", "(?:type).*(?:error|issue)"],
-				"contentPatterns": ["interface ", "type ", ": unknown", "as const"]
+				"keywords": [
+					"typescript",
+					"type",
+					"interface",
+					"generic",
+					"strict mode",
+					"tsc",
+					"tsgo",
+					"tsconfig",
+					"typecheck",
+					"compiler"
+				],
+				"keywordPatterns": [
+					"\\btype\\b",
+					"\\binterface\\b",
+					"\\bgeneric\\b",
+					"\\btsc\\b",
+					"\\btsconfig\\b",
+					"\\bts\\s?7\\b"
+				],
+				"pathPatterns": ["**/*.d.ts", "**/types/**", "**/types.ts", "**/tsconfig*.json"],
+				"intentPatterns": [
+					"(?:define|create).*(?:type|interface)",
+					"(?:type).*(?:error|issue)",
+					"(?:run|fix).*type.?check",
+					"(?:upgrade|migrate|update).*typescript"
+				],
+				"contentPatterns": ["interface ", "type ", ": unknown", "as const", "compilerOptions"]
 			},
 			"excludePatterns": ["issue type", "type of bug"]
 		},