60 lines
4.0 KiB
Markdown
60 lines
4.0 KiB
Markdown
# 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/<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.
|