ha-integration-scaffold

HA Integration Scaffold

Spec: spec/claude/ha-integration-scaffold/en.md (EN canonical) / spec/claude/ha-integration-scaffold/de.md (DE translation).

Why this is a skill, not an agent

• One step in a larger human-driven workflow (decisive): the greenfield scaffold is the opening move of integration development; domain, platforms, discovery, and harness choices are elicited and approved mid-flow.
• Context access: the scaffold lands in the repository the conversation is scoped to and its decisions feed directly into the follow-on ha-* skills.
• Counter-dimension considered: a complete skeleton is a large self-contained unit (agent bias), but every structural decision inside it is operator-facing; a fire-and-forget agent would guess where the spec demands a confirmed answer.

When this skill activates

Use this skill when the user wants to:

• bootstrap a brand-new HA Custom Integration in an empty consumer repo
• get a runnable, lint-clean, test-passing skeleton without having to read every spec/ha/* spec first
• start an integration that targets HACS distribution

When NOT to activate

• editing an existing custom_components/<domain>/ → route to the owning augment skill (ha-config-flow-augment, ha-coordinator-add, ha-entity-platform-add, …) or let ha-integration-solution plan the combination
• scaffolding a Lovelace card → separate skill ha-lovelace-card-scaffold
• scaffolding an ESPHome device config (YAML) → ha-esphome-config-scaffold; an ESPHome custom component (C++/Python) stays out of scope
• scaffolding a blueprint / automation → separate skill ha-blueprint-scaffold
• migrating a YAML-configured integration to config flow → separate skill (planned, only on demand)

Hard rules

1. Never overwrite an existing custom_components/<domain>/. If the directory exists, abort with the path quoted. Collision is a user-disambiguation problem, not a generator problem.
2. Never use hass.data[DOMAIN]. Every setup artefact lives in typed entry.runtime_data (see spec/ha/runtime-data-pattern/en.md). The generated __init__.py is the single source of this contract.
3. Never set _attr_name = "<string>" on a generated entity. All entity names live in strings.json under entity.<platform>.<translation_key>.name (see spec/ha/translations/en.md). Hard-coded names break translation and stable entity_id slugs.
4. Never set self.entity_id = "...". HA derives the entity_id from the system-language display name at first registration. The skeleton stays English-source so the slug remains language-independent (see spec/ha/entity-architecture/en.md).
5. Never bypass the API path whitelist. Generated api.py carries _API_PATH_RE and a _with_auth(headers) helper; bearer tokens go on the wire only after the path has passed the whitelist (see spec/ha/security-hardening/en.md).
6. Never silently default. When the user did not specify hacs / zeroconf / auth / platforms, fall back to documented defaults — but state every default in the output summary so the user sees what was assumed.
7. Name every artefact per ha/naming-conventions. The integration domain, unique_id, translation_key, device identifiers, service names, config-entry title, and all generated file paths follow the consolidated naming authority — snake_case identifiers, English display names (≤ 50 chars), no volatile data (IP, hostname, token, timestamp) in any ID (see spec/ha/naming-conventions/en.md). Rules 3–4 are the entity-name instances of this authority.
8. Verify HA internals against the official docs. Don't reproduce HA API signatures, lifecycle hooks, conventions, or schemas from memory — when uncertain, consult the official docs before generating or relying on it: Developer docs developers.home-assistant, architecture/blueprint/YAML docs home-assistant.io (see spec/ha/upstream-docs-verification/en.md).
9. Emit PARALLEL_UPDATES in every platform module. Each generated entity-platform module carries a module-level PARALLEL_UPDATES constant — 0 for coordinator-backed read-only platforms — so the integration satisfies the Silver quality-scale rule parallel-updates that ha-quality-scale-audit checks. Verify the exact numeric convention against the HA parallel-updates rule page.