Files
2026-11-03 19:46:08 +08:00

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.