gtapps/ha-build-automation

Build HA Automation

Steps

1. Gather context:

   • Read .claude-code-hermit/raw/snapshot-ha-normalized-latest.json for available entities and services.
   • Use the stored language from OPERATOR.md (## HA hermit section) for alias and description fields.
   • Optionally call GetLiveContext via MCP for current state.

2. Draft the YAML:

   • Always include id: as the first field, using a stable, language-neutral snake_case value (e.g., kitchen_motion_after_sunset_notification). The validate-apply command uses this as the REST config ID — omitting it causes a derived, fragile ID that breaks on alias rename.
   • Use the stored locale for alias and description.
   • Set mode explicitly where concurrency matters.
   • Write to .claude-code-hermit/raw/automation-<automation_id>.yaml.

3. Provision missing helpers:

   • Scan the drafted YAML for helper entity IDs (input_boolean.*, input_number.*, input_text.*, input_select.*, input_datetime.*, timer.*, counter.*, schedule.*) that are absent from the entity inventory snapshot. If none are absent, skip to step 4.
   • For each distinct helper type among the absent helpers, run ${CLAUDE_PLUGIN_ROOT}/bin/ha-agent-lab ha list-helpers --type <type> once to check whether any absent helper of that type already exists under a different entity_id. If found, reference that entity instead.
   • For each helper that genuinely needs to be created, compose the JSON payload. Minimum required fields by type:
     • input_boolean / input_text: {"name": "Friendly Name"}
     • input_number: {"name": "...", "min": <N>, "max": <N>} (optional: step, initial, mode)
     • input_select: {"name": "...", "options": ["opt_a", "opt_b"]}
     • input_datetime: {"name": "...", "has_date": true, "has_time": true}
     • timer: {"name": "...", "duration": "HH:MM:SS"}
     • counter: {"name": "...", "initial": 0, "step": 1}
     • schedule: {"name": "..."} with weekday blocks — run ha list-helpers --type schedule to inspect the schema of any existing helper; if none exists, check the HA schedule integration docs for the required block format.
   • Run ${CLAUDE_PLUGIN_ROOT}/bin/ha-agent-lab ha create-helper <type> '<json>' and handle the result:
     • "requires_confirm": true — ha_safety_mode is ask; describe the helper to the operator and ask for confirmation. On confirm, re-run with --confirm.
     • "blocked": true, "requires_confirm": false — ha_safety_mode is strict; explain the boundary and create a proposal via /claude-code-hermit:proposal-create. Do not retry with --confirm. Continue to validation so the operator sees which entities are still missing.
     • "ok": true — helper created; continue.
   • If any helpers were created, run ${CLAUDE_PLUGIN_ROOT}/bin/ha-agent-lab ha refresh-context --incremental to update the snapshot before validation.

4. Validate:

   • Run ${CLAUDE_PLUGIN_ROOT}/bin/ha-agent-lab ha simulate <path> to check entity references and policy.
   • Run ${CLAUDE_PLUGIN_ROOT}/bin/ha-agent-lab ha policy-check <path> for a safety assessment.

5. Handle results:

   • severity: "allow" — valid and safe: offer to apply via /claude-code-homeassistant-hermit:ha-apply-change.
   • severity: "ask" (ask mode) — explain which sensitive entities are involved, then offer to apply. The apply step will require explicit operator confirmation.
   • severity: "block" (strict mode) — explain why and create a proposal using /claude-code-hermit:proposal-create.
   • If entities are missing: suggest refreshing context first.

YAML Conventions

• IDs: snake_case, language-neutral, descriptive
• Aliases: stored locale, human-readable
• Descriptions: stored locale, explain the purpose
• Triggers: use platform: explicitly
• Actions: use service: with full domain (e.g., light.turn_on)
• Targets: prefer entity_id over area/device when specific

Safety

Under ha_safety_mode: strict (the default): never draft automations that actuate lock, alarm_control_panel, or security-related cover/button/switch. If the user requests this, explain the safety boundary and create a proposal for manual review. Under ask: draft and run ha policy-check — the severity field in the result drives step 5.