2026.5.0

.claude/agents/raise-pull-request.md

@@ -0,0 +1,225 @@
+---
+name: raise-pull-request
+description: |
+  Use this agent when creating a pull request for the Home Assistant core repository after completing implementation work. This agent automates the PR creation process including running tests, formatting checks, and proper checkbox handling.
+model: inherit
+color: green
+tools: Read, Bash, Grep, Glob
+---
+
+You are an expert at creating pull requests for the Home Assistant core repository. You will automate the PR creation process with proper verification, formatting, testing, and checkbox handling.
+
+**Execute each step in order. Do not skip steps.**
+
+## Step 1: Gather Information
+
+Run these commands in parallel to analyze the changes:
+
+```bash
+# Get current branch and remote
+git branch --show-current
+git remote -v | grep push
+
+# Determine the best available dev reference
+if git rev-parse --verify --quiet upstream/dev >/dev/null; then
+  BASE_REF="upstream/dev"
+elif git rev-parse --verify --quiet origin/dev >/dev/null; then
+  BASE_REF="origin/dev"
+elif git rev-parse --verify --quiet dev >/dev/null; then
+  BASE_REF="dev"
+else
+  echo "Could not find upstream/dev, origin/dev, or local dev"
+  exit 1
+fi
+
+BASE_SHA="$(git merge-base "$BASE_REF" HEAD)"
+echo "BASE_REF=$BASE_REF"
+echo "BASE_SHA=$BASE_SHA"
+
+# Get commit info for this branch vs dev
+git log "${BASE_SHA}..HEAD" --oneline
+
+# Check what files changed
+git diff "${BASE_SHA}..HEAD" --name-only
+
+# Check if test files were added/modified
+git diff "${BASE_SHA}..HEAD" --name-only | grep -E "^tests/.*\.py$" || echo "NO_TESTS_CHANGED"
+
+# Check if manifest.json changed
+git diff "${BASE_SHA}..HEAD" --name-only | grep "manifest.json" || echo "NO_MANIFEST_CHANGED"
+```
+
+From the file paths, extract the **integration domain** from `homeassistant/components/{integration}/` or `tests/components/{integration}/`.
+
+**Track results:**
+- `BASE_REF`: the dev reference used for comparison
+- `BASE_SHA`: the merge-base commit used for diff-based checks
+- `TESTS_CHANGED`: true if test files were added or modified
+- `MANIFEST_CHANGED`: true if manifest.json was modified
+
+**If no suitable dev reference is available, STOP and tell the user to fetch `upstream/dev`, `origin/dev`, or a local `dev` branch before continuing.**
+
+## Step 2: Run Code Quality Checks
+
+Run `prek` to perform code quality checks (formatting, linting, hassfest, etc.) on the files changed since `BASE_SHA`:
+
+```bash
+prek run --from-ref "$BASE_SHA" --to-ref HEAD
+```
+
+**Track results:**
+- `PREK_PASSED`: true if `prek run` exits with code 0
+
+**If `prek` fails or is not available, STOP and report the failure to the user. Do not proceed with PR creation. If the failure appears to be an environment setup issue (e.g., missing tools, command not found, venv not activated), also point the user to https://developers.home-assistant.io/docs/development_environment.**
+
+## Step 3: Stage Any Changes from Checks
+
+If `prek` made any formatting or generated file changes, stage and commit them as a separate commit:
+
+```bash
+git status --porcelain
+# If changes exist:
+git add -A
+git commit -m "Apply prek formatting and generated file updates"
+```
+
+## Step 4: Run Tests
+
+Run pytest for the specific integration:
+
+```bash
+pytest tests/components/{integration} \
+  --timeout=60 \
+  --durations-min=1 \
+  --durations=0 \
+  -q
+```
+
+**Track results:**
+- `TESTS_PASSED`: true if pytest exits with code 0
+
+**If tests fail, STOP and report the failures to the user. Do not proceed with PR creation.**
+
+## Step 5: Identify PR Metadata
+
+Write a release-note-style PR title summarizing the change. The title becomes the release notes entry, so it should be a complete sentence fragment describing what changed in imperative mood.
+
+**PR Title Examples by Type:**
+| Type | Example titles |
+|------|----------------|
+| Bugfix | `Fix Hikvision NVR binary sensors not being detected` |
+| | `Fix JSON serialization of time objects in anthropic tool results` |
+| | `Fix config flow bug in Tesla Fleet` |
+| Dependency | `Bump eheimdigital to 1.5.0` |
+| | `Bump python-otbr-api to 2.7.1` |
+| New feature | `Add asyncio-level timeout to Backblaze B2 uploads` |
+| | `Add Nettleie optimization option` |
+| Code quality | `Add exception translations to Teslemetry` |
+| | `Improve test coverage of Tesla Fleet` |
+| | `Refactor adguard tests to use proper fixtures for mocking` |
+| | `Simplify entity init in Proxmox` |
+
+## Step 6: Verify Development Checklist
+
+Check each item from the [development checklist](https://developers.home-assistant.io/docs/development_checklist/):
+
+| Item | How to verify |
+|------|---------------|
+| External libraries on PyPI | Check manifest.json requirements - all should be PyPI packages |
+| Dependencies in requirements_all.txt | Only if dependency declarations changed (the `requirements` field in `manifest.json` or `requirements_all.txt`), run `python -m script.gen_requirements_all` |
+| Codeowners updated | If this is a new integration, ensure its `manifest.json` includes a `codeowners` field with one or more GitHub usernames |
+| No commented out code | Visually scan the diff for blocks of commented-out code |
+
+**Track results:**
+- `NO_COMMENTED_CODE`: true if no blocks of commented-out code found in the diff
+- `DEPENDENCIES_CHANGED`: true if the diff changes the `requirements` field in `manifest.json` or changes `requirements_all.txt`
+- `REQUIREMENTS_UPDATED`: true if `DEPENDENCIES_CHANGED` is true and requirements_all.txt was regenerated successfully; not applicable if `DEPENDENCIES_CHANGED` is false
+- `CHECKLIST_PASSED`: true if all items above pass
+
+## Step 7: Determine Type of Change
+
+Select exactly ONE based on the changes. Mark the selected type with `[x]` and all others with `[ ]` (space):
+
+| Type | Condition |
+|------|-----------|
+| Dependency upgrade | Only manifest.json/requirements changes |
+| Bugfix | Fixes broken behavior, no new features |
+| New integration | New folder in components/ |
+| New feature | Adds capability to existing integration |
+| Deprecation | Adds deprecation warnings for future breaking change |
+| Breaking change | Removes or changes existing functionality |
+| Code quality | Only refactoring or test additions, no functional change |
+
+**Track results:**
+- `CHANGE_TYPE`: the selected type (e.g., "Bugfix", "New feature", "Code quality", etc.)
+
+**Important:** All seven type options must remain in the PR body. Only the selected type gets `[x]`, all others get `[ ]`.
+
+## Step 8: Determine Checkbox States
+
+Based on the verification steps above, determine checkbox states:
+
+| Checkbox | Condition to tick |
+|----------|-------------------|
+| The code change is tested and works locally | Leave unchecked for the contributor to verify manually (this refers to manual testing, not unit tests) |
+| Local tests pass | Tick only if `TESTS_PASSED` is true |
+| I understand the code I am submitting and can explain how it works | Leave unchecked for the contributor to review and set manually |
+| There is no commented out code | Tick only if `NO_COMMENTED_CODE` is true |
+| Development checklist | Tick only if `CHECKLIST_PASSED` is true |
+| Perfect PR recommendations | Tick only if the PR affects a single integration or closely related modules, represents one primary type of change, and has a clear, self-contained scope |
+| Formatted using Ruff | Tick only if `PREK_PASSED` is true |
+| Tests have been added | Tick only if `TESTS_CHANGED` is true AND the changes exercise new or changed functionality (not only cosmetic test changes) |
+| Documentation added/updated | Tick if documentation PR created (or not applicable) |
+| Manifest file fields filled out | Tick if `PREK_PASSED` is true (or not applicable) |
+| Dependencies in requirements_all.txt | Tick only if `DEPENDENCIES_CHANGED` is false, or if `DEPENDENCIES_CHANGED` is true and `REQUIREMENTS_UPDATED` is true |
+| Dependency changelog linked | Tick if dependency changelog linked in PR description (or not applicable) |
+| Any generated code has been carefully reviewed | Leave unchecked for the contributor to review and set manually |
+
+## Step 9: Breaking Change Section
+
+**If `CHANGE_TYPE` is NOT "Breaking change" or "Deprecation": REMOVE the entire "## Breaking change" section from the PR body (including the heading).**
+
+If `CHANGE_TYPE` IS "Breaking change" or "Deprecation", keep the `## Breaking change` section and describe:
+- What breaks
+- How users can fix it
+- Why it was necessary
+
+## Step 10: Push Branch and Create PR
+
+Push the branch with upstream tracking, and create a PR against `home-assistant/core` with the generated title and body:
+
+```bash
+# Create PR (gh pr create pushes the branch automatically)
+gh pr create --repo home-assistant/core --base dev \
+  --draft \
+  --title "TITLE_HERE" \
+  --body "$(cat <<'EOF'
+BODY_HERE
+EOF
+)"
+```
+
+### PR Body Template
+
+Read the PR template from `.github/PULL_REQUEST_TEMPLATE.md` and use it as the basis for the PR body. **Do not hardcode the template — always read it from the file to stay in sync with upstream changes.**
+
+Use any HTML comments (`<!-- ... -->`) in the template as guidance to understand what to fill in. For the final PR body sent to GitHub, keep the template text intact — do not delete any text from the template unless it explicitly instructs removal (e.g., the breaking change section when not applicable). Then fill in the sections:
+
+1. **Breaking change section**: If the type is NOT "Breaking change" or "Deprecation", remove the entire `## Breaking change` section (heading and body). Otherwise, describe what breaks, how users can fix it, and why.
+2. **Proposed change section**: Fill in a description of the change extracted from commit messages.
+3. **Type of change**: Check exactly ONE checkbox matching the determined type from Step 7. Leave all others unchecked.
+4. **Additional information**: Fill in any related issue numbers if known.
+5. **Checklist**: Check boxes based on the conditions in Step 8. Leave manual-verification boxes unchecked for the contributor.
+
+**Important:** Preserve all template structure, options, and link references exactly as they appear in the file — only modify checkbox states and fill in content sections.
+
+## Step 11: Report Result
+
+Provide the user with:
+1. **PR URL** - The created pull request link
+2. **Verification Summary** - Which checks passed/failed
+3. **Unchecked Items** - List any checkboxes left unchecked and why
+4. **User Action Required** - Remind user to:
+   - Review and set manual-verification checkboxes ("I understand the code..." and "Any generated code...") as applicable
+   - Consider reviewing two other open PRs
+   - Add any related issue numbers if applicable

.claude/skills/github-pr-reviewer/SKILL.md

@@ -1,18 +1,10 @@
 ---
 name: github-pr-reviewer
-description: Review a GitHub pull request and provide feedback comments. Use when the user says "review the current PR" or asks to review a specific PR.
+description: Reviews GitHub pull requests and provides feedback comments. This is the top skill to use for reviewing Pull Requests from GitHub.
 ---
 
 # Review GitHub Pull Request
 
-## Preparation:
-- Check if the local commit matches the last one in the PR. If not, checkout the PR locally using 'gh pr checkout'. 
-- CRITICAL: If 'gh pr checkout' fails for ANY reason, you MUST immediately STOP.
-    - Do NOT attempt any workarounds. 
-    - Do NOT proceed with the review.
-    - ALERT about the failure and WAIT for instructions.
-    - This is a hard requirement - no exceptions.
-
 ## Follow these steps:
 1. Use 'gh pr view' to get the PR details and description.
 2. Use 'gh pr diff' to see all the changes in the PR.
@@ -35,12 +27,13 @@ description: Review a GitHub pull request and provide feedback comments. Use whe
 - No need to highlight things that are already good.
 
 ## Output format:
-- List specific comments for each file/line that needs attention
+- List specific comments for each file/line that needs attention.
 - In the end, summarize with an overall assessment (approve, request changes, or comment) and bullet point list of changes suggested, if any.
   - Example output:
     ```
     Overall assessment: request changes.
-    - [CRITICAL] Memory leak in homeassistant/components/sensor/my_sensor.py:143
-    - [PROBLEM] Inefficient algorithm in homeassistant/helpers/data_processing.py:87
-    - [SUGGESTION] Improve variable naming in homeassistant/helpers/config_validation.py:45
+    - [CRITICAL] sensor.py:143 - Memory leak
+    - [PROBLEM] data_processing.py:87 - Inefficient algorithm
+    - [SUGGESTION] test_init.py:45 - Improve x variable name
     ```
+  - Make sure to include the file and line number when possible in the bullet points.

.claude/skills/ha-integration-knowledge/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ha-integration-knowledge
+description: Everything you need to know to build, test and review Home Assistant Integrations. If you're looking at an integration, you must use this as your primary reference.
+---
+
+## File Locations
+- **Integration code**: `./homeassistant/components/<integration_domain>/`
+- **Integration tests**: `./tests/components/<integration_domain>/`
+
+## General guidelines
+
+- When looking for examples, prefer integrations with the platinum or gold quality scale level first.
+- Polling intervals are NOT user-configurable. Never add scan_interval, update_interval, or polling frequency options to config flows or config entries.
+- Do NOT allow users to set config entry names in config flows. Names are automatically generated or can be customized later in UI. Exception: helper integrations may allow custom names.
+- For entity actions and entity services, avoid requesting redundant defensive checks for fields already enforced by Home Assistant validation schemas and entity filters; only request extra guards when values bypass validation or are transformed unsafely.
+- When validation guarantees a key is present, prefer direct dictionary indexing (`data["key"]`) over `.get("key")` so invalid assumptions fail fast.
+- Integrations should be thin wrappers. Protocol parsing, device state machines, or other domain logic belong in a separate PyPI library, not in the integration itself. If unsure, ask before inlining.
+
+The following platforms have extra guidelines:
+- **Diagnostics**: [`platform-diagnostics.md`](platform-diagnostics.md) for diagnostic data collection
+- **Repairs**: [`platform-repairs.md`](platform-repairs.md) for user-actionable repair issues
+
+
+## Integration Quality Scale
+
+- When validating the quality scale rules, check them at https://developers.home-assistant.io/docs/core/integration-quality-scale/rules
+- When implementing or reviewing an integration, always consider the quality scale rules, since they promote best practices.
+
+Template scale file: `./script/scaffold/templates/integration/integration/quality_scale.yaml`
+
+### How Rules Apply
+1. **Check `manifest.json`**: Look for `"quality_scale"` key to determine integration level
+2. **Bronze Rules**: Always required for any integration with quality scale
+3. **Higher Tier Rules**: Only apply if integration targets that tier or higher
+4. **Rule Status**: Check `quality_scale.yaml` in integration folder for:
+   - `done`: Rule implemented
+   - `exempt`: Rule doesn't apply (with reason in comment)
+   - `todo`: Rule needs implementation
+
+
+## Testing Requirements
+
+- Tests should avoid interacting or mocking internal integration details. For more info, see https://developers.home-assistant.io/docs/development_testing/#writing-tests-for-integrations

.claude/skills/ha-integration-knowledge/platform-diagnostics.md

@@ -0,0 +1,6 @@
+# Integration Diagnostics
+
+Platform exists as `homeassistant/components/<domain>/diagnostics.py`.
+
+- **Required**: Implement diagnostic data collection
+- **Security**: Never expose passwords, tokens, or sensitive coordinates

.claude/skills/ha-integration-knowledge/platform-repairs.md

@@ -0,0 +1,21 @@
+# Repairs platform
+
+Platform exists as `homeassistant/components/<domain>/repairs.py`.
+
+- **Actionable Issues Required**: All repair issues must be actionable for end users
+- **Issue Content Requirements**:
+  - Clearly explain what is happening
+  - Provide specific steps users need to take to resolve the issue
+  - Use friendly, helpful language
+  - Include relevant context (device names, error details, etc.)
+- **String Content Must Include**:
+  - What the problem is
+  - Why it matters
+  - Exact steps to resolve (numbered list when multiple steps)
+  - What to expect after following the steps
+- **Avoid Vague Instructions**: Don't just say "update firmware" - provide specific steps
+- **Severity Guidelines**:
+  - `CRITICAL`: Reserved for extreme scenarios only
+  - `ERROR`: Requires immediate user attention
+  - `WARNING`: Indicates future potential breakage
+- Only create issues for problems users can potentially resolve