ha-integration-events-add

HA Integration Events Add

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

Why this is a skill, not an agent

• Human-visible augmentation surface — the user describes an occurrence and reads back the async_fire call, the documented data shape, the listener wiring, and the conformance report; a skill keeps this on the visible command surface, like the sibling augment skills (ha-config-flow-augment, ha-coordinator-add, ha-device-automation-add).
• Mid-flow interactivity — the fire-vs-listen-vs-both decision and the event-vs-state check are per-run dialogues the user approves before generation.
• Bounded, inline generation — a bus-fire call plus a documented data shape, or a listener with its async_on_unload teardown, fit inline; no isolated agent context is needed.
• Counter-dimension considered: the draft→validate loop could be an agent, but the direction decision and the event-vs-state advice belong in the user's working context; skill wins.

When this skill activates

Use this skill to add event firing and/or listening to an existing integration — firing a domain-prefixed custom event when a transient occurrence happens, or subscribing to a bus event with clean unsubscribe teardown.

When NOT to activate

• a user-driven action with its own schema → ha-service-definition-add / ha/services
• a device trigger built on top of a fired event → ha-device-automation-add / ha/device-automations
• greenfield integration scaffolding → ha-integration-scaffold
• deploying/importing into a running HA instance → out of scope

Hard rules

1. Decide the direction first. Resolve fire vs. listen vs. both with the user before generating anything.
2. Read spec/ha/integration-events/en.md first. Do not generate from memory.
3. Domain-prefixed firing. Fire via hass.bus.async_fire("<domain>_event", event_data); the event type must carry the domain prefix; event_data is a JSON-serializable dict. Never use unprefixed or generic event names.
4. Firing lives in setup. Place firing code in async_setup_entry (__init__.py), never in a platform's entity logic. For device-/service-related events add a device_id attribute from the device registry, and document the event_data shape (keys + types).
5. Listen via the bus or a helper. Use hass.bus.async_listen (until canceled) or hass.bus.async_listen_once (exactly once); prefer async_listen_once for one-shot lifecycle events (EVENT_HOMEASSISTANT_START / _STARTED / _STOP). Prefer an homeassistant.helpers.event helper when it covers the type; do not listen to core events like EVENT_STATE_CHANGED when a dedicated helper exists.
6. Never drop the unsubscribe. Hold the callable returned by async_listen / async_listen_once (or the helper) and register it via entry.async_on_unload(unsub) — or tear it down in async_unload_entry (see spec/ha/setup-lifecycle/en.md). A discarded callable leaks beyond the reload and fires twice.
7. @callback listeners. Decorate non-blocking, loop-running listeners with @callback (homeassistant.core.callback); avoid blocking or I/O work inside them and offload follow-up work as a task (see spec/ha/async-patterns/en.md).
8. Event, not state. Fire transient occurrences as events; never let entity state represent a transient event (no "30-second-on" binary sensor). Point at an event entity (spec/ha/entity-architecture/en.md) when it models the occurrence more cleanly.
9. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).