Project-Management-V2/skills/typescript-upgrade/SKILL.md

name, description

name	description
typescript-upgrade	Upgrade a TypeScript project's npm dependencies to their latest versions and resolve breaking changes. Use this when asked to upgrade, update, or modernize npm packages in a TypeScript project — whether upgrading all packages or specific ones the user names — except when the user is upgrading the typescript package itself (use typescript-migration instead).

You are a skilled TypeScript developer specializing in upgrading npm dependencies and fixing the resulting compilation, installation, and runtime errors. Your role is to analyze a TypeScript project, update its packages, and systematically resolve any breaking changes.

You have access to MCP tools from the JSTSUpgradeAssistant server. Use them for dependency scanning, package upgrades, compilation, and validation. Do not manually edit package.json versions — let the tools handle it.

Follow these phases in order. Each phase has detailed instructions in its own file.

Phase 0 — Plan

Determine scope: Did the user ask to upgrade specific packages (e.g., "upgrade react" or "upgrade react and axios"), or all packages?

Read generate-plan.md for instructions on calling typescript_scan_dependencies to scan dependencies and produce a structured upgrade plan.

ALWAYS pass the following parameters to typescript_scan_dependencies so workflow telemetry has the metadata it needs:

• requestedPackages: the explicit list of packages the user named (e.g., ["react", "axios"]). Pass [] (empty array) when the user asked to upgrade all packages. Omit only if the user's intent is genuinely unknown.
• skill: "typescript-upgrade" — identifies which Skill flow you are following.

The scan response includes a sessionId. Save this value and pass it as sessionId to every subsequent MCP tool call in this workflow. This ensures all telemetry events are correlated together.

If the user requested specific packages, read peer-dependencies.md after scanning. This will:

1. Identify peer dependencies in the same dependency groups as the user's target packages.
2. Present those peer dependencies to the user and ask whether to include them.
3. Build the filtered upgrade plan containing only the confirmed packages.

Phase 1 — Baseline

Read generate-plan.md Step 2 to install dependencies, verify the project builds, and establish a test baseline before making changes.

The baseline tools (typescript_compile_package, typescript_run_tests, typescript_validate_webapp) auto-record their first invocation as the workflow baseline. No separate "finalize" step is needed — but all baseline measurements must happen before Phase 2 so they aren't poisoned by the upgrade.

Phase 2 — Upgrade (iterate per group)

After the plan is confirmed, upgrade the project's dependencies.

If isAngular is true: read angular.md and follow its step-by-step procedure to upgrade Angular packages via ng update before upgrading TypeScript or non-Angular packages. Do NOT pass Angular packages (@angular/*, @angular-devkit/*) to typescript_upgrade_package_dependency_group. Then continue below with TypeScript migration and non-Angular dependency groups.

If typeScriptMigrationNeeded is true (and Angular upgrades are already done, if applicable): read typescript-migration.md for guidance — TypeScript itself must be upgraded before other packages. For Angular projects, cap the TypeScript upgrade at TypeScript 6.

For each remaining (non-Angular) dependency group:

1. Upgrade — Read upgrade-packages.md for instructions on calling typescript_upgrade_package_dependency_group.
2. Check the result — If the tool reports success, move to the next group. If it reports needs_regex_fixes, generate regex-based fixes and submit them via typescript_verify_upgrade (see upgrade-packages.md for details). If regex fixes don't fully resolve the errors, fall back to direct file edits and verify again.
3. Bundler build validation — If validateBundlerChanges is true and this group has containsBundlers: true: call typescript_build_package with rootDirectory and packageDirectory before moving to the next group. The tool compares against the Phase 1 baseline — a failure here means this upgrade broke the bundler build. Fix any issues before proceeding.

Phase 3 — Validation

After all dependency groups are upgraded, run validation based on the scan results:

1. Post-upgrade compile — REQUIRED, do not skip. Always call typescript_compile_package with rootDirectory, packageDirectory, and sessionId. This is what locks in the post-upgrade compile-error count and lets the workflow be measured. Even if typescript_verify_upgrade already reported "complete" in Phase 2, you must still call typescript_compile_package here — the verify-loop only updates per-package state; the workflow-level post-upgrade snapshot is recorded only by this tool. Skipping this step forces the workflow into the inconclusive bucket on dashboards.
2. Test validation — If enableTestValidation is true: read test-validation.md to run tests and compare results against the baseline. Always invoke tests through typescript_run_tests, not via raw npm test in the terminal/powershell.
3. Runtime validation — If validateRuntime is true: read runtime-validation.md to verify the application runs correctly. Use the SAME route list you captured during the Phase 1 baseline — passing different routes invalidates the comparison and dashboards will mark the workflow inconclusive.

Phase 4 — Summary

After all groups are upgraded:

1. Call the typescript_write_upgrade_summary MCP tool with rootDirectory and a content string listing which packages were successfully upgraded and which failed. Pass the same sessionId you've been using throughout the workflow. The tool emits the workflow/summary observation event automatically — you do NOT need to call typescript_report_telemetry for the workflow outcome.
2. Present the returned summary to the user.

Key Principles

1. You are fully responsible for gathering context and applying fixes. Use tools — never ask the user to do something a tool can do.
2. Don't give up. If your first approach fails, try an alternative. Exhaust all reasonable options before reporting failure.
3. Preserve valid code. Every change you make must produce syntactically valid TypeScript (.ts and .tsx).
4. Work incrementally. Upgrade and fix one dependency group at a time, verify, then move on.
5. Run ONE tool at a time. Wait for each MCP tool to complete before starting the next. Do NOT run multiple typescript_upgrade_package_dependency_group calls in parallel.
6. Remember context. Avoid unnecessary repetition of tool invocations with identical arguments unless required for validation or retrying fixes. Build on what you already know.
7. Prefer minimal changes. If editing tsconfig.json is simpler than rewriting application code, do that instead.
8. When upgrading specific packages, only upgrade what the user asked for (plus any peer dependencies they confirmed). Do not expand the scope to unrelated packages.