node-upgrade

name	node-upgrade
description	Upgrade the Node.js version used by this project. `mise.toml` `[tools] node` is the single source of truth (ADR 0003); this skill confirms the target version with the user via AskUserQuestion, reviews the release notes / breaking changes for that Node line, edits `mise.toml`, has the user run `make install-tools` (mise install), then rebuilds the lockfile and verifies with `pnpm install` + `pnpm lint` + `pnpm build`. Unlike go-boilerplate's go-upgrade there is no `make sync-versions` / Dockerfile / go.mod to propagate to (ADR 0004 no-docker), and no CI node-version to sync yet (BACKLOG B9 pending). A `@types/node` major realignment is intentionally NOT bundled here — it is a separate PR per Toolchain-0005 (major updates in isolation). Use this for a deliberate Node version move; for a routine bulk audit of all mise tools (node + pnpm + …) with supply-chain quarantine, use `tools-upgrade` instead.
argument-hint	["<target-version>"]
allowed-tools	Read, Edit, Bash, AskUserQuestion

Node.js Version Upgrade Procedure

This skill defines the work procedure for upgrading the Node.js version used by this project to an arbitrary target version. mise.toml [tools] node is the single source of truth for the Node runtime version (ADR 0003 / 0003-version-manager.md).

A Japanese reference translation of this skill is available at SKILL.ja.md in the same directory (not loaded as a skill; for human reference only).

Positioning (vs tools-upgrade)

• node-upgrade (this skill) — a deliberate, single-purpose Node version move: review the Node release notes / breaking changes, bump mise.toml, rebuild, and verify. Use when you specifically intend to change the Node line (e.g. 24.x → 26.x, or a patch bump for a security fix).
• tools-upgrade — a routine, bulk audit of every mise.toml [tools] entry (node and pnpm and any others) against upstream latest, with a supply-chain quarantine gate. Use for periodic version hygiene, not for a considered single-runtime upgrade.

They overlap only on "edit mise.toml [tools] node." When you already know you are moving Node and want the release-note review + full rebuild, use this skill.

When NOT to Use

• Bumping pnpm or other tools → tools-upgrade (or edit mise.toml + make install-tools for a one-off).
• Updating npm dependencies (package.json dependencies / devDependencies) → out of scope here; per Toolchain-0005, dependency majors go in their own PR.

First Step: Confirm the Target Version

This skill MUST call AskUserQuestion immediately after invocation to confirm the target version. Even if a version-like string is present in the skill arguments or the most recent user message, do NOT adopt it silently and proceed (explicit confirmation prevents misconfiguration).

Procedure:

1. Read the node = "X.Y.Z" entry under [tools] in mise.toml to determine the current version.
2. Always invoke AskUserQuestion:
   • Question: "Specify the target Node.js version to upgrade to (e.g., 26.0.0)."
   • Include the current version (the value of [tools] node in mise.toml) as context.
   • If a candidate is present in the arguments / recent message, include it as "Candidate: X.Y.Z".
3. Validate the answer is in X.Y.Z format. Use it as <TARGET_VERSION> throughout.

Do NOT modify any files or run any commands until the target version is confirmed.

Preconditions

• Target version: <TARGET_VERSION> (confirmed above).
• Do NOT work directly on production / develop / staging / release/* / hotfix/* branches (Git rules in AGENTS.md). Create a working branch from the latest release/* (e.g. feature/node-upgrade-<TARGET_VERSION>).

AI Modification Scope (skill-declared)

Per AGENTS.md "Exception: Skill Execution," the normal AI Modification Scope is relaxed only for the paths this skill declares, only while it runs. Permitted here:

• mise.toml — the node entry under [tools] (the SSOT edit; mise.toml is otherwise a protected root config, so this skill declares it explicitly so the user is aware when invoking).
• pnpm-lock.yaml — regenerated by pnpm install if the runtime change alters resolution.

Remaining protected even during this skill: AGENTS.md / CLAUDE.md, Accepted ADR bodies, LICENSE, package.json and other root configs (a @types/node change is a separate PR — see step 6), generated files, and anything under .claude/settings.json permissions.deny.

Execution Steps

1. Check the Release Notes

Review the release notes for the target Node line at https://github.com/nodejs/node/releases (and the Node.js changelog). Items to check:

• Removed / deprecated APIs and flags (esp. anything Next.js 16 / the toolchain relies on).
• V8 version bump and any behavior changes.
• Minimum-version bumps in the ecosystem (does Next.js 16 / React 19 support <TARGET_VERSION>?).
• Whether <TARGET_VERSION> is an LTS or Current line (prefer Active LTS for a boilerplate unless the user wants Current).

If the target is a major bump, surface the notable breaking changes to the user before proceeding.

2. Update mise.toml

Edit mise.toml and set the node entry under [tools]:

[tools]
node = "<TARGET_VERSION>"
pnpm = "…"   # unchanged

mise.toml is the single source of truth; there is no make sync-versions step in this repo (that was a Go-boilerplate mechanism for go.mod / Dockerfiles, neither of which exists here — ADR 0004 no-docker).

3. Update the Local Node Environment (user task)

Ask the user to run make install-tools (which runs mise install, reading [tools] node from mise.toml) and to confirm the version:

make install-tools
node --version        # must print v<TARGET_VERSION>

The AI agent must NOT run mise install itself (it mutates the machine's toolchain) — this is a user step, mirroring the go-upgrade convention.

4. Rebuild the Lockfile / Dependencies

After the runtime is switched, reinstall so the lockfile reflects the new runtime and any engine constraints:

pnpm install          # updates pnpm-lock.yaml if resolution changed

Review the pnpm-lock.yaml diff: it should be minimal (often empty). A large diff warrants a look.

5. Verify

pnpm lint             # biome check (ADR 0002)
pnpm build            # next build — must succeed on the new runtime

If a test script exists later (BACKLOG B8 pending), also run pnpm test. Optionally smoke-test the dev server (pnpm dev, then stop it) to confirm the runtime boots the app.

6. Flag Follow-ups (do NOT bundle here)

• @types/node: currently ^20 in devDependencies while the runtime is Node 24+. Aligning its major to the runtime is reasonable, but per Toolchain-0005 a dependency major update belongs in its own PR, not bundled with a runtime bump. Report it as a recommended follow-up; do not edit package.json in this skill.
• CI: there is no .github/workflows/ yet (BACKLOG B9 pending). When CI is added, a node-version-file / matrix sync step belongs here — note it as a future addition to this skill.

Checklist

• Target version <TARGET_VERSION> confirmed with the user via AskUserQuestion
• Release notes / breaking changes reviewed; Next.js 16 / React 19 compatibility confirmed
• mise.toml [tools] node updated to <TARGET_VERSION>
• Local Node updated via make install-tools (user task); node --version matches
• pnpm install run; pnpm-lock.yaml diff reviewed
• pnpm lint + pnpm build green
• @types/node major realignment noted as a separate PR (not done here)

Notes

• Do NOT run mise install yourself — ask the user (it mutates their toolchain).
• Do NOT edit package.json here — dependency majors are separate PRs (Toolchain-0005).
• Commit on the working branch. Direct commits to protected branches are prohibited (AGENTS.md).
• Push to a PR only when the user explicitly instructs it.
• After updating SKILL.md, also update SKILL.ja.md to keep the Japanese translation in sync.