Cdx

.agents/skills/q2-backend-development/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: q2-backend-development
+description: Implement, modify, or review Q2 physics backends and their task-facing state contract. Use for changes under gym/envs/base involving SimBackend, MuJoCo CPU or Warp, VSim, RobotLayout, state tensors, reset ordering, quaternion conversion, contacts, asset import, backend selection, or a new physics engine.
+---
+
+# Q2 Backend Development
+
+Read `AGENTS.md`, `gym/envs/base/sim_backend.py`,
+`gym/envs/base/robot_layout.py`, the affected backend, and its contract tests.
+Read the relevant current section of `MIGRATION_PLAN.md` for parity decisions.
+
+## Preserve the public contract
+
+- Leave every public tensor valid after `setup()` and updated in place after
+  `step()` and reset. Tasks cache tensor objects; property getter side effects
+  do not satisfy liveness.
+- Expose canonical `RobotLayout` order for DOFs, bodies, torques, contacts,
+  `dof_state`, and `rigid_body_states`. Keep engine-native indices private.
+- Keep `dof_state` persistent with writable `dof_pos`/`dof_vel` views. If an
+  engine stores positions and velocities separately, gather into a persistent
+  assembled buffer and scatter public reset writes back to native storage.
+- Follow write-then-commit resets. Do not refresh native root state over a
+  pending public `root_states` write between DOF and root commits.
+- Keep task quaternions scalar-last `[x, y, z, w]`; convert once at the
+  backend boundary.
+- Interpret input torques as canonical full-DOF generalized forces. Apply
+  free-joint offsets and native permutations in the backend.
+- Expose robot-only bodies and world-frame contact force vectors in Newtons.
+  Build semantic contact groups in canonical space.
+
+## Make a backend change
+
+1. State the engine's native conventions: quaternion order, pose/velocity
+   layout, contact force meaning and frame, actuation interface, asset losses,
+   batching, device support, and deterministic behavior.
+2. Decide which tensors are native views and which are assembled copies. Name
+   the exact refresh and scatter sites for each.
+3. Implement fixed-base pendulum setup/step/reset first. Fail immediately on
+   unsupported devices or joint types.
+4. Add the backend fixture and run shared contract and damped-energy tests.
+5. Compare pendulum lockstep or analytic behavior against MuJoCo CPU.
+6. Add floating-base root state, canonical body state, ground/contact support,
+   and partial resets.
+7. Add named routing, legged contract, termination, and task-level liveness
+   tests before RL smoke tests.
+8. Wire selection through `task_registry.select_backend()` without fallback.
+9. Benchmark only after correctness gates pass; record environment count,
+   timestep, rollout geometry, device, warmup, and warnings.
+
+## Engine-specific scars
+
+- MuJoCo imports URDF effort/velocity limits incompletely; Q2 reparses them in
+  `urdf_limits.py`. Preserve that path and add asset-specific tests.
+- MuJoCo may fuse fixed-linked bodies; Q2 disables `fusestatic` so canonical
+  bodies such as feet remain addressable.
+- MuJoCo uses scalar-first quaternions, angular-first body velocities, and
+  `[torque, force]` spatial contact arrays. CPU and Warp must both call the
+  post-constraint RNE operation before exposing contact forces.
+- MuJoCo Warp native arrays are zero-copy, but canonical/swizzled tensors are
+  assembled. Refresh them eagerly. Forward `njmax` to Warp data allocation;
+  a constraint overflow is incorrect physics, not a harmless warning.
+- MuJoCo CPU and Warp model construction belongs in
+  `mujoco_backend_base.py`. Avoid backend-specific physics drift.
+- VSim motor, articulation, body, and sensor order are independent. Route by
+  exact native indices/names, rotate link-attached force components to world
+  axes, and close its process singleton cleanly.
+- Per-engine config pass-throughs must be explicit, validated, and covered by
+  a test showing that the engine actually consumes them.
+
+## Validate
+
+Start with targeted tests, then run:
+
+```bash
+uv run --frozen python -m pytest -q
+```
+
+For VSim changes also run:
+
+```bash
+bash scripts/run_vsim_tests.sh
+```
+
+A GPU-specific test skipped on a CPU machine is not evidence that the GPU path
+works. For physics claims, add a predicted invariant, lockstep comparison, or
+fidelity probe. For state/reset/contact bugs, land the regression test with
+the fix and update `MIGRATION_PLAN.md` if campaign evidence changes.

.agents/skills/q2-backend-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Q2 Backend Development"
+  short_description: "Develop Q2 physics backends safely"
+  default_prompt: "Use $q2-backend-development to change a Q2 physics backend without breaking its contracts."

.agents/skills/q2-development-environment/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: q2-development-environment
+description: Set up, repair, and verify Q2's uv-managed .venv across Linux CPU, Linux NVIDIA GPU, macOS, and the optional licensed VSim backend. Use for fresh checkouts, dependency or Python problems, import failures, platform mismatches, CUDA/Warp setup, VSim loader or license failures, and local-versus-CI discrepancies.
+---
+
+# Q2 Development Environment
+
+Read `AGENTS.md`, `.python-version`, `pyproject.toml`, `uv.lock`, and the
+relevant setup section of `README_MUJOCO.md` before changing dependencies.
+`pyproject.toml` and `uv.lock` are the only dependency sources of truth.
+
+## Establish the target
+
+- Use uv to create and manage the repository's `.venv`.
+- Use Python 3.11 for the common tested environment and VSim wheel
+  compatibility. The package metadata permits Python 3.11 through 3.13.
+- Use MuJoCo CPU for portable/headless development and the Linux CPU viewer.
+- Use MuJoCo Warp only with a working NVIDIA driver and CUDA-visible PyTorch.
+- Use VSim only when the machine has the local wheel, system library, node
+  license, and CUDA. Never replace a requested backend with another silently.
+
+## Create or update the environment
+
+Use the locked dependency graph for ordinary development:
+
+```bash
+uv sync --frozen
+uv run --frozen python -c "import mujoco, torch; print(mujoco.__version__, torch.__version__)"
+uv run --frozen python -m pytest -q
+```
+
+Use `.venv/bin/python` directly only when a tool must bypass uv resolution.
+
+For MuJoCo Warp:
+
+```bash
+uv sync --frozen --extra gpu
+uv run --frozen python -c "import torch, mujoco_warp; print(torch.cuda.is_available())"
+```
+
+Require the final command to print `True`. If it does not, inspect
+`nvidia-smi`, the PyTorch build, and device visibility; do not add a CPU
+fallback.
+
+For VSim, follow `thirdparty/vlearn/README.md` exactly. Install the local wheel
+with `uv sync --locked --extra vsim`; start every process with
+`uv run --env-file .env.vsim ...`; validate using
+`bash scripts/run_vsim_tests.sh`. Do not print or inspect license contents.
+
+## Diagnose by boundary
+
+- Resolution/install failure: compare `pyproject.toml`, `uv.lock`, local wheel
+  presence, and exact uv flags. Do not casually regenerate the lockfile.
+- Python mismatch: check `uv run --frozen python --version` and
+  `sys.executable` before debugging imports.
+- Warp import but no CUDA: confirm driver visibility and the installed torch
+  build separately.
+- Long first Warp step: distinguish kernel compilation from a deadlock using
+  the traceback and GPU activity before interrupting it.
+- VSim loader errors: environment variables must exist before process start;
+  in-process changes to `LD_LIBRARY_PATH` are too late.
+- VSim license errors: verify paths and activation state without reading,
+  logging, or committing secrets. License repair may require the vendor.
+- macOS viewer errors: use `mjpython` with the Homebrew-Python recipe in
+  `README_MUJOCO.md`, or validate headless behavior.
+- CI mismatch: inspect `.github/workflows/` directly. CI runs the uv-managed
+  portable and colocated suites, Ruff, and a package build, but does not cover
+  smoke training, Warp, or licensed VSim.
+
+## Change dependencies
+
+Explain why a dependency belongs in the modern core, `gpu` extra, `vsim`
+extra, or dev group. Update `pyproject.toml` and the lockfile together, then
+test a clean sync appropriate to every affected platform. Update
+`README_MUJOCO.md` when setup steps or supported versions change.

.agents/skills/q2-development-environment/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Q2 Development Environment"
+  short_description: "Set up and verify Q2 development"
+  default_prompt: "Use $q2-development-environment to set up and verify this Q2 checkout."

.agents/skills/q2-rl-development/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: q2-rl-development
+description: Design, implement, or review Q2 reinforcement-learning behavior, including observations, actions, rewards, PPO2, SAC, actors and critics, storage, normalization, runner data flow, and tuning methodology. Use for changes under learning/, reward or observation code in task classes, algorithm hyperparameters, network architecture, rollout geometry, inference, checkpoint state, or training-quality claims.
+---
+
+# Q2 RL Development
+
+Read `AGENTS.md`, the selected task and runner config, the active runner and
+algorithm, and their focused tests. Confirm which configured class names are
+actually instantiated; the tree includes legacy and experimental paths.
+
+## Trace data before editing
+
+For the main on-policy path, trace one update end to end:
+
+1. Actor/critic observation names are resolved from environment attributes.
+2. `TaskSkeleton.get_state()` divides named states by configured scales.
+3. The actor emits actions; runner assignment multiplies action states by
+   their scales.
+4. The environment steps the backend for its configured decimation.
+5. `DictStorage` records transitions for the collected temporal horizon.
+6. `PPO2` performs repeated optimizer minibatches without recounting the same
+   rollout as fresh normalization data.
+7. The logger records total and per-term episode metrics and checkpoints model,
+   optimizer, iteration, and normalization state.
+
+Do not infer behavior from a config field alone; find its consumer.
+
+## Observations and actions
+
+- Keep actor and critic observation lists explicit. Every listed attribute must
+  exist with stable shape; every scaled attribute needs a scaling entry.
+- Keep canonical joint/body order at the task boundary. Express semantic
+  subsets with cached `RobotLayout` group indices, not slices.
+- Keep inference deterministic: switch modules/normalizers to evaluation mode
+  and use clean observations. Noise belongs only in rollout collection.
+- Update observation statistics once per fresh rollout population. Freeze them
+  during repeated optimizer epochs, and save/load them with the policy.
+
+## Rewards
+
+- A nonzero runner-config weight selects `_reward_<name>`; zero weights should
+  remove unused computation. Each reward returns shape `[num_envs]`.
+- `_sqrdexp(error)` is maximized when `error == 0`. Write down the intended
+  optimum before coding; do not pass a raw target quantity whose optimum is
+  elsewhere.
+- Use means for comparable per-joint penalties so magnitude transfers across
+  robots. Use sums only when physical total magnitude is intended and tested.
+- Keep termination handling separate from ordinary weighted rewards.
+- When changing reward math, add a small test for its zero point, sign, scale,
+  shape, and boundary behavior before training.
+
+## Rollout and optimizer geometry
+
+Treat these as separate controls:
+
+- `rollout_batch_size`: total new transition samples collected per update;
+  together with `num_envs`, it determines consecutive steps per environment.
+- `batch_size`: optimizer minibatch size.
+- `max_gradient_steps`: number of actor/critic optimization steps.
+
+When comparing backends or configurations, hold temporal horizon and collected
+sample count constant unless that variable is the experiment. Equal minibatch
+size alone does not make two PPO experiments equivalent.
+
+Discount and GAE values may be derived from physical horizons and control dt.
+Re-run frequency conversion rather than editing derived values.
+
+## Evidence workflow
+
+1. State the proposed mechanism and a result that would falsify it.
+2. Predict direction and useful numeric bounds before running.
+3. Add a unit test for deterministic math, storage, normalization, inference,
+   or checkpoint behavior.
+4. Run same-seed, same-task, same rollout-geometry before/after experiments.
+5. Compare per-term rewards, episode duration/survival, action statistics,
+   losses/KL, throughput, and domain-relevant physical metrics. Do not select
+   only on aggregate reward or a viewer impression.
+6. Record failed or invalid experiments in `MIGRATION_PLAN.md` when they affect
+   the active campaign. Keep tuning changes numerically explicit and separate
+   from algorithm/refactor changes.
+
+Validate with focused learning tests and then:
+
+```bash
+uv run --frozen python -m pytest -q
+```

.agents/skills/q2-rl-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Q2 RL Development"
+  short_description: "Design Q2 rewards and learning changes"
+  default_prompt: "Use $q2-rl-development to change Q2 rewards, observations, or learning code."

.agents/skills/q2-task-authoring/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: q2-task-authoring
+description: Add or modify a Q2 robot, environment, task variant, asset, config, or registry entry end to end. Use when introducing a URDF, creating fixed-base or legged tasks, adding semantic robot groups, changing task observations/actions/rewards, registering a task, or making an existing task work across MuJoCo CPU, Warp, and optional VSim.
+---
+
+# Q2 Task Authoring
+
+Read `AGENTS.md`, the nearest existing task and config, the appropriate base
+robot class/config, `gym/envs/__init__.py`, `robot_layout.py`, and task-focused
+tests. Copy the nearest semantic example, not merely the newest file.
+
+## Choose the task shape
+
+- Use `FixedRobot` for a base attached to the world. Its MuJoCo path disables
+  contacts and has no `root_states` commit.
+- Use `LeggedRobot` for a free base, ground contact, canonical body state, and
+  contact-driven termination/rewards.
+- Prefer a config/task variant when physics and robot layout are shared. Do
+  not fork backend logic into a concrete task.
+
+## Add the asset
+
+- Place URDFs below `resources/robots/<robot>/`. Give every actuated joint
+  finite lower/upper, effort, and velocity limits.
+- Keep source inertias physically valid: positive principal moments satisfying
+  the triangle inequality. Add a parser-level regression for repaired assets.
+- Prefer supported `.stl`/`.obj` visual meshes; MuJoCo strips unsupported DAE
+  visuals. Keep collision geometry independent of visual availability.
+- Keep files below the repository's 100 KB limit; never solve this by
+  force-adding a binary.
+- Define an explicit `asset.robot_layout` when policy-facing order or semantic
+  groups matter. Canonical names must exactly cover movable URDF joints and
+  robot links. Define groups such as legs, feet, or end effectors by exact
+  names; avoid semantic slices and substring order assumptions.
+
+## Add configuration
+
+Create environment and runner config subclasses in the task package.
+
+- Set `env.num_envs`, actuator count, episode length, asset path/base mode,
+  initial state, control frequencies, terrain/contact lists, scaling, and
+  robot layout explicitly.
+- Set actor/critic observation attribute lists, action state names, algorithm
+  sampling/optimization parameters, reward weights, and experiment name.
+- Treat `ctrl_frequency` and `desired_sim_frequency` as inputs. Never assign
+  derived dt/decimation values in the task config.
+- Make required config axes required. If a backend does not implement a
+  configured feature such as per-env domain randomization, disable or document
+  it explicitly rather than implying that it works.
+
+## Implement the task
+
+- Keep engine imports and native indices out of concrete task code.
+- Preserve the constructor's legacy positional parameters and forward
+  `backend=` to the base class.
+- Build observations from stable environment attributes; add matching scales
+  for every scaled state. Keep action tensors and actuator routing in
+  canonical order.
+- Name rewards `_reward_<config_weight>`, return `[num_envs]`, and use exact
+  semantic group indices cached at setup.
+- Use zero-error inputs with `_sqrdexp`; reduce per-joint terms with `mean`
+  unless scale-by-DOF is explicitly intended.
+
+## Register and package
+
+Add all four mappings in `gym/envs/__init__.py`: `class_dict`, `config_dict`,
+`runner_config_dict`, and `task_dict`. Update setuptools package/data discovery
+so the built wheel contains the task module and its required assets. Imports
+are fail-fast; inspect the live registry after adding the declarations:
+
+```bash
+uv run --frozen python -c "import gym.envs; from gym.utils.task_registry import task_registry; print(sorted(task_registry.task_classes))"
+```
+
+Do not treat an editable-tree import as packaging proof. Build the wheel and
+smoke-import the registered task from an isolated installation.
+
+## Prove the task
+
+1. Add registry, layout/routing, asset-limit/inertia, and reward/observation
+   shape tests appropriate to the task.
+2. Run the full unit gate:
+
+```bash
+uv run --frozen python -m pytest -q
+```
+
+3. Smoke train the CPU path with few environments and iterations, headless and
+   without W&B. Use the new task name:
+
+```bash
+uv run --frozen scripts/train.py --task TASK --backend mujoco --device cpu --num_envs 8 --max_iterations 2 --headless --disable_wandb
+```
+
+4. Exercise Warp and VSim only after CPU correctness, with their real contract
+   tests and exact-name routing checks. A skipped optional-backend test is not
+   a pass. Update `README_MUJOCO.md` if the public task list changes.

.agents/skills/q2-task-authoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Q2 Task Authoring"
+  short_description: "Add and modify Q2 robot tasks"
+  default_prompt: "Use $q2-task-authoring to add or modify a robot task in Q2."