typescript-migration

What this skill does

# TypeScript Migration Skill

This skill migrates an existing JavaScript project to TypeScript autonomously. It is a MIGRATION
workflow — the JS code already exists and works; the goal is to add type safety incrementally,
validate each step, and end with a project that compiles under strict mode (or the highest strict
level achievable without behavior changes).

The whole pipeline runs inside a dedicated worktree. There is exactly one human gate: the merge.

## Why a worktree

The pipeline installs packages, writes tsconfig files, renames files with `git mv`, and edits
type annotations across the entire project. Running this on the user's working branch mixes
unreviewed automated changes with their work. A dedicated worktree isolates everything; the diff
at merge time is the review surface. Every sub-agent runs inside the worktree, not the parent
checkout.

## The pipeline

Run these steps in order. Steps 1–4 are yours (the orchestrator); step 5 hands off to the
Workflow that drives the five specialized sub-agents.

### Step 1 — Scope and validate

1. Identify the target: the user may name a project directory or assume the current working directory.
2. Verify it is a JavaScript project: look for `package.json` and at least one `.js` or `.jsx` file
   under `src/` or the project root.
3. Check whether a `tsconfig.json` already exists. If TypeScript is already fully set up, tell the
   user and stop — this skill is for initial migrations, not ongoing type hardening.
4. Confirm the project has a package manager lockfile (`package-lock.json`, `yarn.lock`, or
   `pnpm-lock.yaml`). If not, warn the user before proceeding.

### Step 2 — Enter the worktree

Create and enter a dedicated worktree under `.claude/worktrees/` (this path is gitignored). Use
the `EnterWorktree` tool — never `cd`. Name it for the project, e.g. `ts-migration-<project-name>`.

Everything after this point happens inside the worktree.

### Step 3 — Confirm scope with the user (optional)

If the project has more than 50 JS files, briefly summarize what the auditor will discover and ask
whether to proceed. For smaller projects, proceed directly.

### Step 4 — Note the entry point

Read `package.json` to capture the `main`, `module`, or `scripts.start` entry point. Pass it to
the Workflow as context for the consolidator's final build check.

### Step 5 — Launch the Workflow

Call the Workflow tool with the bundled script. This skill's instruction to call Workflow is the
explicit opt-in; the pipeline must run deterministically (sequential phases, parallel chunks, strict
progression), which is exactly what a Workflow gives you over prose orchestration.

```
Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/typescript-migration/workflow.js",
  args: {
    projectRoot: "<absolute path to the project inside the worktree>",
    entryPoint: "<value of main/module from package.json, or null>"
  }
})
```

Do NOT set `isolation: 'worktree'` on anything — you are already inside the dedicated worktree
and want every sub-agent to operate in it, not spawn its own.

### Step 6 — Hand off for merge

Lead with the merge verdict, not the strict level reached.

- If `mergeable` is false, say so up front. Report the `strictLevelReached`, the `residualErrors`
  that blocked further progress, and what the user would need to fix manually to go further.
  Do not present the worktree as ready to merge.
- If `mergeable` is true, report: strict level reached, files migrated, shared types created,
  any cross-chunk errors resolved, and any `@types` packages installed. Then present the worktree
  for review and merge.

The merge is the user's sign-off — do not merge automatically.

## What the Workflow orchestrates

| Phase | Agent | Role |
|-------|-------|------|
| Audit | `migration-auditor` | Detect project type, map dep graph, plan chunks, select fixture |
| Setup | `migration-setup` | Install tooling, apply tsconfig, git mv all JS files, verify base compile |
| Extract | `shared-types-extractor` | Define cross-chunk interfaces in src/types/ before typers start |
| Type | `typer` (N parallel) | Add types to each chunk's files, scoped compile gate per chunk |
| Consolidate | `migration-consolidator` | Fix cross-chunk errors, enable strict progressively, final build gate |

Why phases are barriered: Audit must complete before Setup (fixture selection depends on it).
Setup must complete before Extract and Type (files must exist as .ts before they can be typed).
Extract must complete before Type (shared interfaces must exist before parallel typers import them).
Type must complete before Consolidate (all files must be typed before the whole-project build is meaningful).