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…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository18 other files it gives its agents.
- agent-setupSkill
- config-flowSkill
- coverageSkill
- documentationSkill
- elementsSkill
- explain-planSkill
- integrationSkill
- lintSkill
- manifestSkill
- modelSkill
- performanceSkill
- pythonSkill
- release-notesSkill
- scenariosSkill
- testingSkill
- translationsSkill
- update-docsSkill
- update-versionSkill
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
- Distinctive: line 38
Convention over configuration: Prefer uniform patterns that work the same everywhere over configurable options that require case-by-case …
- Distinctive: line 39
When code paths diverge based on metadata flags or configuration, ask whether the divergence is necessary.
- Distinctive: line 53
Avoid "check if X then do Y else do Z" patterns - instead, make X and Y go through the same code path
- Distinctive: line 54
When adding a feature, prefer creating new simple components over adding branches to existing ones
- Very specific: line 61
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
- Distinctive: line 66
When making changes, don't leave behind comments describing what was once there.
- Very specific: line 71
Use plain English commit messages without conventional commit prefixes (feat:, fix:, refactor:, etc.).
- Distinctive: line 72
Write a short summary line in imperative mood, followed by a blank line and bullet points if needed.
- Distinctive: line 76
When making changes, don't leave behind backwards-compatible interfaces for internal APIs.
- Distinctive: line 87
Always assume that accessed properties/fields which should exist do exist directly.
- Distinctive: line 94
When reviewing code, rely on linting tools (Ruff and Pyright) to identify issues that they can detect.
- Distinctive: line 95
Do not report on issues that these tools already catch, such as:
- Distinctive: line 129
Use SI-derived units scaled for numerical stability:
- Distinctive: line 141
When working with element subentries:
- Very specific: line 161
When updating version numbers, update both files together, then run uv sync to regenerate uv.lock.
- Distinctive: line 170
Write descriptions that name the subject and say when to use it.
- Very specific: line 172
Read the skill covering an area before changing code in it.
- Very specific: line 177
Run uv run check before considering work complete.
- Distinctive: line 194
When the user provides feedback about systemic corrections (coding patterns, style issues, architectural decisions, or recurring mistakes), …
≈ “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.
Files
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, andfrontend/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 syncfor dependencies,uv runto execute tools) - Testing: pytest, with
scenario,guide, andbenchmarkmarkers selecting the slower suites (uv run checkselects them the way CI does) - Linting/Formatting: Ruff (Python), Prettier (JSON), mdformat (Markdown)
- Type checking: Pyright
- Documentation: Zensical builds
docs/frommkdocs.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()andvol.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 thanelement_type in (NODE, BATTERY, ...) - When the type checker needs a union of kinds, define it once in the package
__init__.pybeside 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 | Nonesyntax, 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.titleMUST match the element'snamefieldsubentry.subentry_typeMUST match the element'selement_typefield- In
participantsdictionaries, keys represent element names (matchingsubentry.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.
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
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.

