ha-integration-reviewer

HA Integration Reviewer

Review integration code from the perspective of the strictest Home Assistant Reviewer.

Prerequisites

Tool	Type	Required	Install
git	cli	Yes	`brew install git` or git-scm.com
gh	cli	No	`brew install gh` then `gh auth login` (for referencing other integrations)
Context7 MCP	mcp	No	`npx -y @upstash/context7-mcp` — add to Claude Code MCP settings (for HA developer docs)

Do NOT proactively verify these tools on skill load. If a command fails due to a missing tool, directly guide the user through installation and configuration step by step.

Review Process

1. Determine the review scope

# 获取待审查的文件（ha-core 使用 dev 分支）
git diff --name-only HEAD~1  # 最近一次提交
git diff --name-only dev     # 与 dev 分支的差异（ha-core 主分支）

or a user-specified directory/file.

2. Launch check Agents in parallel

Use the Task tool to launch multiple specialized checks in parallel, see review-workflow.md。

Other Agent environments: The following checks are independent of each other and can be executed sequentially in order.

Agent 1: Quality Scale 规则检查
Agent 2: 代码风格检查
Agent 3: Config Flow 检查
Agent 4: 测试覆盖检查
Agent 5: 文档与 Manifest 检查

Quality Scale verification - Read quality_scale.yaml and verify done rules
Code style check - Compare against copilot-instructions.md
Config Flow check - Verify unique_id and test coverage
Test coverage check - Confirm >= 95%
Documentation check - Verify strings.json and README

After all checks are complete, aggregate the results into a unified report.

3. Dynamically fetch the latest specifications

Do not use outdated static documentation, fetch dynamically on each review:

Quality Scale rules

WebFetch: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/core/integration-quality-scale/rules/{rule_name}.md

Other environments:curl -sL <URL> as a substitute.

Coding standards

WebFetch: https://raw.githubusercontent.com/home-assistant/core/dev/.github/copilot-instructions.md

Other environments:curl -sL <URL> as a substitute.

Developer documentation

Use Context7 to fetch the latest Home Assistant developer documentation.

If Context7 MCP is not installed, fetch directly from the GitHub repository: curl -sL https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/...

4. Reference other integrations

Look at the implementation of similar integrations in ha-core:

gh api repos/home-assistant/core/contents/homeassistant/components/{integration_name}

5. Aggregate the review report

Output a structured report, including:

The results of each check dimension
Specific issues and their file locations
Fix suggestions and priorities

Checklist quick reference

See common-issues.md, including:

Common code style issues
Logging standards
Exception handling
Entities and devices
Config Flow
Service registration
Documentation standards

Quality Scale verification key points

Use the quality-scale-rule-verifier Agent

The ha-core repository provides a dedicated Quality Scale verification agent:

Location: repos/ha-core/.claude/agents/quality-scale-rule-verifier.md

How to invoke:

# 验证单个规则
"Check if the {integration} integration follows the {rule_name} rule"

# 验证整个等级
"Verify that this integration reaches the {tier} quality scale"

This agent dynamically fetches the rule documentation and verifies the implementation, which is more accurate than static checks.

Done rules

Verify whether the code truly meets the rule requirements, rather than merely being marked as done.

Todo rules

Check whether it is close to completion, and prompt the user to consider completing it to raise the Quality Scale level.

Exempt rules

Evaluate whether the exemption reason is reasonable and whether it truly does not apply to the integration.

Key review criteria

Asynchronous programming

All external I/O must be async
Blocking in the event loop is prohibited
Use gather instead of await in loops

Exception handling

Narrow the scope of the try block
Use ServiceValidationError to handle input errors
Use HomeAssistantError to handle communication failures

Config Flow

unique_id set correctly
100% test coverage
UI text standards (avoid "Click", bold button labels)

Testing

Located in tests/components/{domain}/
Use fixtures and snapshot testing
Coverage >= 95%