ha-config-flow-augment

HA Config Flow Augment

Spec: spec/claude/ha-config-flow-augment/en.md (EN canonical) / spec/claude/ha-config-flow-augment/de.md (DE translation).

Why this is a skill, not an agent

• Mid-flow approval is the contract (decisive): augmenting a live config flow edits an existing integration; the pattern choice and the plan are confirmed with the operator before any write, and follow-up corrections continue in the same thread.
• Context access: which integration, which flow pattern, and which existing conventions apply comes from the open conversation and repo state, not from a self-contained input.
• Counter-dimension considered: applying one known pattern is a well-defined unit (agent bias), but losing the approval gate in a fire-and-forget agent would let structural flow changes land unreviewed — interactivity outweighs.

When this skill activates

Use this skill when the user wants to:

• retrofit a tenant / account selection step after the auth step
• retrofit zeroconf discovery into a config flow that did not initially carry it
• retrofit a reauth flow
• retrofit a reconfigure flow
• add OAuth as a parallel auth path next to the existing API-key path

When NOT to activate

• greenfield integration scaffolding → ha-integration-scaffold
• pure schema edits (rename a field, change a default) → manual code edit
• destructive refactors (remove a step, rewrite a step) → manual code edit with explicit user approval
• schema migration of entry.data across versions → ha-config-entry-migrate
• DHCP/SSDP/USB/HomeKit/MQTT discovery (any transport other than Zeroconf) → ha-discovery-augment; this skill's zeroconf pattern owns only the mDNS/Zeroconf retrofit

Hard rules

1. Never overwrite existing flow steps. Augment is additive. If the requested pattern already exists in config_flow.py, abort with "pattern already present".
2. Never touch unrelated modules. Allowed targets: config_flow.py, strings.json, translations/<lang>.json, tests/test_config_flow.py, and (for zeroconf) manifest.json. The oauth pattern additionally writes a registration block in __init__.py, adds application_credentials to manifest.json:dependencies, and scaffolds application_credentials.py (async_get_authorization_server) — modern HA OAuth is Application-Credentials-based.
3. Never split the augment. Code, strings, translations, manifest entry (where applicable), and tests land together in a single commit-ready state. Half augments where code exists but strings are missing are forbidden.
4. Never invent backend specifics. For oauth, the skill scaffolds the flow skeleton — token endpoint, authorize endpoint, scopes, client ID/secret stay user-fed. Surface them in the output as an explicit checklist.
5. Always state the quality-scale impact. The output names which Quality Scale tier the augment unlocks (Bronze → Silver for reauth, Silver → Gold for reconfigure, …).
6. Verify HA internals against the official docs. Don't reproduce HA API signatures, lifecycle hooks, conventions, or schemas from memory — when uncertain, consult the official docs before generating or relying on it: Developer docs developers.home-assistant, architecture/blueprint/YAML docs home-assistant.io (see spec/ha/upstream-docs-verification/en.md).