write

HA NOVA Write

Scope

Mutations only:

• domains: automation, script
• operations: create, update, delete

Bootstrap (once per session)

Verify Relay:

ha-nova relay health

If this fails, run onboarding: ha-nova setup.

Relay Contract

File-based relay requests only: ha-nova relay core --method <METHOD> --path <PATH> --body-file <payload-file> for config writes, ha-nova relay ws --data-file <payload-file> for reads/reloads, --jq-file / --out for filters and large reads.

Flow

Multi-target logical changes: present the plan first per skills/ha-nova/write-safety.md → Multi-Target Changes.

Phase 1: Resolve (Agent)

1. Read skills/ha-nova/agents/resolve-agent.md.
2. Fill placeholders.
3. Dispatch. Extract target_id, current_config, bp_status, suggested_enhancements.
   • update/delete: resolve known entity_id -> unique_id with config/entity_registry/get; use config/entity_registry/list_for_display only for search/disambiguation
4. On ambiguity/no-match: ask one blocking question for the exact entity_id. No second ambiguity question. Correct invalid premises.
5. create IDs: automations=Unix timestamp, scripts=slug.

Phase 2: Preview + Confirm (Main Thread)

1. Build config. For update: full-replacement merge (base=current, overlay=user changes).
   • Do not rewrite unrelated structure, aliases, or formatting for a narrow change.
   • Treat notification copy as user-authored content: preserve notification titles, messages, templates, metadata. Rename/timing changes must not restyle, relocalize, or restructure existing text; requested wording changes change only the requested copy.
2. BP gate (skills/ha-nova/write-safety.md): fresh/stale+simple->continue, stale+complex->block.
3. Suggestions + Pre-Write Checks (skip for delete):
   • 3a) Suggestions: Show suggested_enhancements (max 4, numbered/menu). User accepts numbers or "skip" → merge accepted into config BEFORE preview. Skip when SUGGESTED_ENHANCEMENTS: none.
   • 3b) Static Checks: Use skills/review/checks.md → Application (family matrix + evidence boundaries). Run S/R/P/M checks analytically on the draft YAML — no relay calls (scripts: F-01..F-08; helper refs: H-01..H-08. Defer H-09/H-10 to Phase 4). One pre-write verdict line before apply:
     • clean draft → localized equivalent of "Pre-write check: no issues worth flagging before save."
     • any flagged draft → localized equivalent of "Pre-write check: this draft may not behave as intended." 🔴 findings → inline warning + fix. 🟠🟡 findings → advisory below preview. Keep wording code-free. Advisories do not block the write and do not require extra confirmation:
     • R-18: REST/UI write can break dependent variables in that block. Tell user to inspect traces after the next real run; do not auto-trigger/read them.
     • R-19: final else branch is only reached when the earlier entity-state branches are false. Move trigger.id into elif or refactor to choose + condition: trigger.
     • If R-23 matches: boolean-like template values are compared to string "True"/"False"; use the boolean directly or direct negation.
     • If R-24 matches: available_energy may be current charge, not capacity; ask user to verify maximum/nominal source. Never auto-rewrite integration-specific entity IDs. Track findings by check type for dedup in Phase 4, except R-18.
   • 3c) Pre-Write Impact (update only): run search/related on the top target entities (max 3 related configs); show affected automations/scripts as advisory. Skip create/delete.
4. Preview (see skills/ha-nova/write-safety.md for the fixed shape):
   • update: run ha-nova diff (prefer --out <diff-file>), print the diff output verbatim in the Changes slot — never write it yourself; state the behavioral effect in the summary sentence (write-safety → Behavior narrative). create: summary. Create/update previews show apply, show yaml, and cancel options.
   • Delete preview MUST include the consumer-check result before confirmation: either the affected consumers or an explicit no-consumer result.
   • Delete previews do not show apply, show yaml, cancel, or any menu; ask only for the exact confirm:<token> or cancellation.
5. Confirmation: create/update=natural, delete=tokenized confirm:<token>. Active Preview Confirmation is required; delete is the typed token, never a menu. Pre-preview consent is draft-only; payload/diff changes need preview.

Phase 3: Apply + Verify (Agent)

1. Read skills/ha-nova/agents/apply-agent.md.
2. Fill with confirmed payload.
3. Dispatch. Expect: success, write_status, verification.
4. Report result. No raw curl/JSON in output.
   • Do not report destructive success until verification proves the target is gone.

Fallback: If agent dispatch unavailable, execute inline.

Phase 4: Post-Write Review (MANDATORY)

Do NOT invoke ha-nova:review separately.

1. Re-read by target_id (do NOT re-resolve by slug):
   • automation: ha-nova relay core --method GET --path /api/config/automation/config/<target_id> --jq-file <filter-file> --out <result-file>
   • script: /api/config/script/config/<target_id>
   • <filter-file>: copy skills/ha-nova/config-body-filter.jq; if unavailable (flat-copy installs), recreate exactly:

     if .ok then .data.body else error("relay error: \(.error.message // "unknown")") end
     

   • for create/update: reload again only if Phase 3 reported reloaded: false or ran inline without reload; resolve actual entity_id by matching unique_id == <target_id>, then read /api/states/{entity_id} to confirm runtime presence
   • if the actual entity_id differs, report it and point to skills/ha-nova/safe-refactoring.md; do not silently assume the requested slug won
2. S/R/P/M/F checks (narrowed):
   • Compare read-back vs draft as normalized objects, not raw JSON strings; key order is irrelevant. Ignore metadata (id,unique_id,created_at,modified_at,editor,enabled).
   • HA may normalize keys during write (trigger→triggers, action→actions, condition→conditions). Account for plural aliasing when comparing — these are not real diffs.
   • Core fields differ beyond aliasing → full checks per skills/review/checks.md → Application. If they match, skip covered checks but re-run storage-sensitive R-18 subset.
   • Dedup: findings from Phase 2 Step 3b that the user saw MUST NOT repeat. Track by check type.
   • Exception: if R-18 still matches on persisted read-back config, report it again as a persisted runtime risk.
   • R-19 follows normal dedup; R-23/R-24 do too. If already shown pre-write, do not repeat unless it becomes a new category.
   • If persisted R-18 remains, inspect traces after the next real run. Do not auto-trigger or auto-read traces.
   • If actions reference helpers: always run H-01..H-10.
3. Collision scan: {"type":"search/related","item_type":"entity","item_id":"<entity_id>"} via ha-nova relay ws --data-file <payload-file>; read max 3 related configs.
4. Post-Write Review output (localized; see skills/ha-nova/output-rules.md) — report only what has substance; scans still run, only empty output is suppressed:
   • Findings: real issues only. Collision check: only when related items exist (list them + the verdict). Advisory: only when non-empty. Omit any section with nothing to report — never print an empty "none" bucket.
   • If nothing is worth reporting, collapse to one scope-honest confirmation line (write-safety → Verification Honesty).
   • Never emit Questions to consider, Suggestions, or Instant help post-write; never repeat an item across Findings and Advisory.
5. Update-Revert: updates only → run ha-nova snapshot save and offer revert (see skills/ha-nova/write-safety.md). Creates → cleanup via normal HA NOVA delete flow with preview, confirm:<token>, and absence verification. Deletes → Home Assistant Backups.

Output Format

Apply skills/ha-nova/output-rules.md.

Previews, delete prompts, and post-write results render as the Cards defined there; the diff mechanics stay in skills/ha-nova/write-safety.md.

See skills/ha-nova/SKILL.md → Response Format.

Safety

• Preview before write: nothing is saved until the user confirms the shown preview.

• Confirmation binds to the displayed preview and expires on any change to target, payload, endpoint, or scope (context skill → Active Preview Confirmation).

• Pre-preview phrases ("do it", "go ahead", "implement the plan") authorize drafting and preview only — never the write itself.

• Delete and destructive operations require the typed token confirm:<token> verbatim; "yes" or any natural-language reply is invalid.

• Never guess entity, service, or config IDs — resolve them or ask.

• Home Assistant is reached exclusively through ha-nova relay.

• For any HA write this skill does not cover, STOP and invoke ha-nova:fallback first — never probe unfamiliar write endpoints.

• Destructive cleanup still requires confirm:<token>, even for items created earlier in the same session.

• Agents must use Relay only; no MCP, no direct HA API

• Every write MUST end with the Post-Write Review slot; use terminal-friendly labels where Markdown headings add noise.

Guardrails

• Never use raw get_states — use targeted registry/config reads
• Max 3 related configs in collision scan

References

Always load:

• skills/ha-nova/relay-api.md, skills/ha-nova/payload-schemas.md, skills/ha-nova/best-practices.md, skills/ha-nova/write-safety.md
• Agent templates: skills/ha-nova/agents/resolve-agent.md, skills/ha-nova/agents/apply-agent.md
• Review checks: skills/review/checks.md (self-contained catalog + Application)

On demand — read only when the trigger applies:

• skills/ha-nova/automation-patterns.md — drafting new branching, timing, or flow-control logic
• skills/ha-nova/template-guidelines.md — the draft contains Jinja templates
• skills/ha-nova/safe-refactoring.md — rename, migrate, or orphan-cleanup tasks
• skills/ha-nova/update-revert.md — the user asks to revert, undo, or restore a verified update (create cleanup and delete recovery stay out — see write-safety)