Skip to content

AGENTS.md

Latest commit

 

History

History
63 lines (52 loc) · 2.56 KB

AGENTS.md

File metadata and controls

63 lines (52 loc) · 2.56 KB

This file is the canonical guardrails + pointers for Codex work in this repo.

Project overview

  • docs/overview.md
  • README.md (end-user docs for release v2.0; may lag behind dev)

Current status

  • docs/status.md

Ongoing tasks

  • docs/todo.md
  • TODO

Setup

  • docs/setup.md

Architecture

  • docs/architecture.md

Design contracts (immutable)

  • docs/design/filtering-contract.md
  • docs/design/config-flow-contract.md
  • docs/design/calendar-contract.md
  • docs/design/sensor-contract.md

Context for Codex

  • docs/context.md
  • docs/decisions.md
  • test/fixtures/usecases.json (UC catalog)

Legacy references

  • docs/resume_prompt.txt (legacy backup)
  • docs/design/filtering-design-checkpoint.md (legacy backup)
  • docs/design/filtering-config-flow-design.md (legacy backup)
  • docs/vibe/context.md (legacy, empty)

Project file structure (in-file)

  • custom_components/skolmat/: Home Assistant integration code.
  • custom_components/skolmat/processors/: optional per-source normalizers.
  • skolmat-card/: Lovelace card submodule.
  • docs/: working docs and design contracts.
  • test/: fixtures and tests (including UC catalog).

Devcontainer model (in-file)

  • .devcontainer/devcontainer.json uses image hass_dev_image_2025.12.2.
  • Post-create runs container setup-project -> .devcontainer/setup-project.
  • Mounts skolmat-card/ into HA config www/.
  • Bootstraps HA .storage from .devcontainer/ha_config_bootstrap/.storage.
  • Ports: 8123 (HA) and 5678 (debugpy).

Generic guardrails (in-file)

  • Do not modify design contracts unless explicitly requested.
  • Treat test/fixtures/usecases.json as ground truth. All implemented logic should be represented in this file. Suggest updates when neccesary.
  • Don’t refactor entire architecture without approval.
  • Never refactor code outside of the currently discussed scope.
  • Only run code generation related to current file / feature.
  • Prefer small, reviewable changes; avoid sweeping reformatting.
  • Update or add tests when behavior changes; call out gaps explicitly if not possible. Suggest additions/updates to test/fixtures/usecases.json as needed.
  • When requirements are unclear, pause and ask one question at a time before coding.
  • Keep dev docs in docs/ aligned with actual behavior; do not update end-user docs (README.md) unless requested.
  • Avoid editing legacy backups unless explicitly asked.
  • Use UTF-8 when Swedish terms or data require it; do not force ASCII where it harms clarity.
  • Log important decisions in docs/decisions.md without waiting for confirmation.