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
- trailofbits/cooptheir own version, first seen Nov 5, 2026
- foryouself83/harness-tiertheir own version, first seen Oct 13, 2026
- alizafarbati/opencode-agents-mcptheir own version, first seen Sep 8, 2026
- christianoblake/fan-development-skillstheir own version, first seen Aug 31, 2026
- robium-ai/robiumtheir own version, first seen Aug 7, 2026
- StephanSergio/vibe-stacktheir own version, first seen Jun 20, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- trailofbits/coop★ 816same name
- robium-ai/robium★ 93same name
- foryouself83/harness-tier★ 10same name
- christianoblake/fan-development-skills★ 2same name
- aiperceivable/apcore-skills★ 1same name
- alizafarbati/opencode-agents-mcp★ 1same name
- StephanSergio/vibe-stack★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-setupSkill
- config-flowSkill
- coverageSkill
- documentationSkill
- elementsSkill
- explain-planSkill
- lintSkill
- manifestSkill
- modelSkill
- performanceSkill
- pythonSkill
- release-notesSkill
- scenariosSkill
- testingSkill
- translationsSkill
- update-docsSkill
- update-versionSkill
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
- Very specific: line 29
Every entity and device ID is built and parsed through custom_components/haeo/unique_id.py, never formatted or split by hand:
- Distinctive: line 40
Never use: IP addresses, hostnames, user-provided names.
- Very specific: line 44
Add entities with async_add_entities(entities, config_subentry_id=subentry.subentry_id), one call per subentry.
- Distinctive: line 50
Use translation keys for all entity names:
- Very specific: line 60
Use None for unknown values (not "unknown" string)
- Very specific: line 73
Create devices through the helpers in entities/device.py, which register each device with the adapter's device name as its translation key …
- Distinctive: line 77
All exceptions that may reach the user must use Home Assistant exception types with translations.
- Distinctive: line 78
Never raise generic exceptions that would show "unknown error" in the UI.
- Distinctive: line 99
Add any key that holds a password, token, or sensitive coordinate there.
- Very specific: line 106
Remove the pricing rules of elements deleted since the config last changed, create the required subentries, then check that every element …
- Distinctive: line 107
Create the horizon manager and the input stores, and start the loaders that keep the stores loaded.
“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.
Files
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 thehaeo.optimizeaction, checks this under the lock and raisesHomeAssistantErrorwithinputs_not_aligned. - Turning auto-optimize off cancels an optimization waiting out the debounce window.
- Raise
UpdateFailedfor data loading or optimization errors, orReportedUpdateFailedwhen 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
Nonefor unknown values (not "unknown" string) - Implement
availableproperty 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 itUpdateFailed: Data loading or optimization errorsHomeAssistantError: 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:
- 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
ConfigEntryNotReadywith amissing_element_referencesrepair issue otherwise. - Create the horizon manager and the input stores, and start the loaders that keep the stores loaded.
- Forward the input platforms, which only display the stores, and wait for every input store to settle, raising
ConfigEntryNotReadywhile inputs are unavailable. - Initialize the coordinator and run the first optimization with
async_refresh(), so a failed optimization does not retry setup. - 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.
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
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.

