ha-entity-platform-add

HA Entity Platform Add

Spec: spec/claude/ha-entity-platform-add/en.md (EN canonical) / spec/claude/ha-entity-platform-add/de.md (DE translation).

Why this is a skill, not an agent

• Human-visible scaffolding surface — the operator describes a device capability and reads back the platform module, the feature bitmask, the command methods, and the conformance report; a skill keeps this on the visible command surface, like the sibling augment skills (ha-coordinator-add, ha-entity-description-map, ha-device-automation-add).
• Mid-flow interactivity — the platform/domain decision and the family confirmation are per-run dialogues the operator approves before generation.
• Bounded, inline generation — one platform module plus its description and setup fit inline; no isolated agent context is needed.
• Counter-dimension considered: the draft→validate loop could be an agent, but the domain decision and the active-vs-declarative gate belong in the operator's working context; skill wins.

When this skill activates

Use this skill to scaffold one active platform entity — a command-driven domain (climate, cover, light, fan, lock, media_player, vacuum, valve, humidifier, water_heater, siren, lawn_mower, …) whose entity exposes async command methods — into an existing integration.

When NOT to activate

• datapoints authored declaratively as EntityDescription tables — read-type sensor/binary_sensor/button, and the description-table form of number/select/switch/calendar/todo with no hand-written command/set method → ha-entity-description-map
• the coordinator itself → ha-coordinator-add
• greenfield integration scaffolding → ha-integration-scaffold
• device-automation triggers/conditions/actions → ha-device-automation-add
• deploying/importing into a running HA instance → out of scope

Hard rules

1. One platform entity, one run. No multi-platform batches.
2. Read the operationalized spec first. Read spec/ha/entity-platform-types/en.md to pick active-vs-declarative and the family, then read the matching family spec (spec/ha/entity-platforms-controls/en.md / spec/ha/entity-platforms-climate/en.md / spec/ha/entity-platforms-devices/en.md / spec/ha/entity-platforms-media/en.md / spec/ha/entity-platforms-voice/en.md / spec/ha/entity-platforms-inputs/en.md / spec/ha/entity-platforms-sensors/en.md) in full. Do not generate from memory.
3. Active platforms only. This skill scaffolds command-driven entities authored as a full entity class with hand-written async command/set methods. The boundary is the authoring form, not the domain: a read-type datapoint (sensor/binary_sensor/button) or any entity expressed purely as an EntityDescription table without a hand-written command/set method → point at ha-entity-description-map and abort. Active platforms whose command/set method this skill writes — including the inputs family (number/select/text/date/time/datetime) and calendar/todo — stay in scope.
4. Name the domain, confirm the family. Require the operator to name the target domain and confirm the resolved family before generating.
5. Base class from the family spec. Derive the entity from the documented platform base class (ClimateEntity/CoverEntity/LightEntity/FanEntity/LockEntity/MediaPlayerEntity/StateVacuumEntity/ValveEntity/HumidifierEntity/WaterHeaterEntity/SirenEntity/LawnMowerEntity …).
6. Feature bitmask from the enum. Set supported_features as a bitwise | combination of the platform-native *EntityFeature enum — never a raw integer.
7. Flag ↔ method, one-to-one. Implement the documented async command method for every set flag (e.g. CoverEntityFeature.OPEN ↔ async_open_cover, ClimateEntityFeature.TARGET_TEMPERATURE ↔ async_set_temperature, LockEntityFeature.OPEN ↔ async_open, FanEntityFeature.SET_SPEED ↔ async_set_percentage). Never set a flag "on spec" whose method is missing.
8. Required properties, built-in enums. Provide every property the domain marks as Required (hvac_mode/hvac_modes, is_closed, color_mode/supported_color_modes, activity, alarm_state, …) and use only the built-in state/mode enums (only built-in HVACMode; VacuumActivity/LawnMowerActivity). Set device_class from the closed platform-native enum where a member exists, never a free string.
9. Wire the setup. Implement async_setup_entry(hass, entry, async_add_entities) that builds the entities and registers them via async_add_entities, attaching to the coordinator / config_entry.runtime_data; if no coordinator exists, point at ha-coordinator-add.
10. Availability (entity-unavailable, Silver). The generated entity handles availability — subclass CoordinatorEntity (which derives available from coordinator.last_update_success) or override the available property to return False when the datapoint can't be read or controlled. An active entity that never reports unavailable silently misses the Silver entity-unavailable rule that ha-quality-scale-audit checks.
11. Emit PARALLEL_UPDATES (parallel-updates, Silver). Declare a module-level PARALLEL_UPDATES constant in <platform>.py (a coordinator-backed read path typically uses 0; command platforms bound their concurrency). Verify the value against the HA parallel-updates rule page rather than reproducing it from memory.
12. Name per spec/ha/naming-conventions/en.md, do not duplicate the generic entity pattern (delegate to spec/ha/entity-architecture/en.md), and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).