# AGENTS.md

## Project overview
- EV3 robot controlled by a PS4 controller using Pybricks.
- Hardware access goes through `DeviceManager` for safe/optional device handling.
- Local development can run without an EV3 by keeping hardware calls mocked or guarded.

## Setup commands
- Python 3.10+ recommended.
- python -m venv .venv
- source .venv/bin/activate
- pip install -r requirements-test.txt

## Dev environment tips
- Keep hardware-specific imports/usage behind guards so code can run on a laptop.
- Prefer dependency injection for sensors/motors to simplify mocking in tests.
- Use `pytest -q` for quick feedback; full run uses coverage and writes to `htmlcov/`.
- When iterating on EV3 code, commit small changes and keep logs concise for on-brick debugging.

## Testing instructions
- Run from repo root: `pytest`
  - Uses settings in `pytest.ini`; coverage reports to `htmlcov/` and XML.
- To target a subset: `pytest tests/test_<area>.py -k "<pattern>"`.
- If hardware is unavailable, mock device classes to avoid import/runtime errors.
- Keep coverage healthy; add/adjust tests when touching controllers, device manager, or safety logic.

## Code style
- Follow PEP 8; prefer descriptive names and small functions.
- Add type hints where practical; keep public APIs documented with docstrings.
- Centralize hardware interactions in `DeviceManager` and avoid duplicated port mappings.
- Default to standard library/testing tools; avoid adding new deps unless necessary.

## PR instructions
- Ensure `pytest` passes before opening/merging.
- Keep PRs scoped; document hardware assumptions/limitations in the description.
- Use imperative, concise titles (e.g., "Add gyro fallback handling").