sxsphinxstack

Skills / Working / Migrate a monorepo build system

Working Code skill

Migrate a monorepo build system

Migrate a monorepo build system through target inventory, dependency graph parity, hermetic execution, cache integrity, developer workflows, staged cutover, and rollback.

When to use

  • Use for task runners, build graphs, remote caches, package layouts, or CI orchestration.
  • Do not combine unexplained output changes with build-tool migration.

Procedure

  1. Inventory targets, inputs, outputs, dependencies, tools, platforms, CI, and developer commands.
  2. Define canonical graph and hermetic input boundaries.
  3. Reproduce outputs, tests, generated code, packaging, and side effects under both systems.
  4. Secure local and remote cache identity, tenant, provenance, and write authority.
  5. Migrate representative projects and rare platform cases.
  6. Compare clean builds, incremental builds, failures, performance, and artifacts.
  7. Cut over by target cohort with fallback and old-system retirement evidence.

Failure plan

  • Keep a target on the old path when graph or output parity is unresolved.

Worked example

A generated API client depends on an undeclared environment tool, revealed by a clean hermetic build.

Related skills

  • Migrate a message queue — Migrate a message queue while preserving message identity, ordering, delivery, retries, dead letters, backpressure, side effects, and rollback.
  • Optimize a slow query — Measure and improve a slow database query while preserving result correctness, concurrency behavior, and operational safety.
  • Migrate a container runtime — Migrate a container runtime through workload inventory, image and isolation parity, node cohorts, drain, rollback, and security verification.