docs: add AGENTS.md for AI agent guidance

[GuyKh]

User description

Summary

Add comprehensive AGENTS.md file for AI coding agents working on this Home Assistant custom component. This follows best practices from established HA custom component repositories.

Changes

• Created AGENTS.md with:
  • Project overview and tech stack
  • Code structure documentation
  • Local development instructions
  • Code style guidelines (Python, ruff, mypy)
  • Key patterns (ConfigEntry, Coordinator, Entity)
  • Project-specific rules (IEC identifiers, API concepts, data storage keys)
  • Common tasks (adding sensors, binary sensors)
  • Validation commands and error recovery strategy
  • Breaking changes guidance
  • Quality standards
  • Links to additional resources

Why

Having an AGENTS.md helps AI coding agents (GitHub Copilot, Claude, etc.) understand:

• How to work with this specific project
• Validation commands to run before committing
• Home Assistant patterns to follow
• Error recovery strategies

This follows the pattern used by well-documented HA custom components like hacs.integration_blueprint.

---

PR Type

Documentation, Enhancement

---

Description

• Add comprehensive AGENTS.md for AI coding agent guidance

• Update py-iec dependency to 0.5.3 with manifest sync

• Bump Home Assistant version to 2025.1.4

• Document project structure, patterns, and validation workflow

---

Diagram Walkthrough

flowchart LR
  A["AGENTS.md<br/>AI Agent Guide"] --> B["Project Overview<br/>& Tech Stack"]
  A --> C["Code Structure<br/>& Patterns"]
  A --> D["Development<br/>Workflow"]
  A --> E["Validation &<br/>Quality Standards"]
  F["Dependencies<br/>Updated"] --> G["iec-api 0.5.3"]
  F --> H["Home Assistant<br/>2025.1.4"]

Loading

File Walkthrough

	Relevant files
Documentation	AGENTS.md Comprehensive AI agent guidance documentation                        AGENTS.md Created comprehensive AI agent instructions document with 217 lines Covers project overview, tech stack, code structure, and local development setup Documents key patterns including ConfigEntry, Coordinator, and Entity patterns Includes validation commands, error recovery strategy, and breaking changes guidance Provides common tasks for adding sensors and handling API changes +217/-0
Dependencies	manifest.json Update iec-api dependency version                                                custom_components/iec/manifest.json Updated iec-api requirement from 0.5.2 to 0.5.3 +1/-1      requirements.txt Update Home Assistant and iec-api versions                              requirements.txt Updated Home Assistant from 2024.2.0 to 2025.1.4 Updated iec-api from 0.5.2 to 0.5.3 +2/-2

---

[qodo-code-review]

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Separate dependency upgrades from documentation changes The PR mixes the addition of a new documentation file with a significant Home Assistant version upgrade from 2024.2 to 2025.1. It is recommended to separate these changes into two distinct PRs to properly isolate and test the impact of the dependency upgrade. Examples: requirements.txt [2-3] homeassistant==2025.1.4 iec-api==0.5.3 Solution Walkthrough: Before: # PR combines documentation and dependency bumps in one go. # AGENTS.md + File created with 217 lines of documentation. # requirements.txt - homeassistant==2024.2.0 + homeassistant==2025.1.4 - iec-api==0.5.2 + iec-api==0.5.3 After: # Suggestion: Split into two separate PRs. # PR 1: Documentation only # AGENTS.md + File created with 217 lines of documentation. # requirements.txt # (no changes) --- # PR 2: Dependency upgrades only # requirements.txt - homeassistant==2024.2.0 + homeassistant==2025.1.4 # (plus any necessary code changes to support the new version) Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a risky, major dependency upgrade for Home Assistant bundled with documentation, which could introduce breaking changes without code adaptations, and wisely recommends separating them.	High
General	Clarify coordinator data storage pattern Clarify that the coordinator instance is stored in hass.data[DOMAIN][entry.entry_id] and that fetched data is accessed via the coordinator.data attribute. AGENTS.md [97] -- Stores data in `hass.data[DOMAIN][entry.entry_id]` +- The coordinator instance is stored in `hass.data[DOMAIN][entry.entry_id]`. +- Fetched data is available via `coordinator.data`. Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly clarifies the Home Assistant coordinator pattern, which improves the accuracy of the new documentation and helps prevent the target AI agent from generating incorrect code.	Low
Update