agentleFS
hass-energyhass-energy/haeo/.agents/skills/integration/SKILL.md

integration

Skill77 starsChanged 20 days agoMITView on GitHub

Home Assistant integration patterns — the event-driven optimization coordinator in coordinator/, HaeoRuntimeData and setup and unload in __init__.py, input stores and the inputs/ package of Home Assistant readers, entity unique IDs and naming, device registry, exception types, and diagnostics redaction. Use when working anywhere under custom_components/haeo/ outside the standalone core package.

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 6 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every entity and device ID is built and parsed through custom_components/haeo/unique_id.py, never formatted or split by hand:

    line 29
  2. Distinctive:

    Never use: IP addresses, hostnames, user-provided names.

    line 40
  3. Very specific:

    Add entities with async_add_entities(entities, config_subentry_id=subentry.subentry_id), one call per subentry.

    line 44
  4. Distinctive:

    Use translation keys for all entity names:

    line 50
  5. Very specific:

    Use None for unknown values (not "unknown" string)

    line 60
  6. Very specific:

    Create devices through the helpers in entities/device.py, which register each device with the adapter's device name as its translation key …

    line 73
  7. Distinctive:

    All exceptions that may reach the user must use Home Assistant exception types with translations.

    line 77
  8. Distinctive:

    Never raise generic exceptions that would show "unknown error" in the UI.

    line 78
  9. Distinctive:

    Add any key that holds a password, token, or sensitive coordinate there.

    line 99
  10. Very specific:

    Remove the pricing rules of elements deleted since the config last changed, create the required subentries, then check that every element …

    line 106
  11. Distinctive:

    Create the horizon manager and the input stores, and start the loaders that keep the stores loaded.

    line 107

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Home Assistant integration development

Package boundary

core/ never imports Home Assistant; import-linter enforces it. Code that reads Home Assistant at run time lives outside it: the inputs/ package holds the state machine adapter, calendar event loading, and meter history readers that feed the core loaders.

Coordinator pattern

HaeoDataUpdateCoordinator in coordinator/coordinator.py assembles each element's config from the input stores, runs the optimization, and exposes the results.

  • It has no update_interval. Updates are event-driven: input store changes and horizon changes signal the results stale, and the coordinator optimizes after the hub's debounce window.
  • Refreshes are single-flight: one lock and one "rerun wanted" flag, so requests made while an optimization runs share one follow-up run. async_request_refresh() goes through the debounce window like any automatic request.
  • An optimization is skipped while forecast inputs are still loading for a new horizon; async_run_optimization(), behind the haeo.optimize action, checks this under the lock and raises HomeAssistantError with inputs_not_aligned.
  • Turning auto-optimize off cancels an optimization waiting out the debounce window.
  • Raise UpdateFailed for data loading or optimization errors, or ReportedUpdateFailed when the failure raises a repair issue of its own.

Entity development

Unique IDs

Every entity and device ID is built and parsed through custom_components/haeo/unique_id.py, never formatted or split by hand:

self._attr_unique_id = element_unique_id(config_entry.entry_id, subentry.subentry_id, unique_key)

Element IDs are {entry_id}_{subentry_id}_{key} and hub IDs are {entry_id}_{key}. parse_element_unique_id reads an element ID back, so generation, device cleanup, and migrations all agree on the format. Migrations of formats that have shipped keep their own historic parsing.

Acceptable sources: config entry ID, subentry ID, device serial numbers. Never use: IP addresses, hostnames, user-provided names.

Subentry links

Add entities with async_add_entities(entities, config_subentry_id=subentry.subentry_id), one call per subentry. Element entities link to their element's subentry and hub entities to the network subentry, matching their devices. Home Assistant then removes the entities when the subentry is deleted.

Entity naming

Use translation keys for all entity names:

class MySensor(SensorEntity):
    _attr_has_entity_name = True
    _attr_translation_key = "battery_power_charge"

State handling

  • Use None for unknown values (not "unknown" string)
  • Implement available property for availability

Event lifecycle

async def async_added_to_hass(self) -> None:
    """Subscribe to events."""
    self.async_on_remove(self.coordinator.async_add_listener(self._handle_update))

Device registry

Create devices through the helpers in entities/device.py, which register each device with the adapter's device name as its translation key and the element name as the name placeholder.

Exception handling

All exceptions that may reach the user must use Home Assistant exception types with translations. Never raise generic exceptions that would show "unknown error" in the UI.

Setup never fails permanently, so that HAEO recovers on its own once the conditions it depends on settle. async_setup_entry turns any unexpected error into ConfigEntryNotReady with a setup_failed repair issue; never raise ConfigEntryError.

  • ConfigEntryNotReady: Setup cannot finish yet; Home Assistant retries it
  • UpdateFailed: Data loading or optimization errors
  • HomeAssistantError: User-facing errors with translation support

For service calls and user actions, use HomeAssistantError with a translation key:

raise HomeAssistantError(
    translation_domain=DOMAIN,
    translation_key="inputs_not_aligned",
)

Diagnostics

Diagnostics are collected in diagnostics/collector.py, which passes config through async_redact_data with _REDACTED_CONFIG_KEYS. Add any key that holds a password, token, or sensitive coordinate there.

Setup and unload

async_setup_entry() in __init__.py stores a HaeoRuntimeData on entry.runtime_data, holding the horizon manager, the input stores in input_stores, the auto-optimize switch, and the coordinator. Setup runs in this order:

  1. Remove the pricing rules of elements deleted since the config last changed, create the required subentries, then check that every element names only elements that exist, raising ConfigEntryNotReady with a missing_element_references repair issue otherwise.
  2. Create the horizon manager and the input stores, and start the loaders that keep the stores loaded.
  3. Forward the input platforms, which only display the stores, and wait for every input store to settle, raising ConfigEntryNotReady while inputs are unavailable.
  4. Initialize the coordinator and run the first optimization with async_refresh(), so a failed optimization does not retry setup.
  5. Forward the output platforms.

Register every cleanup with entry.async_on_unload() during setup. async_unload_entry() then only unloads the platforms, clears entry.runtime_data if they unloaded, and returns that result.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.