agentleFS
hass-energyhass-energy/haeo/AGENTS.md

haeo

AGENTS.md77 starsChanged 20 days agoMITView on GitHub

This repository contains HAEO (Home Assistant Energy Optimizer) - a Python 3.13+ Home Assistant custom component for energy network optimization using linear programming. HAEO optimizes energy usage across battery storage, grid import/export, loads, and generators using linear programming. The integration provides real-time optimization based on energy prices, forecasts, and system constraints. The integration lives in custom_components/haeo/ and is layered: - core/ holds everything that does not need Home Assistant: the LP model (core/model/), element schemas and config migrations (core/schema/), adapters…

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

19 rules. About 0 are common, 14 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Convention over configuration: Prefer uniform patterns that work the same everywhere over configurable options that require case-by-case …

    line 38
  2. Distinctive:

    When code paths diverge based on metadata flags or configuration, ask whether the divergence is necessary.

    line 39
  3. Distinctive:

    Avoid "check if X then do Y else do Z" patterns - instead, make X and Y go through the same code path

    line 53
  4. Distinctive:

    When adding a feature, prefer creating new simple components over adding branches to existing ones

    line 54
  5. Very specific:

    When the type checker needs a union of kinds, define it once in the package __init__.py beside the other registries, not at the use site

    line 61
  6. Distinctive:

    When making changes, don't leave behind comments describing what was once there.

    line 66
  7. Very specific:

    Use plain English commit messages without conventional commit prefixes (feat:, fix:, refactor:, etc.).

    line 71
  8. Distinctive:

    Write a short summary line in imperative mood, followed by a blank line and bullet points if needed.

    line 72
  9. Distinctive:

    When making changes, don't leave behind backwards-compatible interfaces for internal APIs.

    line 76
  10. Distinctive:

    Always assume that accessed properties/fields which should exist do exist directly.

    line 87
  11. Distinctive:

    When reviewing code, rely on linting tools (Ruff and Pyright) to identify issues that they can detect.

    line 94
  12. Distinctive:

    Do not report on issues that these tools already catch, such as:

    line 95
  13. Distinctive:

    Use SI-derived units scaled for numerical stability:

    line 129
  14. Distinctive:

    When working with element subentries:

    line 141
  15. Very specific:

    When updating version numbers, update both files together, then run uv sync to regenerate uv.lock.

    line 161
  16. Distinctive:

    Write descriptions that name the subject and say when to use it.

    line 170
  17. Very specific:

    Read the skill covering an area before changing code in it.

    line 172
  18. Very specific:

    Run uv run check before considering work complete.

    line 177
  19. Distinctive:

    When the user provides feedback about systemic corrections (coding patterns, style issues, architectural decisions, or recurring mistakes), …

    line 194

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

HAEO agent instructions

This repository contains HAEO (Home Assistant Energy Optimizer) - a Python 3.13+ Home Assistant custom component for energy network optimization using linear programming.

Project overview

HAEO optimizes energy usage across battery storage, grid import/export, loads, and generators using linear programming. The integration provides real-time optimization based on energy prices, forecasts, and system constraints.

Project structure

The integration lives in custom_components/haeo/ and is layered:

  • core/ holds everything that does not need Home Assistant: the LP model (core/model/), element schemas and config migrations (core/schema/), adapters that turn configuration into model elements and outputs (core/adapters/), and forecast parsing and input loading (core/data/). It must never import Home Assistant; import-linter enforces this.
  • Home Assistant glue sits beside it: config and subentry flows (flows/), the coordinator that runs each optimization cycle (coordinator/), the entity classes behind the sensor, number, and switch platforms (entities/), readers of Home Assistant state, calendars, and recorder history (inputs/), and config entry migrations, diagnostics, repairs, and services.
  • tools/ holds the developer CLIs, and frontend/ the forecast card.

The architecture guide describes each package and how they interact.

Tests are colocated with source code in tests/ subdirectories within each package. The top-level tests/ directory holds only scenario tests, guide tests, and CLI tool tests.

Development tools

  • Package manager: uv (use uv sync for dependencies, uv run to execute tools)
  • Testing: pytest, with scenario, guide, and benchmark markers selecting the slower suites (uv run check selects them the way CI does)
  • Linting/Formatting: Ruff (Python), Prettier (JSON), mdformat (Markdown)
  • Type checking: Pyright
  • Documentation: Zensical builds docs/ from mkdocs.yml

Agent behavioral rules

These rules apply to all AI agent interactions with this codebase:

Design principles

Convention over configuration: Prefer uniform patterns that work the same everywhere over configurable options that require case-by-case logic. When code paths diverge based on metadata flags or configuration, ask whether the divergence is necessary. Often, a single convention that handles all cases uniformly is simpler and more maintainable.

  • Derive behavior from existing structure rather than adding metadata flags
  • Make all instances of a pattern work the same way - no special cases
  • Let upstream validation (e.g., config flows) enforce constraints so downstream code can assume valid data
  • Config flows use vol.Required() and vol.Optional() to enforce required fields at entry time
  • Downstream code (coordinator, adapters) can assume required fields are present because config flow guarantees it
  • For optional values, if they are missing or None, skip them uniformly throughout processing

Composition over complexity: Build features by composing simple, focused components rather than adding conditional logic to existing code. Each component should do one thing well without needing to know about the internals of other components.

  • Separate concerns: validation happens at config flow boundaries, processing assumes valid input
  • Avoid "check if X then do Y else do Z" patterns - instead, make X and Y go through the same code path
  • When adding a feature, prefer creating new simple components over adding branches to existing ones
  • Runtime code uses the result of schema validation, not the schema itself - the schema's job is done at configuration time

Attributes, not enumeration: Tell kinds of things apart by an attribute or structure of the thing itself, not by listing the kinds where the distinction is used. Adding or deleting an element should not mean searching for every place that names it.

  • Branch on a class, an adapter or spec attribute, or a registry lookup, such as checking that a registered model element subclasses NetworkElement, rather than element_type in (NODE, BATTERY, ...)
  • When the type checker needs a union of kinds, define it once in the package __init__.py beside the other registries, not at the use site
  • The same applies to documentation and translations: describe the pattern, and leave each kind to its own page or placeholder

Clean changes

When making changes, don't leave behind comments describing what was once there. Comments should always describe code as it exists without reference to former code.

Commit messages

Use plain English commit messages without conventional commit prefixes (feat:, fix:, refactor:, etc.). Write a short summary line in imperative mood, followed by a blank line and bullet points if needed.

API evolution

When making changes, don't leave behind backwards-compatible interfaces for internal APIs. There should always be a complete clean changeover.

Error context

The main branch is always clean with no errors or warnings. Any errors, warnings, or test failures you encounter are directly related to recent changes in the current branch/PR. These issues must be fixed as part of the work - they indicate problems introduced by the changes being made.

Property access

Always assume that accessed properties/fields which should exist do exist directly. Rely on errors occurring if they do not when they indicate a coding error and not a possibly None value. This is especially true in tests where you have added entities and then must access them later. Having None checks there reduces readability and makes the test more fragile to passing unexpectedly.

Code review guidelines

When reviewing code, rely on linting tools (Ruff and Pyright) to identify issues that they can detect. Do not report on issues that these tools already catch, such as:

  • Unused imports
  • Type errors
  • Style violations
  • Formatting issues
  • Other issues detectable by static analysis tools

Focus review comments on:

  • Logic errors and bugs
  • Architectural concerns
  • Performance issues
  • Security vulnerabilities
  • Code clarity and maintainability
  • Missing tests or documentation

This avoids false positives and redundant feedback that linting tools already provide.

Universal code standards

  • Python: 3.13+ with modern features (pattern matching, str | None syntax, f-strings, dataclasses)
  • Type hints: Required on all functions, methods, and variables
  • Typing philosophy: Type at boundaries, use TypedDict/TypeGuard for narrowing, prefer types over runtime checks
  • Formatting: Ruff (Python), Prettier (JSON), mdformat (Markdown)
  • Linting: Ruff
  • Type checking: Pyright
  • Language: American English for all code, comments, and documentation
  • Testing: pytest with coverage enforced by codecov on changed lines

See typing philosophy for detailed type patterns.

Units

Use SI-derived units scaled for numerical stability:

  • Power: kilowatts (kW)
  • Energy: kilowatt-hours (kWh)
  • Time: hours (model layer) / seconds (rest of code)

The model layer uses hours for time to keep LP solver values in the ideal range. The rest of the codebase uses seconds for time (Home Assistant convention). See units guide for rationale.

Subentry naming conventions

When working with element subentries:

  • subentry.title MUST match the element's name field
  • subentry.subentry_type MUST match the element's element_type field
  • In participants dictionaries, keys represent element names (matching subentry.title)

These invariants are enforced throughout the codebase and must be maintained.

Translation and naming conventions

HAEO follows Home Assistant's entity naming conventions for sensor translations. The translations skill has the detailed rules.

Version matching

The version number must be consistent across:

  • pyproject.toml (version = "x.y.z")
  • custom_components/haeo/manifest.json ("version": "x.y.z")

When updating version numbers, update both files together, then run uv sync to regenerate uv.lock.

Skills

Detailed standards and workflows live in .agents/skills/, one directory per skill, each with a SKILL.md. They follow the Agent Skills open standard, so Copilot, Cursor, Claude Code, Codex, and other compatible agents all read the same files.

Skills load on demand: an agent sees only each skill's name and description until a task matches, then reads the full instructions. That means the description decides whether the rule is followed at all. Write descriptions that name the subject and say when to use it.

Read the skill covering an area before changing code in it. python and integration apply to nearly all work in this repository.

Verification

Run uv run check before considering work complete. It runs every CI job that can run locally — ruff, pyright, import boundaries, mdformat, prettier, version consistency, unit tests, scenario tests, frontend card checks, and the documentation build — in about 65 seconds. --fast runs ruff, pyright, and unit tests in about 35. HACS validation has no local equivalent and runs only in GitHub Actions. The documentation build runs in strict mode, so a broken internal link or #anchor fails it. hassfest is not part of uv run check, but the lint skill shows how to run it from Home Assistant's source; do so after changing translations, the manifest, services, or repair issues.

Tests run under timeout = 5 per test with filterwarnings = ["error"], so a new warning is a hard failure and a hang surfaces as a 5-second timeout.

Documentation

  • Documentation guidelines - Writing and maintaining docs
  • Units guide - Unit conversion and conventions
  • Testing guide - Test patterns and scenarios

Self-maintenance

When the user provides feedback about systemic corrections (coding patterns, style issues, architectural decisions, or recurring mistakes), update the appropriate instruction file to capture that feedback for future sessions.

The agent-setup skill explains how the skills are organized and how to add one.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.