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:
| Source |
Owns |
| Linear milestone "Multi-version supported across plugins" (project NXC-4072) |
What's wrong per plugin, the resolved support window, open human decisions. Per-plugin tasks NXC-4381..NXC-4410 (P1–P29). |
| This skill |
How to implement the canonical shape, code-level anti-patterns, gotchas, findings doc shape (no-task case). |
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
| Invocation |
Mode |
Behavior |
multi-version-compliance <NXC-XXXX> |
Fix (primary) |
Fetch task, surface findings + decisions in Phase 2, wait for user OK before Phase 3 edits. |
multi-version-compliance (no arg) |
Ask for task ID |
Prompt for NXC-XXXX. |
multi-version-compliance @nx/<plugin> (bare plugin) |
Fix (task lookup) |
Look up the per-plugin task in milestone NXC-4072. If found, confirm with user and enter fix mode. If not found, run discovery in Phase 1–2 (rubric against code), present findings, suggest filing as a new task before any edits. |
multi-version-compliance review #<N> |
Review |
Fetch PR, derive Linear task from branch name if possible, compare diff vs. task findings (or run pure code-level review if no task). |
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:
- 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.
- 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.
- Verify shape. Confirm:
- Title matches
[multi-version][P##] \@nx/` — 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.
- 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).
- Fetch comments.
mcp__linear-server__list_comments issueId="...".
Audits attached as files / linked uploads may carry additional
context.
- 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.
- 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.
- 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.
- 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.
- 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.
- If on a branch matching
nxc-NNNN, read recent commits to understand
prior scope decisions.
- Read
references/canonical-shape.md and references/anti-patterns.md.
Phase 2 — Align.
- (task case) Surface every "Needs human decision" item from the
task as a batch. Wait for resolutions.
- (task case) Restate the Findings list with severity tags. Confirm
scope.
- (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.
- 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).
- Branch from
master if needed using the repo's nxc-NNNN convention.
- Order: any shared-helper extension lands first; plugin changes land
after. Commit/PR titling defers to the user's conventions.
- 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.
- 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).
- Add
all-generators-enforce-floor.spec.ts — parameterized via
assertGeneratorsEnforceVersionFloor. This exercises every
generator's floor assert and is the high-value spec.
- Footgun: assert calls must be in place in every generator BEFORE
running the parameterized spec, or every untouched generator fails
and you'll restart.
- 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.
npx nx test <plugin> --testPathPattern="all-generators-enforce-floor"
(add assert-supported- if you added the optional wrapper spec).
npx nx test <plugin> --testPathPattern="<modified-generator>" per
touched generator.
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.
Review mode
- Fetch PR.
gh pr view <N> --repo nrwl/nx and
gh pr diff <N> --repo nrwl/nx. For a local branch:
git diff master...HEAD.
- Derive the Linear task. Branch name
nxc-NNNN → NXC-NNNN. If
no match: ask the user.
- Fetch the task (if derivable). Compare diff vs. task Findings:
every Finding addressed; nothing extra without justification. Flag
scope drift.
If no task and the user has none: skip task-comparison; run pure
code-level review against
canonical-shape.md and anti-patterns.md.
- Code-level checks. Run the "Code-level verification (review-mode
lens)" section of
canonical-shape.md. Cross-reference
anti-patterns.md. For each finding, anchor at file:line and cite
which reference PR / file demonstrates the correct pattern.
Scope: code, configs, migrations, and in-codebase docs that claim
runtime behavior. NOT PR title / body / commit shape — those defer to
the user's PR conventions.
- Classify each finding.
- Only two inline categories:
[blocker] and [non-blocker]. No
"open question," "ask," or other inline tags. Questions for the
author surface in the closing "Open questions for author" block,
drawn from non-blocker findings — list each question once.
- Severity is independent of scope-drift. A finding can be both a
blocker AND not in the Linear task. Flag it as a blocker in the
code-level section AND list it under "in PR but not in Linear task"
in scope drift. Don't hedge with "in this PR or follow-up?" — if
it's a blocker, the answer is "this PR."
- Group related non-blockers. When multiple non-blockers describe
symptoms of one blocker (e.g., five symptoms of a single
version-utils.ts duplication), list them as sub-bullets under
the blocker with "(resolved when §X is fixed)" rather than as N
separate top-level non-blockers.
- Be terse on passes. A section with no findings gets a single
summary line ("Pass — all 7 generator entries assert at first
statement"), not a per-file enumeration. Detail is reserved for
blockers and non-blockers. The reviewer's audience skims for
actionable items; passing checks should not eat reading budget.
- Output. Markdown checklist of blockers / non-blockers anchored at
file:line, followed by the structured verdict block from
canonical-shape.md §"Verdict template". The verdict block is the
skimmable index — produce it, don't substitute a free-form prose
summary. Do not post via gh pr review unless the user explicitly
asks.
Which references to load (context hygiene)
| Mode |
Required |
Optional |
| Fix |
canonical-shape.md, anti-patterns.md |
gotchas.md (effective floor, ecosystem lockstep, cypress inline tree), examples.md (when copying a pattern) |
| Review |
anti-patterns.md, canonical-shape.md (especially the "Code-level verification" section) |
gotchas.md (cross-plugin coordination, lockstep), examples.md (when citing) |
| "What is compliance?" answer |
none |
answer from SKILL.md alone |
References are ~100–500 lines each. Don't pull all of them just because
you're invoked. Match the load to the mode.
Critical rules (apply in every mode)
- Linear task is the source of truth for scope (ratified decisions
and Findings).
- (a) Don't produce a parallel scope document. The task IS the scope.
Fix mode runs against the task as input — drift checks, new
findings, and decisions feed back to the task (via comments or as
deferred items), not into a competing source of truth.
- (b) Don't expand a fix beyond the task's Findings without
surfacing the new issue.
- (c) Don't second-guess the task's resolved support window without
an explicit user override.
- Do not create or duplicate shared helpers. They live in
@nx/devkit/internal (assertSupportedPackageVersion,
getInstalledPackageVersion, getDeclaredPackageVersion,
throwForUnsupportedVersion, normalizeSemver, isNonSemverDistTag)
and @nx/devkit/internal-testing-utils
(assertGeneratorsEnforceVersionFloor). Reject any local
re-implementation (cleanVersion, getInstalled<Pkg>VersionRuntime,
private throwBelowFloor, etc.). See canonical-shape.md.
- Above-ceiling is silent fallthrough. Do not warn, do not throw,
do not branch. Reject
throwAboveWindow, warnAboveCeiling,
versions() with switch + throw default:. The only throw is below
the declared floor.
keepExistingVersions: true is for generators only. Migration
generators (src/migrations/) are exempt — their job is to bump.
Do not flag missing flags in migration code.
- Floor assert is the first statement in the function doing the
actual work. Wrapper/internal split (cypress, playwright): in
*Internal. Single-function generators (angular): in the function
itself. Not conditional, not inside an install branch, not after a
tree read.
- Phase 1–2 never writes, never branches. Discovery, finding
classification, and decision-surfacing happen on the current branch
with no edits. Any working artifact (e.g., a findings doc for a
no-task case, multi-plugin scratch notes) goes in
tmp/ (gitignored)
and stays uncommitted. No TRIAGE-REPORT.md / AUDIT.md at repo
root. Branch creation and edits start at Phase 3, after the user OK.
- PR / commit conventions are out of scope. Title format, body shape,
commit-message structure, related-issues handling, push flags, etc.
are governed by the user's global memory (
pr-creation-shorthand.md,
push-conventions.md, explain-before-committing.md,
chore-not-fix-non-prod.md). Don't enforce or flag these from this
skill — defer to whatever the user's conventions resolve to at PR time.
Findings doc template (Phase 2 output, used when no Linear task exists)
When fix mode hits the no-task case (Phase 1 step 2), produce
tmp/<plugin>-findings.md shaped to mirror a Linear task body so the
user can file it as a new task in milestone NXC-4072 before proceeding
to Phase 3.
For plugins managing multiple primary packages, repeat the install-map
/ decisions / findings bullets per primary.
# @nx/<plugin> — multi-version support compliance findings
> No Linear task in milestone NXC-4072. This doc is filing-ready —
> create the task with this body before proceeding to fix.
## Plugin
- Path: packages/<plugin>
- Upstream support: <official policy if any, else "no formal LTS">
- peerDep declarations: <list>
- Per-major install (`<file>` branches on installed `<package>` major):
- v<N-1>: <constants>
- v<N>: <constants> (default)
- Paired secondaries: <list of ecosystem-locked siblings>
## Needs human decision
1. <decision 1 — e.g., raise floor to vN.0.0 vs keep current>
2. <decision 2 — e.g., drop ^1.0.0 from peer (no v1 install lane)>
## Findings
- **(high) <one-line summary>** [file:line]
_Suggested fix_: <one-line>
- **(medium) ...**
- **(low) ...**
## Verification checklist (A–F)
### A. Support window declarations
- [ ] peerDep ranges match the support window
- [ ] Version map / runtime branching covers every supported major
- [ ] Every third-party package the plugin **invokes at runtime** has a peerDep entry. "Invokes" = TS import/`require` OR executor spawns its CLI binary OR inferred plugin emits a target whose `command` invokes its CLI (look for `externalDependencies: ['<pkg>']` in emitted target inputs). Packages the generator installs for the user to consume independently (ESLint plugins loaded by the user's eslintrc, `@types/*`) don't need peer-declaration.
- [ ] Peers needed only when a user opts into a specific surface (executor opt-in, inferred plugin gated on config file presence, opt-in preset) are declared **optional** via `peerDependenciesMeta: { "<pkg>": { "optional": true } }`. Required-non-optional peers are reserved for packages every workspace using the plugin needs.
### B. Generator inputs
- [ ] Generators don't overwrite installed third-party versions
- [ ] `addDependenciesToPackageJson` passes `keepExistingVersions=true` or branches on detected version
- [ ] Fresh-install path installs the latest supported version
### C. Generator outputs
- [ ] Templates compile and run on every supported version
- [ ] Generated `project.json` target shape valid on every major
- [ ] Default option values valid on every major
- [ ] Version map covers every managed third-party dep — no gaps
- [ ] Schema accepts union of options; runtime throws when inapplicable
### D. Migrations (migrations.json + packageJsonUpdates)
- [ ] Cross-major `packageJsonUpdates` declare `requires` per bumped package
- [ ] `packageJsonUpdates` `requires` windows are bilateral (`>=N <M`) by default. One-sided ranges (`<N` with no lower, `>=N` with no upper) are intentional (legacy cleanup, undefined source major, v0→v1 bridge) — flagged in "Needs human decision" or noted in the Findings.
- [ ] Migration entries gate on the destination: `requires` evaluates once at collection time against the version the package lands on in this run (installed only when the run does not bump it), so a bound meant as the source window (`>=9 <10` for "migrating from 9") skips whenever the run bumps past the cap (the storybook bug, #33613). Default is `>=N` alone; add an upper bound only when the migration is inapplicable at or above it (`next >=15.0.0 <16.0.0` on the next-15 instructions entry). Semantics: `.claude/skills/author-migration/SKILL.md`, `requires` section.
- [ ] A migration declares a gate only when its behavior depends on the touched package's version; conditions `requires` cannot express (an OR of alternative package names) get an in-body check instead
- [ ] Nx-only migrations have no third-party `requires`
- [ ] No silent gap in `packageJsonUpdates` across the support window
### E. Runtime
- [ ] Executors branch on installed version where behavior diverges
- [ ] Inferred plugin (createNodes/V2) parses configs across every major
### F. Out-of-window UX
- [ ] Below-floor: throws via shared util naming package + installed + floor; no silent fall-through
## Out-of-scope (deferred follow-ups)
- <e.g., consolidate ... across plugins — separate PR>
References
See "Which references to load" near the top. Don't pull all of them.
1---
2name: multi-version-compliance
3description: >
4 Apply or review multi-version support compliance for first-party Nx
5 plugins. Primary entry point: a Linear task ID (NXC-XXXX) from the
6 "Multi-version supported across plugins" milestone — the task carries the
7 resolved support window, findings, and "Needs human decision" items. Falls
8 back to self-discovery when no task exists. Use when asked to "fix
9 multi-version compliance for @nx/X", "do NXC-XXXX", "review this
10 compliance PR", or when working on a branch / PR titled "multi-version
11 support compliance for @nx/X". Covers the canonical shape
12 (assertSupportedPackageVersion, all-generators-enforce-floor.spec.ts,
13 peer dep alignment, requires-gate auditing, user-pin preservation,
14 executor / inferred-plugin feature gating).
15argument-hint: '[<NXC-XXXX> | @nx/<plugin> | review #<PR>]'
16allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Agent, mcp__linear-server__get_issue, mcp__linear-server__list_comments, mcp__linear-server__get_milestone, mcp__linear-server__list_issues
17metadata:
18 source: https://skillmd.com/skills/nrwl/multi-version-compliance
19---
20
21# Multi-version compliance for Nx plugins
22
23## What this is
24
25The `nx migrate --first-party-only` flag lets users upgrade Nx without
26dragging the managed third-party ecosystems (Angular, Cypress, Playwright,
27Jest, Vitest, ESLint, etc.) along. For that to be safe, every first-party
28plugin must keep working across its declared support window — not silently
29fall through to the latest install constants on older workspaces, not
30silently break on newer ones.
31
32**Source-of-truth split:**
33
34| Source | Owns |
35| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
36| Linear milestone "Multi-version supported across plugins" (project NXC-4072) | What's wrong per plugin, the resolved support window, open human decisions. Per-plugin tasks NXC-4381..NXC-4410 (P1–P29). |
37| This skill | How to implement the canonical shape, code-level anti-patterns, gotchas, findings doc shape (no-task case). |
38
39The skill is the gap-closer: it accepts a Linear task, parses it, drives
40the fix. When no task exists for the plugin, fix mode runs discovery in
41Phase 1–2 and produces a findings doc that mirrors a Linear task body —
42so the user can file it as a new task before proceeding.
43
44**Reference PRs (the canonical shape):**
45
46- `#35587` — `@nx/angular` — merged. Set the precedent. Introduced
47 `throwForUnsupportedVersion`.
48- `#35642` — `@nx/playwright` — merged. Generalized the shared helpers
49 into `@nx/devkit/internal`. Established executor / runtime feature-
50 gating.
51- `#35670` — `@nx/cypress` — merged. Added `excludeGenerators` to the
52 parameterized test helper.
53- `#35671` — `@nx/vitest` — open at time of writing. Demonstrates
54 "drop phantom peer-range claim" and "declared floor < effective floor"
55 patterns.
56
57Before citing any PR by number, verify state — these go stale:
58`gh pr view <N> --repo nrwl/nx --json state`. Verify any unmerged PR's
59contents via `gh pr diff <N> --repo nrwl/nx`.
60
61## Entry points
62
63| Invocation | Mode | Behavior |
64| ----------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
65| `multi-version-compliance <NXC-XXXX>` | Fix (primary) | Fetch task, surface findings + decisions in Phase 2, wait for user OK before Phase 3 edits. |
66| `multi-version-compliance` (no arg) | Ask for task ID | Prompt for NXC-XXXX. |
67| `multi-version-compliance @nx/<plugin>` (bare plugin) | Fix (task lookup) | Look up the per-plugin task in milestone NXC-4072. If found, confirm with user and enter fix mode. If not found, run discovery in Phase 1–2 (rubric against code), present findings, suggest filing as a new task before any edits. |
68| `multi-version-compliance review #<N>` | Review | Fetch PR, derive Linear task from branch name if possible, compare diff vs. task findings (or run pure code-level review if no task). |
69
70**Stop-after-Phase-2 (audit-equivalent):** if you want findings without
71edits, decline to approve at the end of Phase 2. The skill stops, no
72branch, no commits.
73
74**On a branch matching `nxc-NNNN` with no explicit arg:** before
75asking the user, suggest "Use NXC-NNNN?" inferred from the branch name.
76
77## Linear-fetching protocol
78
79Before any code-level work in Linear-driven mode, the skill MUST:
80
811. **Check Linear MCP availability.** If `mcp__linear-server__get_issue`
82 isn't available (MCP server not installed / not connected), tell the
83 user and fall through to the no-task discovery path (fix mode Phase 1
84 step 2). Don't pretend to fetch.
852. **Fetch the task.** `mcp__linear-server__get_issue id="NXC-XXXX"`.
86 If the call errors (invalid ID, network), halt and ask the user to
87 verify the ID.
883. **Verify shape.** Confirm:
89 - 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.
90 - Status. `Done` → ask whether re-audit or follow-up. `Canceled` → halt and ask.
914. **Read description sections.** Every per-plugin task has:
92 - **Plugin:** — path, upstream support, peerDep declarations, per-major install map, paired secondaries.
93 - **Needs human decision** — open items blocking implementation.
94 - **Findings** — `(high|medium|low)` items with `[file:line]` and a suggested fix per item.
95 - **Verification checklist** — Sections A (Support window declarations) / B (Generator inputs) / C (Generator outputs) / D (Migrations) / E (Runtime) / F (Out-of-window UX).
965. **Fetch comments.** `mcp__linear-server__list_comments issueId="..."`.
97 Audits attached as files / linked uploads may carry additional
98 context.
996. **Surface "Needs human decision" as a batch.** Restate every decision
100 item in chat. The user can resolve all, defer some, or override.
101 Block until the user has acknowledged the set — don't proceed silently.
1027. **Translate findings → code changes.** Map each finding to a canonical
103 pattern in `references/canonical-shape.md`. The Linear task's
104 suggested fix is the authoritative scope; the skill verifies it
105 conforms to the canonical shape and flags any deviation.
1068. **Run the A–F checklist** against the final code state. The task's
107 checklist is the agreed scope. The skill verifies code-level
108 conformance.
109
110**Default to the task's resolved support window.** Don't re-derive it
111from code unless the user explicitly overrides. If the user overrides:
112restate the new window and confirm before applying.
113
114**Don't expand scope beyond the task's Findings without asking.** If you
115spot a new issue mid-fix: stop, present it, ask whether to (a) add it to
116this PR, (b) defer as a follow-up, or (c) update the Linear task as a
117comment.
118
119## Mode workflows
120
121### Fix mode (primary)
122
123**Phase 1 — Read.**
124
1251. If a Linear task ID was provided, fetch it per the Linear-fetching
126 protocol. If only a plugin name was provided, look up the per-plugin
127 task in milestone NXC-4072.
1282. **No task case.** If no task exists for this plugin: run discovery
129 instead — apply the policy ladder for the support window
130 (Rule 1: upstream LTS for Angular/React/ESLint/Next/Expo; Rule 2:
131 N & N-1; widen to existing supported set if larger), inventory the
132 plugin's code against the A–F rubric, find the effective floor by
133 walking imports, classify all results as new findings. The skill is
134 producing audit-quality output for a plugin that wasn't ticketed.
1353. If on a branch matching `nxc-NNNN`, read recent commits to understand
136 prior scope decisions.
1374. Read `references/canonical-shape.md` and `references/anti-patterns.md`.
138
139**Phase 2 — Align.**
140
1415. **(task case)** Surface every "Needs human decision" item from the
142 task as a batch. Wait for resolutions.
1436. **(task case)** Restate the Findings list with severity tags. Confirm
144 scope.
1457. **(no-task case)** Surface findings discovered from the rubric
146 inventory + decisions the rubric surfaces (floor raise/drop, peer
147 declarations, optional-vs-required peer, one-sided gates, etc.).
148 Suggest filing them as a new Linear task in milestone NXC-4072
149 before proceeding to Phase 3.
1508. **User OK gate.** Wait for explicit "proceed" before Phase 3.
151 Declining stops the skill — no branch, no edits. (This is the
152 audit-equivalent.)
153
154**Phase 3 — Implement** (per `canonical-shape.md`).
155
1569. Branch from `master` if needed using the repo's `nxc-NNNN` convention.
15710. Order: any shared-helper extension lands first; plugin changes land
158 after. Commit/PR titling defers to the user's conventions.
15911. For each Finding category, apply the canonical pattern:
160 - Section A → peer ranges + version map + install constants. Every
161 third-party package the plugin **invokes at runtime** (TS import,
162 executor spawning the CLI binary, or inferred-plugin emitting a
163 target with `command: '<bin>'`) gets a peer entry. Default to
164 `optional: true` via `peerDependenciesMeta` for gated surfaces
165 (executor opt-in, inferred plugin gated on config file presence).
166 Non-optional peers are reserved for packages every workspace using
167 the plugin needs.
168 - Section B → generator entry asserts, `keepExistingVersions`,
169 fresh-install branch.
170 - Section C → templates, schema stubs with runtime throws,
171 version-map coverage.
172 - Section D → `requires` gates per package per AND-semantics; split
173 mixed entries; retain intentional pre-floor entries. **Default to
174 bilateral bounds** (`>=N <M`) for cross-major `packageJsonUpdates`
175 windows. One-sided windows (`<N` with no lower, `>=N` with no
176 upper) need a justified reason (legacy cleanup, undefined source,
177 v0→v1 bridge) — record the reason in the findings doc or as a code
178 comment. Migration entries gate on the destination instead,
179 usually `>=N` alone (checklist below).
180 - Section E → executor and inferred-plugin feature gates.
181 - Section F → below-floor throw via shared util.
182 - **Cross-cutting:** if the fix changes runtime behavior, update any
183 in-codebase docs (`astro-docs/`, `docs/`, inline `.md`) that
184 describe the changed behavior. Docs that contradict the code are a
185 correctness bug, not a PR-body concern.
18612. If during implementation you spot something not in the task's
187 Findings: stop, surface it, ask whether to (a) add to this PR, (b)
188 defer as a follow-up, or (c) update the Linear task as a comment.
189
190**Phase 4 — Tests** (same commit as Phase 3 usually).
191
19213. Add `all-generators-enforce-floor.spec.ts` — parameterized via
193 `assertGeneratorsEnforceVersionFloor`. This exercises every
194 generator's floor assert and is the high-value spec.
19514. Footgun: assert calls must be in place in every generator BEFORE
196 running the parameterized spec, or every untouched generator fails
197 and you'll restart.
19815. Optional: a per-plugin `assert-supported-<pkg>-version.spec.ts`
199 with the 5 canonical cases. The shared `assertSupportedPackageVersion`
200 already has full coverage in devkit, so this is mostly symmetry
201 across the PR series — skip unless the user asks.
202
203**Phase 5 — Verify locally.**
204
20516. `npx nx test <plugin> --testPathPattern="all-generators-enforce-floor"`
206 (add `assert-supported-` if you added the optional wrapper spec).
20717. `npx nx test <plugin> --testPathPattern="<modified-generator>"` per
208 touched generator.
20918. `npx nx format`.
210
211**Phase 6 — Hand off.** Code changes complete. The user drives
212commit/push/PR per their own conventions (loaded globally from
213`~/.claude/memory/workflow/git/`). This skill does not enforce PR title,
214body, commit shape, or related-issues format.
215
216### Review mode
217
2181. **Fetch PR.** `gh pr view <N> --repo nrwl/nx` and
219 `gh pr diff <N> --repo nrwl/nx`. For a local branch:
220 `git diff master...HEAD`.
2212. **Derive the Linear task.** Branch name `nxc-NNNN` → `NXC-NNNN`. If
222 no match: ask the user.
2233. **Fetch the task** (if derivable). Compare diff vs. task Findings:
224 every Finding addressed; nothing extra without justification. Flag
225 scope drift.
226 **If no task and the user has none:** skip task-comparison; run pure
227 code-level review against `canonical-shape.md` and `anti-patterns.md`.
2284. **Code-level checks.** Run the "Code-level verification (review-mode
229 lens)" section of `canonical-shape.md`. Cross-reference
230 `anti-patterns.md`. For each finding, anchor at `file:line` and cite
231 which reference PR / file demonstrates the correct pattern.
232 **Scope:** code, configs, migrations, and in-codebase docs that claim
233 runtime behavior. NOT PR title / body / commit shape — those defer to
234 the user's PR conventions.
2355. **Classify each finding.**
236 - **Only two inline categories:** `[blocker]` and `[non-blocker]`. No
237 "open question," "ask," or other inline tags. Questions for the
238 author surface in the closing "Open questions for author" block,
239 drawn from non-blocker findings — list each question once.
240 - **Severity is independent of scope-drift.** A finding can be both a
241 blocker AND not in the Linear task. Flag it as a blocker in the
242 code-level section AND list it under "in PR but not in Linear task"
243 in scope drift. Don't hedge with "in this PR or follow-up?" — if
244 it's a blocker, the answer is "this PR."
245 - **Group related non-blockers.** When multiple non-blockers describe
246 symptoms of one blocker (e.g., five symptoms of a single
247 `version-utils.ts` duplication), list them as sub-bullets under
248 the blocker with "(resolved when §X is fixed)" rather than as N
249 separate top-level non-blockers.
250 - **Be terse on passes.** A section with no findings gets a single
251 summary line ("Pass — all 7 generator entries assert at first
252 statement"), not a per-file enumeration. Detail is reserved for
253 blockers and non-blockers. The reviewer's audience skims for
254 actionable items; passing checks should not eat reading budget.
2556. **Output.** Markdown checklist of blockers / non-blockers anchored at
256 `file:line`, followed by the structured verdict block from
257 `canonical-shape.md` §"Verdict template". The verdict block is the
258 skimmable index — produce it, don't substitute a free-form prose
259 summary. Do not post via `gh pr review` unless the user explicitly
260 asks.
261
262## Which references to load (context hygiene)
263
264| Mode | Required | Optional |
265| ---------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
266| Fix | `canonical-shape.md`, `anti-patterns.md` | `gotchas.md` (effective floor, ecosystem lockstep, cypress inline tree), `examples.md` (when copying a pattern) |
267| Review | `anti-patterns.md`, `canonical-shape.md` (especially the "Code-level verification" section) | `gotchas.md` (cross-plugin coordination, lockstep), `examples.md` (when citing) |
268| "What is compliance?" answer | none | answer from SKILL.md alone |
269
270References are ~100–500 lines each. Don't pull all of them just because
271you're invoked. Match the load to the mode.
272
273## Critical rules (apply in every mode)
274
2751. **Linear task is the source of truth for scope** (ratified decisions
276 and Findings).
277 - (a) Don't produce a parallel scope document. The task IS the scope.
278 Fix mode runs against the task as input — drift checks, new
279 findings, and decisions feed back to the task (via comments or as
280 deferred items), not into a competing source of truth.
281 - (b) Don't expand a fix beyond the task's Findings without
282 surfacing the new issue.
283 - (c) Don't second-guess the task's resolved support window without
284 an explicit user override.
2852. **Do not create or duplicate shared helpers.** They live in
286 `@nx/devkit/internal` (`assertSupportedPackageVersion`,
287 `getInstalledPackageVersion`, `getDeclaredPackageVersion`,
288 `throwForUnsupportedVersion`, `normalizeSemver`, `isNonSemverDistTag`)
289 and `@nx/devkit/internal-testing-utils`
290 (`assertGeneratorsEnforceVersionFloor`). Reject any local
291 re-implementation (`cleanVersion`, `getInstalled<Pkg>VersionRuntime`,
292 private `throwBelowFloor`, etc.). See `canonical-shape.md`.
2933. **Above-ceiling is silent fallthrough.** Do not warn, do not throw,
294 do not branch. Reject `throwAboveWindow`, `warnAboveCeiling`,
295 `versions()` with `switch + throw default:`. The only throw is below
296 the declared floor.
2974. **`keepExistingVersions: true` is for generators only.** Migration
298 generators (`src/migrations/`) are exempt — their job is to bump.
299 Do not flag missing flags in migration code.
3005. **Floor assert is the first statement in the function doing the
301 actual work.** Wrapper/internal split (cypress, playwright): in
302 `*Internal`. Single-function generators (angular): in the function
303 itself. Not conditional, not inside an install branch, not after a
304 tree read.
3056. **Phase 1–2 never writes, never branches.** Discovery, finding
306 classification, and decision-surfacing happen on the current branch
307 with no edits. Any working artifact (e.g., a findings doc for a
308 no-task case, multi-plugin scratch notes) goes in `tmp/` (gitignored)
309 and stays uncommitted. No `TRIAGE-REPORT.md` / `AUDIT.md` at repo
310 root. Branch creation and edits start at Phase 3, after the user OK.
3117. **PR / commit conventions are out of scope.** Title format, body shape,
312 commit-message structure, related-issues handling, push flags, etc.
313 are governed by the user's global memory (`pr-creation-shorthand.md`,
314 `push-conventions.md`, `explain-before-committing.md`,
315 `chore-not-fix-non-prod.md`). Don't enforce or flag these from this
316 skill — defer to whatever the user's conventions resolve to at PR time.
317
318## Findings doc template (Phase 2 output, used when no Linear task exists)
319
320When fix mode hits the no-task case (Phase 1 step 2), produce
321`tmp/<plugin>-findings.md` shaped to mirror a Linear task body so the
322user can file it as a new task in milestone NXC-4072 before proceeding
323to Phase 3.
324
325For plugins managing multiple primary packages, repeat the install-map
326/ decisions / findings bullets per primary.
327
328```md
329# @nx/<plugin> — multi-version support compliance findings
330
331> No Linear task in milestone NXC-4072. This doc is filing-ready —
332> create the task with this body before proceeding to fix.
333
334## Plugin
335
336- Path: packages/<plugin>
337- Upstream support: <official policy if any, else "no formal LTS">
338- peerDep declarations: <list>
339- Per-major install (`<file>` branches on installed `<package>` major):
340 - v<N-1>: <constants>
341 - v<N>: <constants> (default)
342- Paired secondaries: <list of ecosystem-locked siblings>
343
344## Needs human decision
345
3461. <decision 1 — e.g., raise floor to vN.0.0 vs keep current>
3472. <decision 2 — e.g., drop ^1.0.0 from peer (no v1 install lane)>
348
349## Findings
350
351- **(high) <one-line summary>** [file:line]
352 _Suggested fix_: <one-line>
353- **(medium) ...**
354- **(low) ...**
355
356## Verification checklist (A–F)
357
358### A. Support window declarations
359
360- [ ] peerDep ranges match the support window
361- [ ] Version map / runtime branching covers every supported major
362- [ ] Every third-party package the plugin **invokes at runtime** has a peerDep entry. "Invokes" = TS import/`require` OR executor spawns its CLI binary OR inferred plugin emits a target whose `command` invokes its CLI (look for `externalDependencies: ['<pkg>']` in emitted target inputs). Packages the generator installs for the user to consume independently (ESLint plugins loaded by the user's eslintrc, `@types/*`) don't need peer-declaration.
363- [ ] Peers needed only when a user opts into a specific surface (executor opt-in, inferred plugin gated on config file presence, opt-in preset) are declared **optional** via `peerDependenciesMeta: { "<pkg>": { "optional": true } }`. Required-non-optional peers are reserved for packages every workspace using the plugin needs.
364
365### B. Generator inputs
366
367- [ ] Generators don't overwrite installed third-party versions
368 - [ ] `addDependenciesToPackageJson` passes `keepExistingVersions=true` or branches on detected version
369- [ ] Fresh-install path installs the latest supported version
370
371### C. Generator outputs
372
373- [ ] Templates compile and run on every supported version
374- [ ] Generated `project.json` target shape valid on every major
375- [ ] Default option values valid on every major
376- [ ] Version map covers every managed third-party dep — no gaps
377- [ ] Schema accepts union of options; runtime throws when inapplicable
378
379### D. Migrations (migrations.json + packageJsonUpdates)
380
381- [ ] Cross-major `packageJsonUpdates` declare `requires` per bumped package
382- [ ] `packageJsonUpdates` `requires` windows are bilateral (`>=N <M`) by default. One-sided ranges (`<N` with no lower, `>=N` with no upper) are intentional (legacy cleanup, undefined source major, v0→v1 bridge) — flagged in "Needs human decision" or noted in the Findings.
383- [ ] Migration entries gate on the destination: `requires` evaluates once at collection time against the version the package lands on in this run (installed only when the run does not bump it), so a bound meant as the source window (`>=9 <10` for "migrating from 9") skips whenever the run bumps past the cap (the storybook bug, #33613). Default is `>=N` alone; add an upper bound only when the migration is inapplicable at or above it (`next >=15.0.0 <16.0.0` on the next-15 instructions entry). Semantics: `.claude/skills/author-migration/SKILL.md`, `requires` section.
384- [ ] A migration declares a gate only when its behavior depends on the touched package's version; conditions `requires` cannot express (an OR of alternative package names) get an in-body check instead
385- [ ] Nx-only migrations have no third-party `requires`
386- [ ] No silent gap in `packageJsonUpdates` across the support window
387
388### E. Runtime
389
390- [ ] Executors branch on installed version where behavior diverges
391- [ ] Inferred plugin (createNodes/V2) parses configs across every major
392
393### F. Out-of-window UX
394
395- [ ] Below-floor: throws via shared util naming package + installed + floor; no silent fall-through
396
397## Out-of-scope (deferred follow-ups)
398
399- <e.g., consolidate ... across plugins — separate PR>
400```
401
402## References
403
404See "Which references to load" near the top. Don't pull all of them.