AGENTS.md

Purpose
Provide project guidelines for agents working in this repository.

Scope
This repository uses Dora, Python, C++, and Rust. Prefer clear, easy-to-understand code and incremental implementation with verification.

General Guidelines
- Keep external dependencies to a minimum. Prefer standard libraries and existing project dependencies.
- Make changes incrementally. Implement small steps, then test or verify before continuing.
- Document assumptions and hardware considerations when relevant.
- Favor readability: simple control flow, meaningful names, and small functions.

Robot Safety
- This is a real robot project. Avoid changes that could cause unsafe motion or unsafe behavior.
- Add or preserve safeguards (limits, checks, bounds) for sensors and actuators.
- If a change affects motion control or safety, call it out explicitly and propose a validation plan.

Language-Specific Rules
Python
- Follow PEP 8 style; use type hints where helpful.
- Prefer dataclasses for structured data.
- Avoid unnecessary abstractions.

C++
- Follow existing project style; default to modern C++ (C++17 or later) unless constrained.
- Prefer RAII and value semantics.
- Avoid raw ownership; use smart pointers where needed.

Rust
- Use idiomatic Rust; prefer ownership/borrowing clarity over complex lifetimes.
- Favor explicit error handling with Result and ?.
- Keep modules small and focused.

Dora
- Keep dataflow definitions simple and explicit.
- Prefer small nodes with clear inputs/outputs.
- Validate node I/O types and message schemas.

Building and Running
- Build dataflows with: `dora build <dataflow.yml> --uv`
- The `--uv` flag uses uv for fast Python dependency management.
- Run dataflows with: `dora start <dataflow.yml>`
- Stop with: `dora stop`
- Check logs with: `dora logs`

Testing and Verification
- Add or update tests when feasible.
- For robot-facing changes, provide a staged validation plan:
  1) Unit or simulation check (if available).
  2) Dry-run or limited-scope run.
  3) Full system run with safety monitoring.

Review Checklist
- Dependencies minimized
- Code readable and consistent with language rules
- Incremental changes validated
- Safety considerations addressed
