hacs.integration_blueprint: Skill for Claude Code

Debug the running integration

Work from evidence, not from guesses. The order below is deliberate: reproduce, read the log, localise to a layer, then fix.

File	When to read
references/async-rules.md	A blocking-call warning, a thread-safety error, or a hang with no traceback behind it

1. Reproduce with a clean instance

Always use the project scripts — hand-rolled hass or pip invocations miss the venv, PYTHONPATH, port cleanup, and debugpy setup, and are the single most common cause of agents getting stuck.

./script/develop

If Home Assistant is unresponsive or the port is held:

pkill -f "hass --config" || true && pkill -f "debugpy.*5678" || true && ./script/develop

Restart after any change to Python files, manifest.json, services.yaml, translations, or the config flow.

Once it is up, script/ha reads the instance directly — entity states, config entry status, diagnostics, the error log — so nothing below depends on asking the developer to look something up in the UI. It authenticates itself; there is no token to set up.

script/ha status     # reachable, and which version
script/ha entries    # did the config entry actually load

The instance is shared

The developer restarts Home Assistant, clicks through the UI, and tries things out while you work — often precisely because you are busy. Never carry the instance's run state from one step to the next. Observe it.

script/ha status    # exit 0 up, exit 2 down; `started` and `uptime` reveal a restart you did not do

• A changed run state is the expected case, not a fault. Running when you left it stopped means the developer started it. Do not go through ps, the process tree, or the log looking for an explanation — start it, or re-run your command, and carry on.
• Spend at most one re-check on it. If it still does not add up, say what you observed and continue with the task. Reconciling who started what is never the task.
• ./script/develop takes the instance over — it is not "start it if it is not running". It kills whatever is already bound to config/ and starts its own, by design, because the log has to stream into the terminal that launched it. So the developer's terminal falls silent, and the live log they were watching is gone. Check script/ha status first and simply use the instance that is already there. Run script/develop only when it is genuinely down, or when a change to Python, manifest.json, services.yaml, translations or the config flow forces a restart — and say that you are doing it. Never restart to tidy up.
• The same happens in reverse, and is equally fine: when the developer runs ./script/develop, the instance you started dies and whatever file you were writing its log to stops growing. Treat that as normal and re-orient.
• Announce it before you take exclusive control, so the developer knows to keep their hands off meanwhile. That covers script/setup/reset, script/ha token --rotate and --revoke, and any loop that restarts repeatedly — all of them need Home Assistant stopped or undisturbed.
• ha call, ha flow, ha reload and ha loglevel change what the developer sees. Cheap and reversible, but a config entry created by a flow stays until someone removes it.
• State the run state when you finish — after checking it, never from memory.