ha-config-entry-migrate

Files (1)

• SKILL.md

SKILL.md (first lines)

# HA Config Entry Migrate

Spec: `spec/claude/ha-config-entry-migrate/en.md` (EN canonical) / `spec/claude/ha-config-entry-migrate/de.md` (DE translation).

This skill owns the config-entry **migration** path — `async_migrate_entry` plus the `VERSION` / `MINOR_VERSION` bump — that no other skill covers. It sits between `ha-config-flow-augment` (which explicitly excludes destructive refactors) and the initial scaffold, and is the maintenance move an integration needs whenever its stored `entry.data` / `entry.options` shape changes.

## Why this is a skill, not an agent

- **Human-visible augmentation surface** — the user describes the schema change and reads back the `async_migrate_entry` body, the version bump, and the migration test; a skill keeps this on the visible command surface, like the sibling `ha-config-flow-augment`.
- **Mid-flow interactivity** — whether the change is breaking (major `VERSION`) or backward-compatible (minor `MINOR_VERSION`), and the exact key transforms, are per-run dialogues the user confirms before generation.
- **Bounded, inline generation** — one migration function plus the version bump and a test fits inline; no isolated agent context is needed.
- Counter-dimension considered: the draft→validate loop could be an agent, but the breaking-vs-minor decision and the report belong in the user's working context; skill wins.

## When this skill activates

Use this skill when an existing integration's stored config-entry shape changed — a renamed key, a moved value (`data` → `options`), a new required default, a split field — and old entries on disk must be migrated forward on load.

## When NOT to activate

- greenfield integration setup → `ha-integration-scaffold`
- setup-time config-flow patterns (tenant / reauth / reconfigure / zeroconf / oauth) → `ha-config-flow-augment`
- adding a new post-setup option (no migration of existing entries) → `ha-options-flow-augment`
- deploying/importing into a running HA instance → out of scope (generation only)

## Hard rules

1. **One migration, one version step, one run.** Migrate to the next version; never batch several schema generations into one function without the intermediate steps.
2. **Bump the right version.** A breaking shape change bumps `ConfigFlow.VERSION` (major); a backward-compatible additive change bumps `MINOR_VERSION` (minor). State which and why.
3. **Reject a newer entry.** `async_migrate_entry` returns `False` when `config_entry.version > <current major>` (a downgrade the running code cannot handle) so HA marks the entry as migration-failed rather than corrupting it.
4. **Transform, never drop.** Rename / move / default / split keys explicitly and write them back via `hass.config_entries.async_update_entry(entry, data=new_data, options=new_options, version=…, minor_version=…)`. Unrelated keys are carried over verbatim; no key is dropped silently.
5. **Idempotent and ordered.** Guard each step by the source version (`if entry.version == 1: …`) so re-running the migration is safe and multi-step upgrades apply in order.
6. **Land the test.** Add a `tests/test_init.py` (or `tests/test_migration.py`) test that seeds an old-version `MockConfigEntry`, runs setup, and asserts the entry is migrated to the new `version`/`minor_version` with the transformed keys.
7. **Name per `spec/ha/naming-conventions/en.md`** and **verify HA internals against the official docs** (see `spec/ha/upstream-docs-verification/en.md`).

## Inputs

| Field | Required | Default | Notes |
|---|---|---|---|
| `target_dir` | yes | — | repo root of the existing integration |
| `change` | yes | — | the schema change in prose (which keys rename / move / split / default) |
| `breaking` | no | inferred + confirmed | breaking (major `VERSION`) vs. backward-compatible (`MINOR_VERSION`) |

## Pre-flight (in order — abort on first failure)

1. `git -C <target_dir> rev-parse --is-inside-work-tree` and a clean working tree.
2. `custom_components/<domain>/config_flow.py` and `__init__.py` exist; read `domain`, the current `VERSION`/`MINOR_VERSION`, and the existing `entry.data`/`entry.options` shape.
3. Resolve `breaking` (infer + confirm) and the concrete key transforms.

## Workflow

### 1) Resolve and confirm

State `domain`, the from/to version, whether it is breaking, and the exact key transforms in one paragraph. Wait for confirmation.

### 2) Apply

- `config_flow.py` — bump `VERSION` (and/or `MINOR_VERSION`) on the `ConfigFlow`
- `__init__.py` — add or extend `async def async_migrate_entry(hass, config_entry) -> bool`, version-guarded, returning `False` on a newer entry and writing the transformed entry via `async_update_entry(...)`
- `tests/test_init.py` (or `tests/test_migration.py`) — the old-entry → migrated-entry test

### 3) Validate & report

Validate offline (version bumped; `async_migrate_entry` present, version-guarded, returns `False` on a newer entry, writes via `async_update_entry`, drops no key; the migration test is present) and emit a CONFORMANT / NEEDS-WORK report keyed to the acceptance criteria, plus the changed file paths.

## Boundaries

- Setup-time config-flow patterns → `ha-config-flow-augment`
- Adding a new option without migrating existing entries → `ha-options-flow-augment`
- Reauth/reconfigure flows (not a stored-shape migration) → `ha-config-flow-augment`

From nolte/claude-home-assistant, MIT.

More from nolte/claude-home-assistant