gregoryg/aipihkal/home-assistant-config-dev

Home Assistant configuration development

Treat Home Assistant configuration work as a reversible live-system change, not as ordinary text editing. Prefer supported APIs, exact evidence, boring rollback, and production-path tests.

This skill complements hass-cli. Use that skill for entity discovery, state, areas, safe household control, and deterministic local intents. Do not enlarge this skill into a general home-control interface.

Establish the boundary

Before mutation:

1. Read the target repository's agent, planning, task, and snapshot documents.
2. Require a clean worktree and inspect the curated pull preview when the repo

uses one.

1. Classify the object as YAML-backed, storage-backed, runtime-only, or external.

Read persistence-boundaries.md.

1. Name the inverse operation and external cleanup before changing anything.
2. Identify the exact objects and files expected to change.
3. For Assist-facing work, enumerate required and forbidden exposed entities and

capture their live entity-registry conversation options.

1. Stop if the supported interface cannot capture and restore the original.

Never edit .storage generically. Never paste tokens into chat or commands. Never treat Git as disaster recovery when the repository is only a projection.

Use current diagnostic tools

Paths below are relative to this skill directory. The wrappers use exported HASS_SERVER and HASS_TOKEN; when absent, they reuse the sibling hass-cli environment loader without copying credentials.

All output is bounded JSON. Exit codes are 0 for success, 2 for invalid or rejected work, and 3 for authentication, transport, dependency, timeout, or protocol failures.

ha-assist-run requires --execute because text processing may perform real Home Assistant actions. Inspect pipeline, engine, processed_locally, response_type, and events; do not infer production routing from a direct conversation-agent call.

ha-calendar-events is deliberately limited to the read-like calendar.get_events action. Use exact ISO start/end values and an exact calendar.* entity. Descriptions are omitted unless explicitly requested.

Trace output excludes raw config and detailed step payloads by default. Use it to establish run identity, completion, last step, errors, and executed path—not to dump unbounded integration data into context.

For log evidence, prefer the host's ha core logs, which keeps timestamps for days. system_log/list groups entries by logger and source with a count since the last restart, so one entry can mix unrelated failures. When several cloud integrations log DNS timeouts or "Network unreachable" at the same instant, inspect the host's DNS with ha dns info and ha dns logs before blaming a provider.

Repeat the opt-in metadata-only live checks with:

HA_DEV_LIVE_SMOKE=1 \
HA_DEV_SMOKE_CALENDAR=calendar.example \
HA_DEV_SMOKE_TRACE_DOMAIN=automation \
HA_DEV_SMOKE_TRACE_ITEM_ID=example \
tests/live_smoke.sh

Add HA_DEV_SMOKE_ASSIST=1 only when a production-pipeline query is authorized. The default phrase is “What time is it?”; override it with HA_DEV_SMOKE_ASSIST_PHRASE only after reviewing its possible actions.

Audit Assist exposure

Treat entity exposure as an explicit storage-backed dependency. A valid entity, script, automation, or prompt does not imply that the selected LLM can see or invoke it. Creation, rename, replacement, integration migration, and deletion can all change the effective allowlist outside the curated YAML snapshot.

For every Assist-facing change:

1. List the exact required entities and action tools.
2. Inspect each live entity-registry conversation.should_expose value.
3. Inspect exposed scripts' current fields and action-response contracts; a tool

schema that exists but returns an invalid shape is still broken.

1. Search for stale, duplicate, unavailable, renamed, or superseded exposed

entities that could conflict with the authoritative source.

1. Keep implementation-only entities unexposed when a narrower script provides

the intended contract.

1. Test a safe phrase through the selected production pipeline, including one

wording that bypasses deterministic local sentence triggers; correlate the result with the invoked script or automation trace.

1. Record storage-backed exposure semantics in repository documentation because

a pull-only snapshot cannot preserve or review them directly.

Audit positive and negative space. Confirming the required tool is exposed does not establish that a stale contradictory helper is absent, and confirming stale entities are absent does not establish that the required tool is available.

Since HA 2026.11 a displayed name is composed: device name, then entity name. config/entity_registry/list returns neither aliases nor the composed name; read aliases with config/entity_registry/get_entries. When an exposed entity's full name changes, HA keeps the old name as its first alias. Rename a device through config/device_registry/update, which never renames entity IDs. The UI's rename dialog offers to rename them too; decline, because YAML refers to entity IDs.

Replace an integration for a device

A replacement integration rarely passes the old one's data through unchanged. When one device moves to another integration:

1. Read the new integration's source for each entity's states. Values such as

finished and finish, or run and active, differ, and one entity may collapse states, such as reading idle while paused.

1. Find every reference to the old entity IDs. A repository search misses

storage dashboards, Energy preferences, and exposure, so also list the matching file names in the host's .storage without printing contents.

1. Remove the old integration before renaming the new entities onto any old

IDs. Reuse an old ID only where the meaning is unchanged, such as an energy meter; see persistence-boundaries.md.

1. A rename produces a state with no previous one. A state trigger's

not_from does not filter it, so a template that reads trigger.from_state must check it.

1. New entities are not exposed to Assist when expose_new is false, and they

may include controls such as start and stop buttons. Expose only the intended entity and confirm that the controls stay hidden.

Write custom LLM tools to the current contract

A tool returned through llm.LLMTools sets integration to its domain, uses a DOMAIN__ name prefix, and returns llm.ToolResult. HA 2026.11 logs a warning for an untagged tool or a plain JSON result; they stop working in 2027.10 and 2027.11.0. A clarification question is a normal result, not error=True; raise HomeAssistantError for failures. The warning for a missing integration appears whenever a conversation collects tools; the JSON-result warning appears only when the tool is called.

Follow the live-first workflow

For authorized YAML-backed automation or script changes:

1. Baseline: verify expected live/repository drift and record current states.
2. Capture: save exact API objects and complete relevant files under a

durable rollback ID with private permissions.

1. Deactivate: turn off affected behavior when practical.
2. Install: use the supported config-object API; install scripts before

automations that depend on them.

1. Check: keep affected behavior off and run target-side ha core check.
2. Compare: fetch installed objects and compare normalized JSON exactly.
3. Activate: reload only required domains, then explicitly enable behavior.
4. Test actions: exercise action sequences independently where possible.
5. Audit exposure: verify the required and forbidden Assist allowlist when

the feature participates in conversation.

1. Test triggers: use the actual production path and inspect traces.
2. Verify effects: inspect external state and clean conspicuous test data.
3. Pull back: preview the curated rsync, require only expected paths, apply,

parse/lint, and review the full diff.

1. Document: update durable decisions, validation evidence, pending tests,

limitations, and rollback identity.

Read validation-matrix.md before claiming a change is validated. Syntax, action, trigger, collision, cancellation, and recovery are different evidence layers.

Preserve rollback discipline

The config APIs can write live files or reload an individual object before a whole-system check. Deactivation and capture reduce that risk; they do not make the change atomic.

A config-transaction wrapper is intentionally not implemented yet. Until its rollback paths have fault-injection tests, manual mutation remains exceptional: show the exact object set, rollback location, and activation boundary before proceeding. Never reconstruct rollback commands from memory after failure.

Use artifact-schema.md when capturing mutation evidence. Keep installation, check, activation, restart, and acceptance as separate states. Restart always requires explicit authorization.

Respect Git ownership

Pulling accepted live configuration into a working tree does not grant permission to stage, commit, amend, or push. Inspect and validate the diff, then leave history to the human unless separately authorized.

Current limitations

• Configuration transaction and rollback wrappers remain future work.
• Storage-backed object support is not generic and must be designed per API.
• Live Assist tests can incur LLM cost or real side effects.
• Calendar and integration polling can make successful API writes temporally

invisible to triggers; test platform timing rather than assuming immediacy.

• An HA outage can preserve an external record while still missing an HA action.