wecker/AGENTS.md

System Context

This project runs on a Raspberry Pi 4 Model B (2018). Please take this into account for all code changes, dependencies (e.g., ARM architecture), and performance optimizations.

Audio Output Note

When configuring audio or running tasks on this device, always use the 3.5mm headphone jack (Audio Jack) as the explicit audio output unless requested otherwise. The system might have HDMI devices as lower-index cards, which can cause headless/cron background scripts to fail with ALSA errors. Ensure tools and scripts explicitly target the correct audio card (usually hw:2,0 or via a user-wide ~/.asoundrc config).

Development Guidelines

STRICT ADHERENCE to the following guidelines is mandatory for every task. Failure to follow these principles undermines the integrity of the project.

• TDD (Test-Driven Development): Always write tests before implementing the actual logic. Follow the Red-Green-Refactor cycle.
• DRY (Don't Repeat Yourself): Minimize redundancy in code and logic.
• MVP (Minimum Viable Product): Implement only what is necessary to meet the requirement.
• Use uv to manage dependencies for Python.
• Use uv ruff to lint the code.
• Never commit untested code.
• Only commit when ruff is green.

Pre-commit Rules

• Always lint the code (uv ruff).
• Analyze the README.md and update its content if the code changes the use or behavior of the application for the end user or for API consumers.