# 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](.agents/skills/setup-env/SKILL.md) | Detect/install a new environment or diagnose backend/CUDA dependencies | | [new-task](.agents/skills/new-task/SKILL.md) | Add a robot/task and run mechanical/interface conformance checks | | [train](.agents/skills/train/SKILL.md) | Train, inspect learning curves, manage checkpoints/jobs and compare experiments | | [controls](.agents/skills/controls/SKILL.md) | Inspect control contracts, joint/torque CSV and simulation replay | | [deploy](.agents/skills/deploy/SKILL.md) | Export/verify research bundles and state hardware exclusions | | [rl-engineer](.agents/skills/rl-engineer/SKILL.md) | Coordinate a reward-to-evaluation experiment across the stages | Detailed references: [Setup](docs/SETUP.md), [Robot checks](docs/NEW_ROBOT.md), [Training operations](docs/TRAINING_OPERATIONS.md), [Vendor sources](docs/VENDOR.md), [CLI reference](docs/CLI.md). `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/_smoke.json --output NEW_REPORT` checks sites, IMU, contacts, PD/limits, joint order and initial posture against declared expectations. `./scripts/uh smoke --config experiments/_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.