dora_littlehand/AGENTS.md

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