Files
UniversalHumanoid/AGENTS.md
T
2026-11-03 19:46:08 +08:00

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-vendor and 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.