# Repository working rules The project is a generic robotics onboarding, simulation, and training platform. Choose an intake route in [Workflow](docs/WORKFLOWS.md). Use [Usage](docs/USAGE.md) for commands and [Contributing](CONTRIBUTING.md) for layout. Apply the mandatory [per-robot skill maintenance rule](AGENTS.md#maintain-skills-after-every-robot-intake) to every intake. ## Checks Run from the repository root with the editable install active. ```bash python -m pip install -e ".[dev]" python -m pytest tests/ -q python -m ruff check . python scripts/train.py --list ``` For a host with unrelated pytest plugins on its Python path, run pytest in the project environment with `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`. Use [agent setup](docs/AGENT_SETUP.md) if imports resolve to a different checkout. ## Architecture - The root and `rl/` are separate package roots. `rl/` has no `__init__.py`. Keep imports from `mjrl`, `mjlab`, and `rsl_rl` in their existing form and use the editable install to resolve them. - `mjrl.backend.select.use_backend` must run before creating an environment. The manager resolves mjlab's simulation class when it builds the environment. Native MuJoCo implements the batched simulator interface that Warp provides. - Native rollout scratch data is per worker. Restore each environment's state, controls, and warm starts from its own buffers. Constant recomputation uses dedicated scratch data and preserves visual statistics. - `tasks/registry.py` discovers literal `tasks//robot_spec.py` files. Listing tasks must stay free of simulation imports. The selected family resolves to a locked template in `tasks/templates/`. - Keep physical facts in the robot specification and asset. Keep reward and observation logic, randomization, curriculum, and PPO in the templates. Adding a robot requires no changes to a template or a command entry point. - Onboarding and verification are in `rl/mjrl/onboarding/`. Deterministic controls live in `rl/mjrl/controllers/`, and the portable native runtime lives in `rl/mjrl/platform/`. The legacy Rust controller and target build tools remain in `deploy/`. ## Changes and verification - Preserve the lock in `tests/test_template_lock.py`. Review an authorized template revision before updating the recorded hashes, including shared dependencies that change template behavior. - Verify physics and control response separately. Report measured outcomes with the model, backend, and run size. A shape check, a visual preview, or a completed iteration alone cannot establish behavior or hardware readiness. - Keep changes to vendored libraries identifiable with an `[mjrl]` marker, reason, and upstream version. See [Vendoring](docs/VENDOR.md). - Write repository material in English. A Chinese `*.zh.md` translation carries the digest of its English source. Update both before refreshing the marker with `tools/checks/stamp_translations.py`. - Exercise tests against the quiet failure they claim to prevent. When an assertion could pass vacuously, include a control that demonstrates detection.