migrate-hardhat2-to-hardhat3

This skill runs the full V2→V3 migration as six sequential phases. A single agent running them top-to-bottom is the default — it handles small and medium projects (and large ones up to ~150 .ts test files on a 1M-token context window). Beyond that, or on a smaller-context harness (~200k tokens) past a trivial project, fan the file-heavy phases (4 and 5) out to sub-agents so a single context doesn't overflow mid-migration (see "Optional: sub-agent fan-out" in references/migration-conventions.md).

Before you start

1. Read references/migration-conventions.md — the rules every phase depends on (no VCS commands, package-manager detection, scoping, gates, change presentation, and the optional parallel-execution model). Don't proceed until you have.
2. Detect the package manager (lockfile check) and remember it for the whole migration.
3. Choose the execution mode. Estimate your context window and the project size (count .ts test files) and pick single-agent (the default) vs. sub-agent fan-out using the thresholds in the conventions doc. If you can't tell which window you're on, assume the smaller one. Most projects stay single-agent.
4. Phases are strictly sequential — each depends on the previous one's output. After every phase, stop at a user checkpoint and wait for approval before continuing. Present the checkpoint in this order:
   • Step done — the title of the phase just completed (e.g. Phase 1 — Project Setup) and its changes: list the changed files and surface any unexpected ones verbatim (see core rule 5 in the conventions doc).
   • Suggested commit message — the checkpoint commit for the completed phase.
   • Next step — the title of the phase coming next (e.g. Phase 2 — Config) and a one-line description of what it will do, or "the migration is complete" after Phase 6.

Phases

Run each phase by following its phase guide. Each ends with a gate; the checklist below is your confirmation that the phase is truly done before moving on.

Phase 1 — Project Setup → phase guide

Creates .env from templates, updates tsconfig.json for ESM, converts package.json (ESM flag, V2→V3 dependency swap, scripts).