limitless-angular · osnoser1 · Jun 13, 2026 · Jun 13, 2026
diff --git a/.agents/skills/angular-version-support/SKILL.md b/.agents/skills/angular-version-support/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: angular-version-support
+description: Deterministic support for adding, validating, or updating Angular major-version compatibility in the limitless-angular workspace. Use when Codex is asked to add support for a new Angular version, update the Angular peer matrix, validate Angular compatibility, or adjust this repo's Angular compatibility harness, especially for @limitless-angular/sanity.
+---
+
+# Angular Version Support
+
+Use this skill for repo-specific Angular compatibility work in the
+`limitless-angular` workspace.
+
+Before changing files, read
+[`references/limitless-angular-compat.md`](references/limitless-angular-compat.md).
+
+## Workflow
+
+1. Identify the requested Angular major from the user prompt.
+   - If no target major is present, ask for the Angular major before mutating files.
+   - Treat prompts like "Angular 20", "v20", and "major 20" as target major `20`.
+2. Use the deterministic helper when the task is to add a stable Angular major:
+
+   ```bash
+   node .agents/skills/angular-version-support/scripts/add-angular-version.ts --major <major>
+   ```
+
+   Use `--dry-run` before applying when the user asks for a preview.
+3. Audit the project-specific compatibility files listed in the reference.
+4. Run the focused validation commands from the reference.
+5. If general Angular coding changes are required, use `$angular-developer` after
+   the compatibility matrix has been updated.
+
+## Rules
+
+- Do not use Python for this skill's workflow or bundled scripts.
+- Keep bundled scripts executable with plain Node 22; do not require `tsx`,
+  `ts-node`, build steps, or a custom runner.
+- Do not mass-upgrade demo app Angular dependency pins unless the user
+  explicitly asks for a workspace upgrade.
+- Keep stable compatibility rows deterministic: one `floor` row and one
+  `latest` row for every supported Angular major.
diff --git a/.agents/skills/angular-version-support/agents/openai.yaml b/.agents/skills/angular-version-support/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Angular Version Support"
+  short_description: "Update this repo's Angular support matrix"
+  default_prompt: "Use $angular-version-support to add support for Angular 20."
diff --git a/.agents/skills/angular-version-support/references/limitless-angular-compat.md b/.agents/skills/angular-version-support/references/limitless-angular-compat.md
@@ -0,0 +1,89 @@
+# Limitless Angular Compatibility Contract
+
+This workspace publishes `@limitless-angular/sanity` and verifies Angular
+support through the private `@limitless-angular/angular-compat` package.
+Adding support for a stable Angular major means updating the public peer range
+and the generated-consumer compatibility matrix.
+
+## Required Files
+
+- `packages/sanity/package.json`
+  - Update `peerDependencies.@angular/common`.
+  - Update `peerDependencies.@angular/core`.
+  - Update `peerDependencies.@angular/router`.
+  - Keep these three Angular peer ranges identical.
+- `tools/angular-compat/config.json`
+  - Add `angular-<major>-floor` with `mode: "floor"`.
+  - Add `angular-<major>-latest` with `mode: "latest"`.
+  - Set `buildAngularMajor` to the newest stable major represented by
+    `consumerVersionSets`.
+
+Use the helper for this deterministic edit:
+
+```bash
+node .agents/skills/angular-version-support/scripts/add-angular-version.ts --major <major>
+```
+
+The helper also backfills missing `floor`/`latest` rows for stable Angular
+majors that are already declared by the peer range or compatibility config.
+
+For a preview:
+
+```bash
+node .agents/skills/angular-version-support/scripts/add-angular-version.ts --major <major> --dry-run
+```
+
+## Required Audit
+
+After the deterministic edit, search for version-specific branches and stale
+contract text:
+
+```bash
+rg 'VERSION|isAngularVersionLessThan|angular-[0-9]|Angular [0-9]' \
+  packages/sanity tools/angular-compat .github tools/release package.json
+```
+
+Always inspect `packages/sanity/shared/src/angular-versions.ts`. Update it only
+when the requested Angular support changes a real runtime branch or minimum
+version check.
+
+Treat these as compatibility contract surfaces:
+
+- `tools/angular-compat/*.test.mjs`
+- `tools/angular-compat/orchestration-contract.test.mjs`
+- `.github/workflows/ci.yml`
+- `.github/workflows/release-and-publish.yml`
+- `.github/workflows/release-dry-run.yml`
+- `tools/release/src/pipeline.mjs`
+
+Do not change these files only because a new major was added. Change them when
+tests reveal a contract drift or when the user asks to update the orchestration.
+
+## Demo App Pins
+
+The demo and e2e Angular apps currently pin their own Angular toolchains. Do
+not upgrade those app dependencies as part of "add Angular support" unless the
+user asks for a workspace or example-app upgrade. The compatibility harness
+builds and tests generated consumers separately from the demo apps.
+
+## Validation
+
+Run focused validation after updating the support matrix:
+
+```bash
+node --test tools/angular-compat/*.test.mjs
+pnpm run compat:assert
+pnpm run compat:matrix
+```
+
+For real support changes, also run:
+
+```bash
+pnpm run compat:pack
+pnpm run compat:artifact
+pnpm run compat:test --angular <major>
+```
+
+The root `compat:test` script already forwards arguments to the compat package.
+If `compat:test --angular <major>` reports no latest row, re-check
+`tools/angular-compat/config.json` for `angular-<major>-latest`.