dora-joy/AGENTS.md

AGENTS.md

Rules for AI coding assistants working in this repository.

• dora >= 1.0. Verified against dora-cli 1.0.1, which CI pins in .gitea/workflows/validate.yml.
• uv for everything: uv sync --group dev, uv run pytest, uv run ruff check ., uv run python .... Never pip into the ambient environment.
• ruff is the linter and the formatter. uv run ruff check . must be clean.
• Markdown is linted too, by markdownlint-cli2 in CI. Its line length is set in .markdownlint.json.
• numpy-style docstrings.
• Dependencies must ship prebuilt wheels for linux-x86_64, linux-aarch64 and macos-arm64. uv sync is the whole install: no system packages, no compiler.
• Nothing outside dora_joy/gamepad.py may touch pygame. Everything else sees a plain Sample, which is what lets it be tested with no pad plugged in.
• Nothing is shaped on the way out. No deadzone, no expo, no clamping, no rescaling of a trigger. Raw SDL or nothing: what a reading means belongs to whatever acts on it, and two places shaping one number is a bug nobody can see.
• Do not teach this node what a control is for. No GRASP_BUTTON variable, no semantic output ports. This is a source; it names no consumer.
• Publish on every tick, changed or not. The stream doubles as a heartbeat, so silence means the node died and nothing else. Do not add publish-on-change.
• present is never inferred from zeroed axes. An absent pad is not a centred pad, and a consumer driving something that moves needs the difference.
• The Arrow schema is declared, never inferred. pyarrow reads an empty axes list as list<null>, so an inferred schema would change type the moment a pad is unplugged.
• Do not commit or push. Leave changes in the working tree and wait to be asked.
• Do not mention AI tools in commit messages or documentation.