Clarify companion skill selection before frontend review (#54067)

.agents/skills/ha-frontend-review/SKILL.md

@@ -7,6 +7,12 @@ description: Home Assistant frontend PR and review guidance, including implement
 
 Use this skill when reviewing Home Assistant frontend changes or preparing a pull request.
 
+## Review Preparation
+
+1. Establish the review scope from the diff and the behavior changed by it.
+2. Before identifying findings, use the [project skill catalogue](../../../AGENTS.md#project-skills) to load every matching companion's `SKILL.md`. Follow applicable companion references in those skills as well; this review skill supplies the workflow, and companions supply the domain-specific criteria.
+3. Apply all loaded guidance within that scope. Report only problems introduced or worsened by the changeset, anchored to changed lines. Read surrounding code to understand affected behavior, not to generate unrelated cleanup or migration requests.
+
 ## Pull Request Body
 
 When creating a pull request, use `.github/PULL_REQUEST_TEMPLATE.md` as the body.
@@ -116,4 +122,3 @@ For user-facing changes, establish the existing design context as part of fronte
 - Record the applicable UI/UX evidence for user-facing changes, whether or not further input is needed.
 - Keep style-only comments secondary unless they affect maintainability or user experience.
 - Prefer small, direct fixes over large refactors during review follow-up.
-- Load the matching `ha-frontend-*` skill when a finding falls within its area.

.github/scripts/check-blocking-labels.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Fails the check when a pull request carries a label that blocks merging, and
+// writes the outcome to the job summary. Invoked from the `check` job in
+// .github/workflows/blocking-labels.yaml via actions/github-script:
+//
+//   const { default: checkBlockingLabels } =
+//     await import(`${process.env.GITHUB_WORKSPACE}/.github/scripts/check-blocking-labels.mjs`);
+//   await checkBlockingLabels({ github, context, core });
+
+export default async function checkBlockingLabels({ context, core }) {
+  const blockingLabels = [
+    "wait for backend",
+    "Needs UX",
+    "Do Not Review",
+    "Blocked",
+    "has-parent",
+  ];
+  const prLabels = context.payload.pull_request.labels.map((l) => l.name);
+  const found = blockingLabels.filter((bl) => prLabels.includes(bl));
+  if (found.length > 0) {
+    const message = `This Pull Request is blocked by label${found.length > 1 ? "s" : ""}: ${found.join(", ")}`;
+    await core.summary
+      .addHeading(":no_entry_sign: Pull Request is blocked", 2)
+      .addRaw(message)
+      .write();
+    core.setFailed(message);
+  } else {
+    await core.summary
+      .addHeading(
+        ":white_check_mark: Pull Request is clear to merge after review",
+        2
+      )
+      .addRaw(
+        "This Pull Request is not blocked by any labels which prevent it from being merged."
+      )
+      .write();
+  }
+}

.github/workflows/blocking-labels.yaml

@@ -0,0 +1,35 @@
+name: Blocking labels
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - labeled
+      - unlabeled
+    branches:
+      - dev
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check for labels which block the Pull Request from being merged
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out workflow scripts
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          sparse-checkout: .github/scripts
+      - name: Check for blocking labels
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { default: checkBlockingLabels } = await import(
+              `${process.env.GITHUB_WORKSPACE}/.github/scripts/check-blocking-labels.mjs`
+            );
+            await checkBlockingLabels({ github, context, core });

AGENTS.md

@@ -37,7 +37,7 @@ Never run `tsc` or `yarn lint:types` with file arguments. When `tsc` receives fi
 
 ## Project Skills
 
-Detailed guidance lives in project skills under `.agents/skills/`. Load the matching skill before detailed implementation or review:
+Detailed guidance lives in `.agents/skills/<name>/SKILL.md`. Load every matching skill before detailed implementation or review. For reviews, load `ha-frontend-review` alongside all companions that apply to the changed code or behavior:
 
 - `ha-frontend-contexts`: Lit contexts, `hass` migration, and rerender-sensitive state access.
 - `ha-frontend-components`: dialogs, forms, alerts, shortcuts, tooltips, panels, and Lovelace cards.