4.0 KiB
Agent engineering contract
Keep project changes within this repository. Treat external dependencies and robot asset checkouts as read-only unless the operator explicitly authorizes changes to them.
Task manuals
Read the matching manual before acting; this index serves agents that do not auto-discover skills.
| Manual | Use when |
|---|---|
| setup-env | Detect/install a new environment or diagnose backend/CUDA dependencies |
| new-task | Add a robot/task and run mechanical/interface conformance checks |
| train | Train, inspect learning curves, manage checkpoints/jobs and compare experiments |
| controls | Inspect control contracts, joint/torque CSV and simulation replay |
| deploy | Export/verify research bundles and state hardware exclusions |
| rl-engineer | Coordinate a reward-to-evaluation experiment across the stages |
Detailed references: Setup, Robot checks,
Training operations, Vendor sources,
CLI reference. tests/test_layout.py enforces index/link/CLI synchronization.
Boundaries
- The coding agent is the orchestrator; use
scripts/uh. No separate LLM service is required. - Do not delegate work or start multi-agent workflows unless the operator asks for them.
- Use installed vendored backends in
rl/; do not install separate mjlab/rsl-rl-lib distributions. - Verify
doctor,verify-vendorand the lock before changing dependencies; no personal path fallbacks. - Vendor changes require explicit review, modification notices and inventory updates; never refresh hashes merely to silence failures.
- Public documentation must distinguish reusable features from reference-environment evidence and release blockers.
- Never change the task's robot, joint order, actuator model or observation dimensions silently.
- Keep hardware facts in robot adapters, reward mechanisms in
rewards.py, and tuning in experiments. - Never disable falls to manufacture a successful evaluation. Keep finite episodes and censoring counts.
- Never call a two-iteration run a converged policy, nor call an ONNX bundle hardware-ready.
- No physical robot bus, motor enable, firmware flash or autonomous real-world deployment.
- Do not run untrusted checkpoints: the upstream loader uses pickle.
- Do not delete failed runs. New experiment, new directory. Read failure status and logs.
- Evaluate and export a baseline before editing source. Provenance intentionally rejects source drift.
- Read training curves (tracking, action std, episode length); elapsed time is not evidence of learning.
- Use explicit checkpoint manifests, status/stop and new-directory resumes; never guess the newest file.
- Distinguish evaluation seeds from training replicas and completed-only failure fractions from incidence.
- Check actual randomized states, push counts and censoring before claiming stress-test coverage.
Checks
./scripts/check runs lint and tests without inherited ROS pytest plugins.
./scripts/uh check-robot --config experiments/<robot>_smoke.json --output NEW_REPORT checks
sites, IMU, contacts, PD/limits, joint order and initial posture against declared expectations.
./scripts/uh smoke --config experiments/<robot>_smoke.json checks actual GPU dynamics.
A full acceptance check needs bounded PPO training, a fixed-command evaluation and ONNX parity.
A task is supported only after its sensors/collisions, resolved action order, reward finiteness, training, evaluation and export have been checked. Asset discovery alone is not support.
Reporting
State exact config/run/checkpoint/report paths, GPU, iteration/env/step counts and measured metrics. Separate plumbing validation, learning quality, export parity and physical safety. Never select a reward revision by raw reward total alone; compare fixed-protocol tracking and failures across seeds.