home-assistant-controller/AGENTS.md

AGENTS.md

Project

A sidecar for Home Assistant that runs automations using arrowized functional reactive programming (AFRP). Haskell, built with cabal.

Working style

• When doing any non-trivial work, always work in a worktree on a feature branch
• Feature branches should be named as the topic of the change

Code style

• Vertical modules: split by feature/concept, not by layer.
• Comments are minimal. They describe the contract, not the implementation, and should stay stable as the implementation changes.
• Never ever log directly to stdout via putStr and friends. Always use proper logging functions

Build

• Nix-backed project: flake.nix provides the devShell, default.nix is the generated cabal derivation.
• Always run cabal through the devShell: nix develop -c cabal build.
• After adding dependencies to the .cabal file, regenerate the derivation: nix run nixpkgs#cabal2nix -- ./. > default.nix. Do not edit it by hand.
• secrets.yaml is sops-encrypted. Never read, print, or commit its contents.

Tests

• hspec for unit tests, hedgehog for property tests.
• Run with nix develop -c cabal test.

Reviewing

Reviews are recorded in git notes under refs/notes/review; read the latest note before reviewing. See REVIEW.md.