Skip to content

AGENTS.md

Latest commit

 

History

History
48 lines (36 loc) · 4.38 KB

AGENTS.md

File metadata and controls

48 lines (36 loc) · 4.38 KB
Raw

AI Agent Instructions for Home Assistant iOS

This is the router for AI coding agents (LLMs) working on the Home Assistant for Apple Platforms codebase. Detailed guidance lives in modular skills under .agents/skills/. Load the skill that matches your task instead of reading everything up front.

Home Assistant for Apple Platforms is a native Swift companion app for Home Assistant home automation. The primary user interaction is through a WKWebView displaying the Home Assistant web frontend, with native features for notifications, sensors, location tracking, widgets, CarPlay, Apple Watch, and more.

  • Language: Swift 5.8+
  • Platforms: iOS, watchOS, macOS (Catalyst), CarPlay
  • Build System: Xcode 26.2+, Swift Package Manager
  • Project: Open HomeAssistant.xcodeproj directly (dependencies are managed via Swift Package Manager)

Non-Negotiable Conventions

These apply to every change, even if you don't load the matching skill:

  • One type per file: each struct/class/enum lives in its own file named after the type — never stack multiple top-level types (especially SwiftUI View structs) in one file. Small private helper types nested inside the type are the only exception. Every SwiftUI view ships with a #Preview. See ha-ios-ui for the full UI rules.
  • SwiftUI confirmations stay on the trigger: apply .confirmationDialog directly to the Button that opens it, not to a parent List, Section, or container view. This keeps confirmation ownership local and avoids dialogs firing from unrelated controls.

Skills

Skill Load it when you are…
ha-ios-architecture Starting in the repo, deciding where code lives across targets, using the global Current (World pattern), or setting up dependencies and code signing
ha-ios-webview Working on WebViewController, the JavaScript external message bus, custom URL schemes, or deep links into the frontend
ha-ios-magicitem Adding or changing MagicItem types or actions shared by Widgets, Watch, CarPlay, and App Shortcuts
ha-ios-localization Adding or changing user-facing strings, using L10n, or dealing with Lokalise translations
ha-ios-code-style Writing or formatting Swift, running SwiftFormat/SwiftLint, referencing SF Symbols or Material Design icons, logging, or using with()
ha-ios-concurrency Writing async/await, actors, or Combine, deciding whether to touch PromiseKit, or calling the server via HAKit
ha-ios-persistence Adding or migrating a persistent model, or choosing between GRDB, Realm, and UserDefaults
ha-ios-push-live-activities Implementing or fixing push notifications or Live Activities across the local-push and remote-push flows
ha-ios-ui Building UI, choosing SwiftUI vs UIKit, or following the one-struct-per-file, inline-body, and #Preview rules
ha-ios-testing Writing unit or snapshot tests, or mocking dependencies by overriding Current
ha-ios-workflow-ci Preparing a change for commit or understanding the CI gates that must pass before merge
ha-ios-skill-maintenance Adding, editing, or reorganizing these skills, or updating this router

Additional Resources

AI policy

This project follows the Open Home Foundation AI Policy. Autonomous contributions are not accepted: a human must review, understand, and be able to explain every change before it is submitted. Do not open issues or pull requests autonomously, and do not post comments on behalf of a user without their review.