zorruno-homeassistant/AGENTS.md

Home Assistant OpenCode Rules

You are working directly inside a live Home Assistant installation (/homeassistant).

Critical Mandates & Approval Rules

1. Read-Only by Default: Only read files and query APIs when investigating. Never modify files or call state-changing services without explicit user confirmation.
2. Explicit Confirmation: Show the exact diff or file content to be written before making any change. Wait for user approval ("yes", "go ahead").
3. One Change at a Time: Apply minimal changes, report what changed, and verify before proceeding.
4. No Unsolicited Work: Do not refactor, clean up, or change unrelated code/files beyond the requested scope.
5. Project Context Protocol:
   • Associate requests with a stable project ID in PROJECTS.md (e.g. P013).
   • Read PROJECTS.md before starting work. Record durable context under the project ID.
   • Never mark a project Complete unless the user explicitly confirms completion. Ask: "Should I close Pxxx?"

Off-Limits & Restricted Paths

Never read, write, or access:

• .storage/, .cloud/, deps/, tts/
• home-assistant_v2.db*, home-assistant.log*
• secrets.yaml (never expose or log secret contents)

Use MCP tools (get_devices, get_areas, get_entity_details, get_history) or CLI tools (hab) instead of accessing internal storage or database files.

Configuration & Architecture Gotchas

• Directory Includes in configuration.yaml:
  • automation: Uses !include_dir_merge_list automations/ -> Active automations are in automations/, NOT root automations.yaml (which is legacy/inactive).
  • script: Uses !include_dir_merge_named scripts/ -> Active scripts are in scripts/, NOT root scripts.yaml.
  • group: Uses !include_dir_merge_named group/ -> Active groups are in group/, NOT root groups.yaml.
  • packages: Uses !include_dir_named packages/.
  • template: Uses !include_dir_merge_list templates/.
  • sensor: Uses !include_dir_merge_list sensor/.

CLI & Tooling Reference

Shell YAML Queries (yq)

• Always use yq (mikefarah/Go version) for CLI YAML processing. PyYAML and Ruby YAML crash on HA tags (!include, !secret).
• Example: yq '.homeassistant.latitude' configuration.yaml

Home Assistant Admin (hab CLI)

• Pre-authenticated CLI tool for managing HA via terminal (hab <command> --json).
• Common commands:
  • Entities & Devices: hab entity list --domain light --json, hab device list --json
  • Automations/Scripts: hab automation list --json, hab script list --json
  • Dashboards: hab dashboard list --json, hab dashboard get <id> --json
  • Operations: hab system health --json, hab backup create

Zigbee Toolkit (zigporter CLI)

• Handles cascade renames across automations, scripts, scenes, and Lovelace dashboards.
• Command: zigporter rename-entity light.old light.new --apply (Defaults to dry-run if --apply omitted).
• Note: zigporter migrate requires physical interaction and must NOT be run by AI.

Safe Configuration Writing (MCP)

• Prefer write_config_safe(file_path, content, dry_run=true) to pre-validate before writing.
• Always read the target file first and preserve all existing content when writing.

Mandatory YAML Style Rules

• Indentation: 2 spaces (no tabs).
• Strings: Double quotes ("..."). Exceptions: entity IDs, action names, area IDs, device classes, modes.
• Booleans: Lowercase true/false only. Never on/off/yes/no as YAML booleans.
• Lists & Maps: Block style only. Never flow style [1, 2] or {key: val}.
• Action Targets: Always use target: block (target: entity_id: light.room). Do not put entity_id inside data: or at root action level.
• Templates: Use states('sensor.x') and is_state(...) helpers. Never use direct state object access (states.sensor.x.state).