angular-agents-skills 1.0.0

package/skills/quality/pr-reviewer/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: pr-reviewer
+description: 'Review a Pull Request using the Azure DevOps MCP. Use this skill to fetch PR details, changed files, and provide a structured architectural review. Trigger on: "review PR", "revisa la PR", "PR review", "check pull request".'
+
+argument-hint: 'PR number or URL'
+---
+
+# Pull Request Reviewer Skill
+
+You are a senior architect reviewing a Pull Request.
+
+## 1. Context Injection (MANDATORY)
+For all Azure DevOps MCP tool calls, you MUST explicitly use:
+- **Organization:** `<ORGANIZATION>`
+- **Project:** `<PROJECT>`
+- **Repository:** `<REPOSITORY>`
+
+> **Setup:** Replace the placeholders above with your Azure DevOps values before using this skill.
+
+## 2. Output & Language Rules (STRICT)
+- **SILENT BACKGROUND PROCESSING:** Run all data-fetching tools silently in the background. Do not output logs, intermediate thoughts, status updates, or tool execution steps.
+- **INTERACTIVE GATEWAY:** Your very first output in the chat must be the complete review draft (following the Output Format) immediately followed by the approval question.
+- **LANGUAGE:** All reviews, draft comments, and interactions must be written entirely in Spanish.
+
+## 3. Step-by-Step Execution Flow
+
+### Step 1 — Fetch Metadata and Changes
+1. Call `mcp_ado_repo_pull_request` with `action: 'get'` to get basic PR details.
+2. Call `mcp_ado_repo_pull_request` with `action: 'get_changes'`. The inline `lineDiffBlocks` inside this response is your **ONLY source of truth** for files and modified lines.
+
+### Step 2 — Analyze Diffs and Generate Draft
+Review each changed file using **ONLY** the inline diffs from Step 1.
+- Present the review in the chat using the exact **Output Format** defined below.
+- At the absolute end of your response, append this exact question:
+  > "¿Publico estos comentarios en la PR o quieres modificar algo primero?"
+- **STOP HERE.** Do NOT call any write tools or threads yet.
+
+### Step 3 — Publish Upon Explicit Confirmation
+- Wait for the user's confirmation (e.g., "sí", "adelante", "ok", "publícalos").
+- Once confirmed, publish each approved comment as an individual thread using `mcp_ado_repo_pull_request_thread_write` with `action: 'create'`.
+- If modifications are requested, update the draft and re-ask before publishing.
+
+---
+
+## 4. Scope and Forbidden Actions (CRITICAL)
+- **Models are Classes:** If your project convention defines models as `class` (not `interface`), do NOT suggest converting a model class to an interface. Adapt this rule to your project's conventions.
+- **Strict PR Scope:** Review only the lines changed in the PR. Do NOT read full files with `mcp_ado_repo_file` (`action: 'get_content'`) unless the inline diff context is completely unreadable (e.g., verifying a heavily broken import shape).
+- **No Codebase Exploration:** Do NOT use global search tools (`search/*`). Do NOT read files from the target branch (`dev`/`main`). Do NOT follow import chains into unrelated files.
+- **Exclusions:** Do not review or comment on test code, and do not suggest unrelated refactors outside the explicit PR diff scope.
+- **Efficiency:** Process each file exactly once. Do not loop or re-read files. If a file has no issues, explicitly confirm it is correct; do not skip it.
+
+---
+
+## 5. Comment Tone & Voice
+- **Teammate Persona:** Colloquial, direct, short sentences. Avoid corporate or hyper-formal phrasing.
+- **Suggestion-First:** Frame issues gently ("te sugiero", "podrías", "¿qué te parece si...?").
+- **Concise Whys:** Maximum 1 sentence explaining the technical reason behind a suggestion.
+- **Prose Over Bullets:** If a point takes 2-3 sentences, write it as a fluid paragraph instead of a bullet list.
+- **Genuine Approvals:** Keep positive validations brief and authentic.
+
+---
+---
+
+## 6. Output Format
+
+### 6.1 Header block (once, at the top of the full review)
+
+```md
+# Revisión de PR #[número] — [título de la PR]
+
+**Autor:** [nombre]  
+**Rama:** `[source]` → `[target]`  
+**Archivos modificados:** [N]
+
+---
+```
+
+### 6.2 Per-file block (repeat for every changed file)
+
+```md
+## 📄 `ruta/del/archivo-modificado.ts`
+
+### ✅ [breve descripción de lo que cambió y está bien]
+Bien hecho. [Una oración de por qué se ajusta a las convenciones del proyecto.]
+
+---
+
+### 🔴 Blocker: [título corto del problema]
+
+**📍** `NombreClase.nombreMetodo` — línea ~[N]
+
+[Máximo 2–3 oraciones: qué está mal, por qué rompe el contrato o la seguridad, y qué hacer.]
+
+```ts
+// código corregido
+```
+
+---
+
+### 🟡 Sugerencia: [título corto]
+
+**📍** `NombreClase.nombrePropiedad` — línea ~[N]
+
+[Máximo 2–3 oraciones: qué desvío hay, por qué importa y cómo corregirlo.]
+
+```ts
+// código sugerido
+```
+
+---
+```
+
+### 6.3 Summary block (once, at the end of the full review)
+
+```md
+---
+
+## 📊 Resumen
+
+| Nivel | Cantidad |
+|---|---|
+| 🔴 Blockers | N |
+| 🟡 Sugerencias | N |
+| 🟢 Sin problemas | N |
+
+[1–2 oraciones de cierre: valoración global de la PR y siguiente paso recomendado.]
+```
+
+### 6.4 Approval gate (last line, always)
+
+> "¿Publico estos comentarios en la PR o quieres modificar algo primero?"

package/skills/quality/vitest-angular-components/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: vitest-angular-components
+description: Configure and write component tests for standalone Angular components using Vitest browser mode with Playwright, including TestBed setup and overlay cleanup.
+---
+
+# Testing Angular Components with Vitest (Browser Mode)
+
+This skill covers setting up and writing tests for standalone Angular components using Vitest's browser mode (real browser via Playwright) instead of Karma/Jasmine.
+
+## When to use
+- Writing unit/component tests for a standalone Angular component/directive/service in this kind of workspace.
+- Setting up a new library's test configuration to match the workspace's existing Vitest setup.
+- Debugging flaky tests caused by leftover overlay DOM elements between tests.
+
+## `vitest.config.ts` essentials
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      provider: 'playwright',
+      instances: [{ browser: 'chromium' }],
+      viewport: { width: 1920, height: 1080 },
+    },
+    setupFiles: ['./setup-vitest.ts'],
+  },
+});
+```
+
+## `setup-vitest.ts` — global TestBed initialization
+```typescript
+import '@analogjs/vitest-angular/setup-zone'; // or the workspace's equivalent zoneless setup
+import { getTestBed } from '@angular/core/testing';
+import { BrowserTestingModule, platformBrowserTesting } from '@angular/platform-browser/testing';
+
+getTestBed().initTestEnvironment(BrowserTestingModule, platformBrowserTesting());
+
+// Global ResizeObserver mock — required since components query element size in effects
+global.ResizeObserver = class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+afterEach(() => {
+  // Clean up any overlay elements dynamically appended to <body>
+  // (see dynamic-component-creation / overlay-animation-lifecycle skills)
+  document.querySelectorAll('.modal, .popover, .toast, .tooltip, .slide-panel, .overlay')
+    .forEach(el => el.remove());
+  document.body.classList.remove('overlay-open');
+});
+```
+This cleanup step is critical: overlay services attach elements directly to `document.body` (outside the component fixture), so `TestBed`'s automatic teardown never removes them — leftover nodes leak state and z-index stacking into the next test.
+
+## Writing a component test
+```typescript
+import { render, screen } from '@testing-library/angular'; // or TestBed.createComponent directly
+import { ButtonComponent } from './ui-button.component';
+
+describe('ButtonComponent', () => {
+  it('applies the size and type host classes', async () => {
+    const fixture = TestBed.createComponent(ButtonComponent);
+    fixture.componentRef.setInput('size', 'big');
+    fixture.componentRef.setInput('type', 'primary');
+    fixture.detectChanges();
+
+    const host = fixture.nativeElement as HTMLElement;
+    expect(host.classList.contains('ui-button-size-big')).toBe(true);
+    expect(host.classList.contains('ui-button-type-primary')).toBe(true);
+  });
+});
+```
+Use `fixture.componentRef.setInput(name, value)` to set signal `input()`s from tests — direct property assignment (`component.size = 'big'`) does not work since inputs are read-only signals.
+
+## Testing signal-driven effects/computed values
+- Call `fixture.detectChanges()` (or `await fixture.whenStable()`) after changing an input to allow `effect()`/`afterRenderEffect()` to flush.
+- For `computed()` values, just read `component.someComputed()` directly — no `detectChanges()` needed since computed signals update synchronously on read.
+
+## Testing overlay-based components (modal/popover/toast)
+- Trigger the service call (`modalService.create(...)`) inside the test, then query `document.body` (not the fixture) for the rendered overlay content, since it's mounted outside the fixture's DOM tree.
+- Await the `afterOpened$`/`afterClosed$` observables exposed by the returned ref rather than arbitrary timeouts, to synchronize with the animation lifecycle (see `overlay-animation-lifecycle`).
+
+## Pitfalls
+- Forgetting the `afterEach` overlay cleanup causes intermittent failures when tests run in sequence (duplicate `role="dialog"` elements, click interception by a stale backdrop).
+- Testing `@defer` blocks requires explicitly resolving the deferred state (e.g. via Angular's testing utilities for defer blocks) — a plain `detectChanges()` will not render the deferred content on its own.
+- Since tests run in a real browser (Playwright/Chromium), avoid Node-only APIs in test files; use browser-safe utilities.

package/skills/reactivity/signals-effects/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: signals-effects
+description: Use effect() and afterRenderEffect() correctly for signal-driven side effects, replacing ngOnChanges, and avoiding infinite update loops.
+---
+
+# Signal Effects (`effect()` / `afterRenderEffect()`)
+
+This skill covers running side effects in response to signal changes, and choosing between `effect()` and `afterRenderEffect()`.
+
+## When to use
+- You need to react to a signal/input change with a side effect that is **not** a derived value (DOM manipulation, calling a service, syncing to a non-signal API).
+- You need logic that must run **after** the DOM has been updated/rendered (measuring elements, `requestAnimationFrame` work, `ResizeObserver` setup).
+- You are replacing legacy `ngOnChanges` lifecycle logic in a component that has been migrated to signal inputs.
+
+## `effect()`
+Runs in the reactive context, tracking any signals read synchronously inside it. Must be created in an injection context (constructor, or field initializer of a component/directive/service).
+
+```typescript
+constructor() {
+  effect(() => {
+    if (this.slotLeft().nativeElement.children.length > 0) {
+      this.slotLeftClassValue.set(true);
+    }
+  });
+}
+```
+
+Rules:
+- Only for side effects — do not use it to compute a value another part of the component needs (use `computed()` instead).
+- Avoid writing to a signal that the same effect also reads — this causes infinite loops. If you must write to a signal inside an effect, make sure it's not one of the effect's own dependencies.
+- Effects run once immediately on creation, then again whenever a tracked signal changes.
+
+## `afterRenderEffect()`
+Same reactive semantics as `effect()`, but guaranteed to run after Angular has finished rendering the current change detection cycle. Use it for anything that reads the DOM or needs layout to be settled.
+
+```typescript
+constructor() {
+  afterRenderEffect(() => {
+    const displayedColumns: string[] = this.displayedColumns();
+    const lockedColumns: string[] = this.lockedColumns();
+    this.setTableElements();
+    requestAnimationFrame(() => {
+      this.minTableWidth.set(this.getColumnsWidth(true));
+    });
+  });
+}
+```
+
+Use this instead of `effect()` whenever the callback:
+- Reads `ElementRef`/`nativeElement` geometry (`offsetWidth`, `getBoundingClientRect`).
+- Needs to run after `viewChild()`/`contentChild()` results are guaranteed to reflect the latest template.
+
+## Replacing `ngOnChanges`
+| Legacy pattern | Signals replacement |
+|---|---|
+| `ngOnChanges(changes)` reacting to one `@Input()` | `effect(() => { const v = this.myInput(); ... })` |
+| `ngOnChanges` computing a derived value | `computed()` — no effect needed |
+| `ngOnChanges` doing DOM work after an input change | `afterRenderEffect()` |
+
+## Pitfalls
+- Don't call `.set()` on the same signal you're reading in the same `effect()` without an `untracked()` guard — infinite loop risk.
+- Don't use `effect()` for value derivation reachable via `computed()` — effects can't be used as inputs to templates and add unnecessary reactivity overhead.
+- Remember `effect()`/`afterRenderEffect()` need an injection context; if created outside the constructor (e.g. in a method), pass `{ injector }` explicitly.

package/skills/reactivity/signals-inputs-outputs/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: signals-inputs-outputs
+description: Migrate Angular @Input()/@Output() decorators to the modern signal-based input(), output(), and model() APIs with defaults, required fields, and transforms.
+---
+
+# Signals-based Inputs & Outputs
+
+This skill helps write or refactor Angular component inputs/outputs using the Angular 17+ functional API instead of the `@Input()`/`@Output()` decorators.
+
+## When to use
+- Creating a new standalone component that needs configurable properties or events.
+- Refactoring a component that still uses `@Input()`/`@Output()` decorators.
+- Needing two-way bound properties (replacement for `@Input() x` + `@Output() xChange`).
+
+## Key APIs
+
+### `input()`
+```typescript
+// Optional input with a default value
+size = input<'small' | 'medium' | 'big'>('medium');
+
+// Required input (no default, must be provided by the consumer)
+label = input.required<string>();
+
+// Input with a transform function (e.g. coerce string attribute to boolean)
+disabled = input(false, { transform: booleanAttribute });
+
+// Alias the public input name
+value = input<string>('', { alias: 'inputValue' });
+```
+Inputs are read-only signals. Read them with `this.size()`, never assign directly.
+
+### `output()`
+```typescript
+calendarOpened = output<void>();
+searchEvent = output<string>();
+rowSelected = output<any>();
+
+// Emitting
+this.calendarOpened.emit();
+this.searchEvent.emit(this.searchText());
+```
+`output()` replaces `@Output() x = new EventEmitter<T>()`. No need to import `EventEmitter` for this case.
+
+### `model()` (two-way binding)
+```typescript
+// Component
+checked = model<boolean>(false);
+
+// Usage in template: [(checked)]="isChecked"
+this.checked.set(true); // updates the bound parent value automatically
+```
+Use `model()` only when the component genuinely needs to mutate a parent-bound value (e.g. checkbox, toggle). Prefer plain `input()` + `output()` when the parent should stay in control of the source of truth.
+
+## Migration checklist
+1. Replace `@Input() foo: T;` → `foo = input<T>();` (or `input.required<T>()` if it had no default and was always provided).
+2. Replace `@Output() foo = new EventEmitter<T>();` → `foo = output<T>();`.
+3. Remove `EventEmitter`/`Input`/`Output` imports that are no longer used.
+4. Update every internal read of `this.foo` to `this.foo()` (inputs are signals now).
+5. Update templates: input signals are read the same way in bindings (`[value]="foo()"` if read inside a getter/computed, but plain property bindings from the parent don't need `()`— only accessed from within the component's own TS/template as a signal call).
+6. If the input value was watched via `ngOnChanges`, replace with `effect()` reading the signal, or `computed()` if it's a pure derivation (see the `signals-effects` and `signals-state-management` skills).
+
+## Example
+```typescript
+@Component({ selector: 'ui-button', ... })
+export class ButtonComponent {
+  size = input<ButtonSize>('medium');
+  type = input<ButtonType>('primary');
+  buttonType = input<'button' | 'submit' | 'reset'>('button');
+}
+```
+
+## Pitfalls
+- Do not use `input()` results as a mutable variable — they are read-only; use `signal()` for local mutable state instead.
+- Don't wrap `input()` calls in `effect()` unnecessarily if a `computed()` would do — see `signals-state-management`.
+- `model()` creates an implicit two-way contract with the parent; document it clearly since it's easy to miss in code review.

package/skills/reactivity/signals-state-management/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: signals-state-management
+description: Manage local Angular component state reactively using signal(), computed(), and linkedSignal(), and know when to use each.
+---
+
+# Signals State Management
+
+This skill covers reactive local state in Angular components using the Signals primitives `signal()`, `computed()`, and `linkedSignal()`.
+
+## When to use
+- A component needs mutable internal state (selection, open/closed, search text, loading flags).
+- A value is fully derived from other signals/inputs (should never be set directly).
+- A piece of state should reset/re-sync whenever an upstream signal (often an `input()`) changes, but can also be locally overridden afterward.
+
+## Key APIs
+
+### `signal()` — mutable state
+```typescript
+selectedItems = signal<any[]>([]);
+searchText = signal<string>('');
+isLoading = signal<boolean>(false);
+
+// Mutating
+this.searchText.set('new value');
+this.selectedItems.update(items => [...items, newItem]);
+```
+Use `signal()` for state that is genuinely owned by the component and changes over time (event handlers, user interaction).
+
+### `computed()` — derived, read-only state
+```typescript
+isAllSelected = computed<boolean>(() =>
+  !this.isLoading() && this.flatData().length > 0 &&
+  this.flatData().every(item =>
+    this.selectedItems().findIndex(x => x[this.keyValue()] === item[this.keyValue()]) !== -1
+  )
+);
+
+hasFooter = computed<boolean>(() =>
+  Object.keys(this.templates()).some(key => this.templates()[key].footerTemplate())
+);
+```
+Rules:
+- Never call `.set()`/`.update()` on a `computed()` — it has no setter.
+- Keep the function pure — no side effects, no `console.log` mutating outside state.
+- Prefer `computed()` over `effect()` whenever the goal is "produce a value", not "perform an action".
+
+### `linkedSignal()` — resettable/derived-but-overridable state
+```typescript
+// Datepicker: selectedDate starts synced to the `date` input,
+// but the user can pick a different date locally afterward.
+date = signal<CalendarSelectedDatesNullable>(null);
+selectedDate = linkedSignal<CalendarSelectedDatesNullable>(() => this.date());
+```
+Use `linkedSignal()` instead of `computed()` when:
+- The value should re-initialize whenever the source signal changes, AND
+- The component also needs to write a *different* value locally afterward (something `computed()` cannot do, since it's read-only).
+
+Common use case: a component receives a value via `input()`, wants to let the user modify a local working copy, but reset that working copy whenever the input changes (e.g. date pickers, editable form drafts).
+
+## Decision guide
+| Need | Use |
+|---|---|
+| Mutable state owned by the component | `signal()` |
+| Value 100% derived from other signals, never set directly | `computed()` |
+| Value initialized from another signal, but can diverge afterward | `linkedSignal()` |
+
+## Pitfalls
+- Don't put expensive/impure logic inside `computed()` — it re-runs on every dependency change.
+- Don't use `signal()` for something that's purely derived — duplicating state via `effect()` + `signal()` when `computed()` would work leads to sync bugs.
+- Remember `linkedSignal()` still returns a writable signal — treat writes as deliberate local overrides, not permanent replacements of the source signal.