Nx Multi Repo Migrate

Nx Multi-Repo Migrate

Migrate a set of repos to one target nx version, then open linked draft PRs. Think of it like a pharmacist filling the same prescription for several patients: same drug (target version), but each patient (repo) has different allergies (package manager quirks) — get those wrong and the dose silently fails.

Input

• Target version — e.g. 23.0.0-beta.25. Verify it exists: npm view nx@<version> version.
• Repos — an explicit list, or the repos already in a Polygraph session. When none is given, the default set is nx, ocean, nx-labs, nx-examples, nx-console (all in the nrwl org).

Procedure

1. Set up the session

Use the polygraph skill to discover repos, select the org, and start (or join) the session. It owns auth and session lifecycle — don't reimplement any of that here.

2. Delegate the migration to a child agent per repo

This is the Polygraph way: each repo's work runs in its own child agent (spawn_agent), not in the parent. Delegate to every repo in the session — in parallel — and poll with show_agent until each is terminal. Hand each child the migration instruction below (substitute the target version).

Migrate this repository to nx <VERSION>.

1. Branch from the current default branch, not the clone's checkout. Fetch first so you don't inherit a stale clone or an in-place working-dir branch, then create the branch from origin/<base> (master or main): git fetch origin <base> && git checkout -B migrate-nx-<VERSION> origin/<base>.
2. Detect the package manager from the lockfile (package-lock.json=npm, yarn.lock=Yarn Berry, pnpm-lock.yaml=pnpm, bun.lock/bun.lockb=bun).
3. Install first, so node_modules is at the repo's current (pre-migrate) nx version. nx migrate reads the "from" version from node_modules, not package.json — if node_modules is already at the target, it finds zero migrations and silently skips them. Verify with node -p "require('./node_modules/nx/package.json').version".
4. Run nx migrate <VERSION> (updates package.json, writes migrations.json).
5. Install again — mutable. Do NOT set CI=true (it makes Yarn Berry immutable / pnpm frozen, so the install and migrations fail silently). pnpm needs --config.confirm-modules-purge=false; Yarn Berry needs YARN_ENABLE_IMMUTABLE_INSTALLS=false.
6. Commit the version bump first (before running migrations, so it stays isolated from the migration edits): stage package.json + the lockfile — NOT migrations.json — and commit chore(repo): migrate to nx <VERSION> (never mention AI/Claude).
7. Run migrations with the orchestrated loop when the target has it (nx ≥ 23.2.0-beta.8). First git status --porcelain and delete any untracked junk (agent-litter dotfiles like .bashrc/.zshrc/.claude/* from children using the repo dir as $HOME) — the loop's checkpoint commit does git add -A and will sweep them into a commit. Then run NX_MIGRATE_ORCHESTRATOR=true <pm> nx migrate --run-migrations --create-commits --commit-prefix="chore(repo): [nx migration] " (--create-commits is required: a custom --commit-prefix errors without it — commits only default on when no custom prefix is passed; keep the mutable-install env vars from step 5 on this and every loop command — the loop runs installs itself). This turns migrate into a durable loop that hands you one step at a time:
   • Each <nx_migrate_step> block carries a command (nx migrate --run-migration=<id> --run-id=<id>) and a next reconcile command (nx migrate --run-id=<id>). Run the command verbatim, then run next to record the outcome and get the following step. Repeat until a block with action="complete".
   • Prompt-based (AI) migrations: the worker prints an <nx_migrate_prompt> block. Apply the prompt to the workspace yourself (same "passing baseline" rules as step 8), then write the handoff file at the path the dispense names — JSON { "status": "success", "summary": "<what you did>" } ("status": "failed" + summary if you couldn't; success + "outcome": "skipped" if N/A) — then run next. No tools/ai-migrations/ pile is left behind in this mode.
   • Failed/died steps: the dispense lists the valid --step-action options (retry, retry-clean, adopt, skip, unresolved) and how many retries are left (two per step; ask the user before the last). Diagnose first; retry only with a fix in hand, retry-clean when offered. adopt records a migration already applied by hand or a died worker's landed changes (when a commit of the migration's changes landed, or was started and never recorded, the dispense withholds skip and unresolved; adopt only once you have inspected the tree and finished the migration, otherwise stop and report); skip only for a genuinely inapplicable step; unresolved gives the migration up (recorded as a run issue and listed in the completion report; only a session nx started itself exits non-zero for it, so in this loop read the completion block's unresolved tally). Unattended, an unfinishable prompt step reaches that option by writing the failed handoff yourself, running next, then choosing unresolved.
   • Commits are created by nx and default ON in this mode — do not also hand-commit. Expect one per migration, plus a second one under the same migration's name only when changes remain in the tree: adopt after a recorded commit lands what changed since, and unresolved lands a tree it cannot safely reset. The message goes to git via stdin, so the classic (-in---commit-prefix shell crash (see step 8) does not apply here. If nx refuses because .nx/migrate-runs isn't gitignored, add that entry to .gitignore and re-run.
   • Crash/timeout recovery: run state lives in .nx/migrate-runs/<run-id>. Re-running nx migrate --run-migrations (same env) does not resume: it prints an existing-run block with the run's report and two ways forward, and starts nothing. Continue the run with the continue command that block lists (--run-migrations --agentic --run-id=<id> plus the run's recorded policy flags: it re-enters the run, re-emits the runbook and names the next reconcile); --start-fresh --run-id=<id> deletes only that run's record and runs the whole plan again. Both commands need NX_MIGRATE_ORCHESTRATOR=true set like the loop command; the block says so but does not print it in front of them. It undoes nothing: the changes and commits the run made stay, and the new run applies the same migrations over them. Discarding them is a separate restore or revert that needs the user's explicit go-ahead. The report's activity line names any other nx migrate process still working on the run; nx refuses to continue or start fresh while one does, so wait for it or stop it first. Under WASM that line reads unknown: start fresh still refuses, a continue proceeds. Never re-migrate after a killed child.
   • If no <nx_migrate_step> block appears (target older than 23.2.0-beta.8, or the agent-detection gate — CLAUDECODE in the env — didn't trip and the classic loop ran), fall back to step 8.
8. Classic fallback — do NOT use --create-commits. nx shells its --commit-prefix="chore(repo): [nx migration] " through /bin/sh unescaped, and the ( crashes it (Syntax error: "(" unexpected), which silently drops migrations. Instead run one nx migrate --run-migrations pass (apply the whole list, not a subset), then commit each migration's edits by hand, e.g. chore(repo): [nx migration] <name> (git commit -m handles the parens fine). Then apply the AI migrations yourself — you are the agent nx defers them to. --run-migrations applies the deterministic codemods (importantly remove-removed-typescript-eslint-extension-rules, which strips typescript-eslint v8-removed rules like @typescript-eslint/no-extra-semi; leaving one in a flat config crashes ESLint's loader → nx "Failed to process project graph" → red CI) AND writes prompt-only migrations to tools/ai-migrations/**/*.md, printing "Next steps for the AI agent driving this run: apply the deferred prompts." That is addressed to you (the child) — read each prompt and make the described changes; do NOT leave them for a human. Honor each prompt's "passing baseline": keep lint/typecheck passing, never disable a rule the user explicitly configured, and disable a newly preset-enabled rule with a short comment rather than editing source to satisfy it. (nx auto-skipping its nested agentic flow inside an agent is the review skipping — NOT permission to skip the migrations.)
9. Verify before declaring done: nx run-many -t lint --skip-nx-cache must resolve the project graph and pass (the removed-rule crash only shows at graph-processing time), plus typecheck/build affected projects where feasible. Fix migration-introduced breaks; surface genuine framework-major incompatibilities (Angular/React/TS majors) for a human rather than hacking around them.
10. Delete tools/ai-migrations/ (classic path only — the orchestrated loop doesn't create it) and migrations.json; leave .nx/migrate-runs/ alone (gitignored scratch, kept for post-mortems). If migrations changed deps, re-install and commit the lockfile update.
11. Report: old→new version, packages bumped, which mode ran (orchestrated vs classic), deterministic migrations run (+ commits), each AI prompt and how you applied it (or why N/A, per handoff), any --step-action resolutions used, final lint/typecheck/build status, and any unresolved failures — type/name collisions, framework-major breaks. Leave true blockers for a human; do not invent workarounds.

Completing a partial / already-at-target run. If node_modules is already at the target, nx migrate <VERSION> finds zero migrations. To (re)apply migrations that a prior run skipped — the deterministic remove-removed-* codemod or the AI prompts — regenerate the full list with an explicit --from: nx migrate <VERSION> --from=nx@<original-version>. Migrations detect already-applied state and no-op, so this safely re-runs only what's missing, then finish with steps 7–11 above.

Package-manager cheat sheet:

Migrations can rewrite source: a multi-beta jump (e.g. beta.23→beta.25) pulls migrations from every intervening version, so it may rewrite real code (e.g. CreateNodesContextV2→CreateNodesContext). The child should review the non-dep diff before committing. A single-beta jump on an already-current repo often legitimately has none.

3. Push + open a PR per repo, as each child finishes

Don't barrier on the slowest repo. The moment a child reports success, push_branch that repo (branch migrate-nx-<VERSION>) and create_pr for that repo alone — so its CI starts immediately and one slow repo (e.g. one stuck fighting the sandbox) doesn't gate the others:

for each repo, as its child reaches terminal success (not in a barrier):
  push_branch(repo) → create_pr([repo])

The PRs stay linked because they all join the same Polygraph session — the link is the session, not the single batched call. Commit-message scope repo passes nx's commitlint. Print the Polygraph session URL once all are open.

Verify once: a single batched create_pr writes every PR body with its sibling cross-references at creation time; with incremental creation, confirm Polygraph back-fills the earlier PRs' bodies with links to the later ones (vs. each PR only linking to the session). If it doesn't back-fill and you need the in-body cross-links, fall back to one batched create_pr after all children finish.