Multi Version Compliance

Multi-version compliance for Nx plugins

What this is

The nx migrate --first-party-only flag lets users upgrade Nx without dragging the managed third-party ecosystems (Angular, Cypress, Playwright, Jest, Vitest, ESLint, etc.) along. For that to be safe, every first-party plugin must keep working across its declared support window — not silently fall through to the latest install constants on older workspaces, not silently break on newer ones.

Source-of-truth split:

The skill is the gap-closer: it accepts a Linear task, parses it, drives the fix. When no task exists for the plugin, fix mode runs discovery in Phase 1–2 and produces a findings doc that mirrors a Linear task body — so the user can file it as a new task before proceeding.

Reference PRs (the canonical shape):

• #35587 — @nx/angular — merged. Set the precedent. Introduced throwForUnsupportedVersion.
• #35642 — @nx/playwright — merged. Generalized the shared helpers into @nx/devkit/internal. Established executor / runtime feature- gating.
• #35670 — @nx/cypress — merged. Added excludeGenerators to the parameterized test helper.
• #35671 — @nx/vitest — open at time of writing. Demonstrates "drop phantom peer-range claim" and "declared floor < effective floor" patterns.

Before citing any PR by number, verify state — these go stale: gh pr view <N> --repo nrwl/nx --json state. Verify any unmerged PR's contents via gh pr diff <N> --repo nrwl/nx.

Entry points

Stop-after-Phase-2 (audit-equivalent): if you want findings without edits, decline to approve at the end of Phase 2. The skill stops, no branch, no commits.

On a branch matching nxc-NNNN with no explicit arg: before asking the user, suggest "Use NXC-NNNN?" inferred from the branch name.

Linear-fetching protocol

Before any code-level work in Linear-driven mode, the skill MUST:

1. Check Linear MCP availability. If mcp__linear-server__get_issue isn't available (MCP server not installed / not connected), tell the user and fall through to the no-task discovery path (fix mode Phase 1 step 2). Don't pretend to fetch.
2. Fetch the task. mcp__linear-server__get_issue id="NXC-XXXX". If the call errors (invalid ID, network), halt and ask the user to verify the ID.
3. Verify shape. Confirm:
   • Title matches [multi-version][P##] \@nx/<plugin>` — multi-version support compliance(per-plugin) or[multi-version][W#] ...` (cross-cutting). If the pattern doesn't match, halt and ask the user to confirm this is the right task.
   • Status. Done → ask whether re-audit or follow-up. Canceled → halt and ask.
4. Read description sections. Every per-plugin task has:
   • Plugin: — path, upstream support, peerDep declarations, per-major install map, paired secondaries.
   • Needs human decision — open items blocking implementation.
   • Findings — (high|medium|low) items with [file:line] and a suggested fix per item.
   • Verification checklist — Sections A (Support window declarations) / B (Generator inputs) / C (Generator outputs) / D (Migrations) / E (Runtime) / F (Out-of-window UX).
5. Fetch comments. mcp__linear-server__list_comments issueId="...". Audits attached as files / linked uploads may carry additional context.
6. Surface "Needs human decision" as a batch. Restate every decision item in chat. The user can resolve all, defer some, or override. Block until the user has acknowledged the set — don't proceed silently.
7. Translate findings → code changes. Map each finding to a canonical pattern in references/canonical-shape.md. The Linear task's suggested fix is the authoritative scope; the skill verifies it conforms to the canonical shape and flags any deviation.
8. Run the A–F checklist against the final code state. The task's checklist is the agreed scope. The skill verifies code-level conformance.

Default to the task's resolved support window. Don't re-derive it from code unless the user explicitly overrides. If the user overrides: restate the new window and confirm before applying.

Don't expand scope beyond the task's Findings without asking. If you spot a new issue mid-fix: stop, present it, ask whether to (a) add it to this PR, (b) defer as a follow-up, or (c) update the Linear task as a comment.

Mode workflows

Fix mode (primary)

Phase 1 — Read.

1. If a Linear task ID was provided, fetch it per the Linear-fetching protocol. If only a plugin name was provided, look up the per-plugin task in milestone NXC-4072.
2. No task case. If no task exists for this plugin: run discovery instead — apply the policy ladder for the support window (Rule 1: upstream LTS for Angular/React/ESLint/Next/Expo; Rule 2: N & N-1; widen to existing supported set if larger), inventory the plugin's code against the A–F rubric, find the effective floor by walking imports, classify all results as new findings. The skill is producing audit-quality output for a plugin that wasn't ticketed.
3. If on a branch matching nxc-NNNN, read recent commits to understand prior scope decisions.
4. Read references/canonical-shape.md and references/anti-patterns.md.

Phase 2 — Align.

5. (task case) Surface every "Needs human decision" item from the task as a batch. Wait for resolutions.
6. (task case) Restate the Findings list with severity tags. Confirm scope.
7. (no-task case) Surface findings discovered from the rubric inventory + decisions the rubric surfaces (floor raise/drop, peer declarations, optional-vs-required peer, one-sided gates, etc.). Suggest filing them as a new Linear task in milestone NXC-4072 before proceeding to Phase 3.
8. User OK gate. Wait for explicit "proceed" before Phase 3. Declining stops the skill — no branch, no edits. (This is the audit-equivalent.)

Phase 3 — Implement (per canonical-shape.md).

9. Branch from master if needed using the repo's nxc-NNNN convention.
10. Order: any shared-helper extension lands first; plugin changes land after. Commit/PR titling defers to the user's conventions.
11. For each Finding category, apply the canonical pattern:
    • Section A → peer ranges + version map + install constants. Every third-party package the plugin invokes at runtime (TS import, executor spawning the CLI binary, or inferred-plugin emitting a target with command: '<bin>') gets a peer entry. Default to optional: true via peerDependenciesMeta for gated surfaces (executor opt-in, inferred plugin gated on config file presence). Non-optional peers are reserved for packages every workspace using the plugin needs.
    • Section B → generator entry asserts, keepExistingVersions, fresh-install branch.
    • Section C → templates, schema stubs with runtime throws, version-map coverage.
    • Section D → requires gates per package per AND-semantics; split mixed entries; retain intentional pre-floor entries. Default to bilateral bounds (>=N <M) for cross-major packageJsonUpdates windows. One-sided windows (<N with no lower, >=N with no upper) need a justified reason (legacy cleanup, undefined source, v0→v1 bridge) — record the reason in the findings doc or as a code comment. Migration entries gate on the destination instead, usually >=N alone (checklist below).
    • Section E → executor and inferred-plugin feature gates.
    • Section F → below-floor throw via shared util.
    • Cross-cutting: if the fix changes runtime behavior, update any in-codebase docs (astro-docs/, docs/, inline .md) that describe the changed behavior. Docs that contradict the code are a correctness bug, not a PR-body concern.
12. If during implementation you spot something not in the task's Findings: stop, surface it, ask whether to (a) add to this PR, (b) defer as a follow-up, or (c) update the Linear task as a comment.

Phase 4 — Tests (same commit as Phase 3 usually).

13. Add all-generators-enforce-floor.spec.ts — parameterized via assertGeneratorsEnforceVersionFloor. This exercises every generator's floor assert and is the high-value spec.
14. Footgun: assert calls must be in place in every generator BEFORE running the parameterized spec, or every untouched generator fails and you'll restart.
15. Optional: a per-plugin assert-supported-<pkg>-version.spec.ts with the 5 canonical cases. The shared assertSupportedPackageVersion already has full coverage in devkit, so this is mostly symmetry across the PR series — skip unless the user asks.

Phase 5 — Verify locally.

16. npx nx test <plugin> --testPathPattern="all-generators-enforce-floor" (add assert-supported- if you added the optional wrapper spec).
17. npx nx test <plugin> --testPathPattern="<modified-generator>" per touched generator.
18. npx nx format.

Phase 6 — Hand off. Code changes complete. The user drives commit/push/PR per their own conventions (loaded globally from ~/.claude/memory/workflow/git/). This skill does not enforce PR title, body, commit shape, or related-issues format.