From 78ed89cb6ff0633cb0eae24476f6b6c2feafe879 Mon Sep 17 00:00:00 2001
From: Moustachauve <2206577+Moustachauve@users.noreply.github.com>
Date: Mon, 12 Oct 2026 00:24:55 -0400
Subject: [PATCH] Add AGENTS.md guidelines for AI coding assistants

Provide project-level instructions for AI agents working on the
python-hilo client library, adapted from Home Assistant guidelines.
The document specifies strict architectural decoupling from Home
Assistant core, AbstractAuth contracts, single-purpose unit testing,
strict typing (forbidding Any in new code), and commit guidelines.
---
 AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5ae31db
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,56 @@
+# Coding Assistant Instructions: python-hilo Library
+
+This repository contains `pyhilo`, a standalone asynchronous Python client library for Hilo energy services (SignalR WebSocket, GraphQL, and REST APIs).
+
+## Git Commit Guidelines
+
+- **First line**: Short, specific imperative sentence (e.g. "Add abstract auth interface for token provider"). No emojis in titles.
+- **Commit description**: Focus on the **WHY** (problem, context, and architectural rationale). Keep it concise, factual, and proportional.
+- **Do NOT amend, squash, or rebase commits that have already been pushed to the PR branch after the PR is opened**: Reviewers need to follow the commit history and see what changed since their last review.
+
+## Development Commands
+
+- Install dependencies: `uv sync`
+- Run test suite: `uv run pytest`
+- Run a specific test: `uv run pytest tests/test_device.py`
+- Check linting and formatting: `uv run ruff check .` and `uv run ruff format --check .`
+
+## Architecture & Boundaries
+
+- **Strict Decoupling from Home Assistant**:
+  - This library MUST NEVER import `homeassistant` or depend on Home Assistant Core modules, constants, or types.
+  - The library must be 100% installable, testable, and runnable independently in any standard Python 3.12+ environment.
+- **Authentication Contract**:
+  - Expose an abstract base class `AbstractAuth` (`pyhilo.auth`):
+    ```python
+    class AbstractAuth(ABC):
+        @abstractmethod
+        async def async_get_access_token(self) -> str:
+            """Return a valid access token, refreshing if necessary."""
+    ```
+  - The library calls this method whenever it needs a valid token, leaving token storage and refresh mechanisms to the consumer (such as the Hilo Home Assistant integration or CLI tools).
+- **Backwards Compatibility**: When modifying public API signatures, provide temporary shims with deprecation warnings for at least 1–2 minor versions to prevent breaking downstream consumers.
+- **Credential Protection**: Never log raw access tokens, refresh tokens, passwords, or decoded JWT claims in `DEBUG` or `INFO` logs.
+
+## Testing Standards
+
+- Verify library protocol behavior, event decoding, device mapping, and error handling.
+- When writing tests or implementation code, ensure all parameters have precise type annotations. **The use of `Any` is strictly forbidden in new code.**
+- **Single purpose tests**: Each test function must verify only one specific behavior or outcome. Avoid testing multiple unrelated scenarios in a single test; split them into focused tests or use parametrization.
+- Prefer standard library `unittest.mock` (`AsyncMock`, `MagicMock`) over large bespoke stub classes.
+- Prefer `@pytest.mark.usefixtures` over unused fixture arguments.
+- Avoid branching (`if`/`else`) in tests; use `@pytest.mark.parametrize` with `pytest.param(..., id="...")` for table-driven testing.
+- Tests must execute cleanly with `uv run pytest` without requiring network access.
+
+## Good practices
+
+- Built with `asyncio`, `aiohttp`, `pysignalr`, and `gql`.
+- Non-blocking I/O: avoid any synchronous disk reads/writes on active event loops. Accept explicit file paths when managing state.
+- Keep `try` clauses as small as possible.
+- When validation guarantees a dict key exists, prefer direct key access (`data["key"]`) instead of `.get("key")`.
+- Keep comments concise and explain only the WHY. Do not restate code or use divider comments (`# --- XYZ ---`).
+- CalVer format: Versions follow `vYYYY.MM.MICRO` (e.g. `v2026.10.1`).
+
+## AI policy
+
+Autonomous contributions are not accepted. Every change must be reviewed and understood by a human contributor before submission. Never open pull requests, create release tags, or post comments autonomously without explicit contributor instruction.