ha-esphome-binding-add

HA ESPHome Binding Add

Spec: spec/claude/ha-esphome-binding-add/en.md (EN canonical) / spec/claude/ha-esphome-binding-add/de.md (DE translation). Grounding spec: spec/ha/esphome-ha-driven-content/en.md; rendering of the resulting values is owned by spec/ha/esp32-s3-box-display/en.md.

Adds exactly one Home-Assistant-driven binding per invocation, and the mechanism choice is the substance of the run — not the YAML that follows from it.

Why this is a skill, not an agent

• Mid-flow approval is the contract (decisive): the mechanism decision (subscription vs. action vs. writable entity vs. return channel) is made with the operator against the spec's rule; picking wrong produces a device that polls what it should have been told, or an automation firing into a device with no receiver — and neither fails loudly.
• Quick, targeted change in the current context: one block in one device file or package, iterated in conversation.
• Counter-dimension considered: the six documentation pages this spans make the schema lookup self-contained (agent bias), but the boot-state and offline-behaviour decisions belong in the operator's context, not in a report; skill wins.

When this skill activates

The user wants Home Assistant to drive what an ESPHome device shows or does — "der ESPHome-Node soll den Strompreis anzeigen", "HA should be able to tell the box to show a message", "the button press should reach Home Assistant".

When NOT to activate

• how the value is drawn (pages, zones, fonts, redraw script) → ha-esphome-display-author
• the voice pipeline and satellite binding → ha-esphome-voice-satellite-add
• a locally measured sensor or a local component → ha-esphome-config-augment
• the automation, script, or template on the Home Assistant side → ha-automation-solution
• MQTT as an alternative transport → out of scope; the grounding spec assumes the native API

Hard rules

1. Read spec/ha/esphome-ha-driven-content/en.md first, then the target device file and its packages. Do not generate a mechanism from memory.
2. Choose per value, not per device, using the spec's rule: continuously mirrored → subscription; one-shot instruction with arguments → callable action; person-set → writable entity; Home Assistant must learn something → return channel. State the choice and its reason in the report.
3. Never emulate one mechanism with another. A periodically called action is not a subscription, and a rapidly changing subscribed value is not an action — both work briefly and fail under load or disconnection.
4. Verify every key against the official ESPHome docs per spec/ha/upstream-docs-verification — this axis spans at least six component pages (api, sensor/homeassistant, text_sensor/homeassistant, time/homeassistant, text/template, and the display components).
5. Subscriptions are push-based and internal: true by default on every import platform. Set internal explicitly for readability, give every subscribed value an id:, and use attribute: only on the read-only import platforms — number and switch have no such key.
6. Actions carry typed variables: and validate them, answering a bad call through api.respond with success: false. Name the Home-Assistant-side identifier as esphome.{node_name}_{action_name} in the report, and state that a device rename breaks every automation calling it.
7. A writable text: {platform: template} respects its documented exclusions: optimistic, initial_value, and restore_value each cannot be used with lambda. Do not carry these rules over to an unread template platform.
8. A device calling Home Assistant actions needs the integration's explicit opt-in. Name it as a trust decision the operator has to make, never as a formality.
9. Define the two edge states, always. What the device shows or does before the first value has ever arrived, and what it does when the API connection drops (on_client_connected / on_client_disconnected) — including the consequence of api.reboot_timeout (default 15 minutes).
10. Route anything visible through the single redraw entry point of the display spec; an on_value that draws directly is a finding, not a shortcut.
11. One binding per run, one device file per run. No deploy; the run ends at the edited file plus the validation report.