upgrade-project

Purpose

Help evaluate or carry out technology migrations, target configurations, project rules, and general workflows for JavaScript/TypeScript projects, while avoiding mixing unrelated refactors into the task. First confirm the scope of operations the user permits and the project facts, then combine the applicable references; when only evaluating, do not modify files, and when execution is permitted, make only verifiable necessary changes.

Task routing and execution flow

The four categories of references can be used in combination. First determine the task mode and target state, then decide whether to carry out modifications:

用户请求
    │
    ▼
确认任务模式与范围：只评估 / 执行修改
    │
    ▼
检查项目事实、用户约束和未提交改动
    │
    ▼
选择并读取 references（可以组合）
    ├─ 技术从当前状态迁到目标状态 ─ migrations
    ├─ 项目应遵守的规则 ───────── profiles
    ├─ 具体框架的目标配置 ─────── frameworks
    ├─ 跨框架执行流程 ─────────── workflows
    └─ 没有匹配资料 ───────────── 小范围调研真实能力
    │
    ▼
组合目标状态和本次操作范围
    │
    ▼
references 是否与用户要求或项目事实冲突？
    ├─ 是：以用户要求和项目事实为准，记录必要偏差
    └─ 否：继续
    │
    ▼
是否只评估？
    ├─ 是：输出差距、风险和合理例外，停止
    └─ 否
        │
        ▼
      验证目标命令或配置真实可用
        │
        ▼
      实施最小改动，并同步受影响调用方
        │
        ▼
      局部验证；必要时再运行全量验证
        │
        ▼
      复查任务范围、旧技术残留和需幂等的命令

Execution principles

Respect the task mode. When the user only asks for evaluation, only read and compare; do not modify files, dependencies, lockfiles, or Git state. When execution is permitted, do not expand into migrations or refactors the user has not authorized.
Take project facts as the source of truth. Before editing, check scripts, direct dependencies, lockfiles, configuration, pre-commit checks, project documentation, and uncommitted changes. References provide target baselines and do not override user requirements or already-verified project differences.
Combine references by responsibility. Only read the entries that match this task; when multiple categories of material are involved, read them separately. For multiple migrations, first determine the execution order and the acceptance point for each step, to avoid an earlier item mistakenly deleting content still needed by a later item.
Verify capabilities first. Before changing commands or configuration, confirm the real capabilities by using the target tool's help, version, or a minimal verification. If a command, package name, or configuration field is unavailable, do not invent a substitute.
Keep changes necessary and focused. Do not mix in unrelated lint, format, test framework, module system, Docker, CI, IDE, or business code refactors.
Track affected callers. When script, configuration, or artifact paths change, also check the actual references in Dockerfile, deployment scripts, CI, husky, lint-staged, startup entry points, and project documentation.
Follow the project toolchain. Use the existing package manager according to the lockfile; when dependencies, scripts, or configuration change, maintain the lockfile and related pre-commit checks in sync.
Verify by risk. First run the local checks related to this change, then run the project's existing type checks, builds, or tests according to the scope of impact. Verification commands that modify files and operations that need idempotency are handled according to the applicable reference.

Reference directory

Reference materials are divided into four categories by ownership:migrations Only describe the conversion from the old state to the new state;profiles Handle project-level rules;frameworks Handle framework target configurations that can be directly applied;workflows Handle cross-framework reusable execution flows and interface contracts. Do not maintain the same rule or specific template repeatedly across multiple categories.

Migrations: technology migrations

references/migrations/prettier-oxfmt/index.md: Prettier to Oxfmt.
references/migrations/eslint-oxlint/index.md: ESLint to Oxlint.
references/migrations/jest-vitest/index.md: Jest to Vitest; test semantics still follow the target project's AGENTS.md or the applicable profile.
references/migrations/cjs-esm/index.md: CommonJS/CJS to ESM for TypeScript projects.
references/migrations/pnpm-latest/index.md: Upgrade pnpm itself to the latest stable version; includes version selection, project version declaration, dependency build approval, and lockfile compatibility handling.
references/migrations/nestjs-latest/index.md: The only entry point for NestJS upgrades; first take stock of the existing validation approach and handle user confirmation, then read dependencies, Standard Schema, and validation materials in the same directory.

Profiles: project rules

references/profiles/nodejs-backend/index.md: Generic Node.js backend project profile. Read when the task involves framework-agnostic AGENTS.md、CLAUDE.md, test layering, or code organization rules.
references/profiles/nestjs-backend/index.md: NestJS backend project profile. Maintains the complete rule template for NestJS projects, including the long-term Schema conventions after the user adopts Standard Schema.
references/profiles/react-csr/index.md: CSR React project rules profile, only maintains AGENTS.md、CLAUDE.md and the skill conventions needed by frontend projects.

Frameworks: target configuration

references/frameworks/nestjs/index.md: NestJS's package.json、tsconfig.json、nest-cli.json、.swcrc, Prisma Client, PM2, and Dockerfile target templates.
references/frameworks/react-csr/index.md: React CSR + Vite target templates for dependencies, build, type checking, testing, Oxlint, Oxfmt, and lint-staged.

Workflows: general processes

references/workflows/docker-build/index.md: Docker build, validation, image publishing, and deployment script processes. Only the general stage contract is maintained here; the specific Dockerfile is determined by the project or framework.
references/workflows/gitignore/index.md: Git ignore rules template.
references/workflows/dependencies-latest/index.md: Upgrade all direct dependencies; includes latest stable versions, peer dependency, and lockfile checks; upgrading pnpm itself is combined separately with pnpm migration.