hacs.integration_blueprint: Instructions file for Codex

AI Agent Instructions

Always-loaded project context for every AI coding agent working on this Home Assistant custom integration. Per-file style rules and task procedures live elsewhere — the routing table below says where.

Only what an agent cannot infer from the code belongs in this file. General Python, async or Home Assistant knowledge does not; this project's identity, layering, workflow policy and traps do.

Which repository is this?

initialize.sh is present, so this repository has not been initialised yet — the domain, class prefix and directory names below are still the template's placeholders. The script replaces them across the whole repository and then deletes itself, and template sync never restores it. Its absence, not any wording here, is what marks an initialised integration.

Two kinds of repository are in this state, and they are byte-identical — nothing in the working tree tells them apart:

• The upstream template. The placeholders are permanent here, and the example integration is itself the thing being maintained. Every change ships to every downstream repository through the weekly template-sync pull request, so skills and instruction files must use the <domain> and {ClassPrefix} placeholders rather than the concrete identifiers, and blueprint-skill-maintenance governs the shipped skill set.
• A fresh copy made with GitHub's "Use this template" button, which still has to be initialised. Do not write integration code first — initialize.sh would overwrite it. Run ./initialize.sh, then blueprint-scaffold; when existing integration code is being migrated in, blueprint-import covers the order instead.

When the request does not make clear which of the two this is, ask. Do not infer it from the git remote — a contributor's fork of the template is not a copy awaiting initialisation.