Skip to content

AGENTS.md

Latest commit

 

History

History
53 lines (46 loc) · 4.21 KB

AGENTS.md

File metadata and controls

53 lines (46 loc) · 4.21 KB
Raw

Purpose

WattPlan is the source of truth for the WattPlan Home Assistant custom integration and its in-repo optimizer. Optimize for clean integration behavior, reliable Home Assistant tests, and release artifacts that stay HACS-compatible. Prefer updating the integration, tests, and docs together when behavior changes.

Do / Don't

  • Do: treat WattPlan as the canonical repo and hass-core as the runtime/test harness via symlink.
  • Do: keep custom_components/wattplan/optimizer/ free of homeassistant imports.
  • Do: update docs when workflows, release behavior, or architecture changes.
  • Don't: edit the backup copies under hass-core/*/wattplan.pre-symlink-backup-*.
  • Don't: reintroduce vendor_poweroptim; the optimizer lives under optimizer/.
  • Don't: assume hass-core is clean before changing symlinks or running migrations.

Pushback / quality bar

  • Before starting new projects or automation, evaluate whether the effort is justified and push back if build time exceeds the time it would save.
  • If a request would introduce hacks, unclear behavior, or long-term maintenance risk, push back and propose a safer alternative.
  • Avoid obvious performance pitfalls; call them out and offer a better approach.
  • Prefer clear, simple code over clever or verbose implementations.

Core workflows

  • Build: python scripts/build_hacs_zip.py
  • Test: pytest
  • Run: PYTHONPATH=. pytest tests or PYTHONPATH=. ../hass-core/.venv/bin/pytest tests
  • Release: use docs/release.md as the authoritative runbook for all release questions, preparation, tag handling, release text, and artifact publication.

Testing in Codex

  • When running pytest from Codex, request elevated execution for each test run instead of using the default sandbox.
  • Current issue: Home Assistant pytest bootstrap can hang inside the sandbox, while the same tests complete normally outside it.
  • Treat sandboxed pytest hangs as environment noise unless the same failure reproduces in an elevated run.
  • At the end state of a code change, especially before committing, run the full test suite unless there is a clear reason not to; if skipping it, state the reason explicitly.
  • When this repo is on a mounted or network-backed filesystem, prefer placing Codex-managed test virtualenvs on a native local filesystem under /tmp instead of a repo-local .venv; uv installs on the mounted path can leave the Home Assistant package incomplete.
  • The default ./scripts/run_tests.sh wrapper already uses worktree-specific paths under /tmp for both the virtualenv and pytest --basetemp. Reuse that convention for Codex-created envs to avoid collisions across parallel worktrees.

Repo conventions

  • Integration code lives in custom_components/wattplan/.
  • Optimizer code lives in custom_components/wattplan/optimizer/.
  • Home Assistant integration tests live in tests/integration/.
  • Optimizer-only tests live in tests/optimizer/.
  • hass-core/config/custom_components/wattplan and hass-core/tests/custom_components/wattplan are symlinks into this repo.
  • Keep release packaging focused on the integration tree under custom_components/wattplan/.
  • The HA integration acquires four planner input series: import price, export price, usage, and PV.
  • Each source uses one configured provider mode, then passes through normalization/fixup to produce one value per planner slot before the optimizer runs.
  • Keep source acquisition behavior centered in source_pipeline.py, source_provider.py, source_fixup.py, and coordinator.py; preserve the rule that optimizer/ stays free of homeassistant imports.

Documentation upkeep

  • README.md — keep quickstart, release flow, and repo purpose aligned with the current structure
  • docs/development.md — update when local workflow, symlink setup, or test commands change
  • docs/architecture.md — update when code boundaries or planning/runtime flow changes
  • docs/release.md — update when tag, prerelease, or artifact behavior changes
  • docs/optimizer-api.md — update when optimizer import paths or request/response models change

When to split

If this file grows beyond a page, or if the repo has distinct task areas (for example docs/release vs integration/runtime), ask whether to split into AGENTS.<TASK>.md files.