ha-discovery-augment

HA Discovery Augment

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

Why this is a skill, not an agent

• Human-visible augmentation surface — the user describes how the device announces itself and reads back the manifest matcher, the config-flow step, 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-repairs-add).
• Mid-flow interactivity — the mechanism choice, the matcher narrowing, and the Zeroconf/Bluetooth redirect are per-run dialogues the user approves before generation.
• Bounded, inline generation — one mechanism's manifest matcher plus its discovery step fit inline; no isolated agent context is needed.
• Counter-dimension considered: the draft→validate loop could be an agent, but the mechanism decision and the report belong in the user's working context; skill wins.

When this skill activates

Use this skill to add one discovery mechanism — DHCP, SSDP/uPnP, USB, HomeKit, or MQTT — to an existing integration so the user doesn't have to type a host or pick the integration manually.

When NOT to activate

• mDNS/Zeroconf discovery → ha/zeroconf-discovery (the scaffold already produces it)
• Bluetooth discovery → separate sibling spec ha/bluetooth
• greenfield integration scaffolding → ha-integration-scaffold
• generic config-flow auth/selection steps → ha-config-flow-augment / ha/config-flow-patterns
• deploying/importing into a running HA instance → out of scope

Hard rules

1. One mechanism, one run. No multi-mechanism batches.
2. Read spec/ha/discovery-mechanisms/en.md first. Do not generate from memory.
3. Right mechanism, with delimitation. mDNS/Zeroconf → ha/zeroconf-discovery/scaffold; Bluetooth → ha/bluetooth. Redirect rather than augmenting the wrong one.
4. Manifest matcher is a list of matcher dicts under the correct key (dhcp/ssdp/usb/homekit/mqtt); discovery fires when all items of any one matcher are present. Narrow generic OUI/bridge-chip matchers (e.g. add a description match for vid: 10C4/pid: EA60).
5. Typed discovery step. Implement async_step_dhcp(self, discovery_info: DhcpServiceInfo) / async_step_ssdp(... SsdpServiceInfo) / async_step_usb(... UsbServiceInfo) / async_step_homekit(... ZeroconfServiceInfo) / async_step_mqtt(... MqttServiceInfo) in config_flow.py.
6. Always confirm. Forward into a confirm step (async_step_discovery_confirm + self._set_confirm_only()) before async_create_entry — never an entry without user confirmation.
7. Own the update path. Set await self.async_set_unique_id(<stable_id>) then self._abort_if_unique_id_configured(updates={CONF_HOST: host}); never a second entry on re-discovery. Canonical unique_id source per mechanism: DHCP → MAC (format_mac), SSDP → udn, USB → serial_number (else vid:pid), HomeKit → the accessory id, MQTT → a stable id from the discovery topic/payload. For DHCP IP-updates register the MAC (CONNECTION_NETWORK_MAC) and set registered_devices: true; for MQTT add mqtt to dependencies and await mqtt.async_wait_for_mqtt_client(hass) before subscribing. Add the config.abort.already_configured / already_in_progress strings to strings.json.
8. Name per spec/ha/naming-conventions/en.md and verify HA internals against the official docs (see spec/ha/upstream-docs-verification/en.md).