mujoco-phase-contracts

Name: mujoco-phase-contracts
Author: Hebbian-Robotics

15stars0forks

How to install mujoco-phase-contracts?

hebbian-robotics/mujoco-workbench/mujoco-phase-contracts

$npx -y skills add Hebbian-Robotics/mujoco-workbench --skill mujoco-phase-contracts

Installs into the current project.

Summary

Use this when working on mujoco-workbench phase contracts, TaskPhase labels, PhaseState expectations, invariants, observability artifacts, or debugging mwb debug contracts and phase failures.

Files · 1

View on GitHub

SKILL.md

1	# Mujoco Phase Contracts
2
3	Phase contracts are executable documentation for scripted scenes. They should
4	answer what must be true at phase starts, phase ends, and invariant samples.
5
6	Relevant modules:
7
8	- `mujoco_workbench.scene_base`: `TaskPhase`, `PhaseState`, `PhaseContract`, invariants.
9	- `mujoco_workbench.observability`: contract evaluation and artifacts.
10	- `mujoco_workbench.phase_monitor`: live runner enforcement.
11	- `mujoco_workbench.runtime`: batch timeline replay used by debug commands.
12
13	## Breaking Down Large Motions
14
15	Use phases to make placement explicit. A good phase should change one kind of
16	state at a time:
17
18	- Base-only movement: drive, yaw, translate, lift, or align the chassis while
19	arm joints stay static.
20	- Arm-only movement: approach, touch/grip, pull/insert, release, or retract
21	while base/lift joints stay static.
22	- Attachment state: activate/deactivate one semantic grasp, weld, connect, or
23	visual state change at an authored boundary.
24
25	For long or fragile motions, split into minute waypoints:
26
27	- `approach`: standoff point in free space, before contact.
28	- `at_target`: TCP/contact point on the surface.
29	- `hold_or_grip`: no pose change; only gripper/attachment state changes.
30	- `clearance`: back out along the same surface normal or lift direction.
31	- `transfer`: move base or lift while the object is held.
32	- `seat_or_release`: final surface/slot point, then deactivate the hold.
33
34	Derive these waypoints from layout geometry, not hand literals. Use:
35
36	```bash
37	uv run mwb debug surface-point ...
38	uv run mwb debug standoff ...
39	uv run mwb debug camera-look-at ...
40	```
41
42	Contract the boundary of each phase with outcome facts: base aux pose,
43	expected object pose, active/inactive attachments, static joint sets, held-object
44	levelness, and qacc sentinels. The indicator-check pattern is the model:
45	drive straight, yaw where the swept radius clears, translate into final click
46	pose, then move arms while the base is frozen.
47
48	Run all contracts:
49
50	```bash
51	uv run mwb debug contracts \
52	--scene examples.scenes.mobile_aloha_piper_indicator_check \
53	--out-root results/runs
54	```
55
56	Replay one phase:
57
58	```bash
59	uv run mwb debug phase wait_at_server \
60	--scene examples.scenes.mobile_aloha_piper_indicator_check \
61	--out-root results/runs
62	```
63
64	Render the phase graph:
65
66	```bash
67	uv run mwb debug phase-graph \
68	--scene examples.scenes.mobile_aloha_piper_indicator_check \
69	--out /tmp/phases.dot
70	```
71
72	Artifacts are plain files:
73
74	- `events.jsonl`
75	- `summary.json`
76	- `phase_contracts.json`
77	- `snapshots/*.npz`
78	- `renders/*.png`
79
80	When adding a new `Step` field that affects sim state, update both
81	`mujoco_workbench.runner` and `mujoco_workbench.runtime` so live behavior and
82	debug artifacts stay identical.
83
84	Do not make contracts assert implementation details. Assert outcomes: base pose,
85	attachment state, grippable pose, held-object invariants, static joints, gripper
86	state, or MuJoCo warning counts.

People who liked this also viewed

6 picks

Type

mujoco-phase-contracts

15stars0forks

View on GitHub

How to install mujoco-phase-contracts?

hebbian-robotics/mujoco-workbench/mujoco-phase-contracts

$npx -y skills add Hebbian-Robotics/mujoco-workbench --skill mujoco-phase-contracts

Installs into the current project.

Summary

Use this when working on mujoco-workbench phase contracts, TaskPhase labels, PhaseState expectations, invariants, observability artifacts, or debugging mwb debug contracts and phase failures.

Files · 1

View on GitHub

SKILL.md

1	# Mujoco Phase Contracts
2
3	Phase contracts are executable documentation for scripted scenes. They should
4	answer what must be true at phase starts, phase ends, and invariant samples.
5
6	Relevant modules:
7
8	- `mujoco_workbench.scene_base`: `TaskPhase`, `PhaseState`, `PhaseContract`, invariants.
9	- `mujoco_workbench.observability`: contract evaluation and artifacts.
10	- `mujoco_workbench.phase_monitor`: live runner enforcement.
11	- `mujoco_workbench.runtime`: batch timeline replay used by debug commands.
12
13	## Breaking Down Large Motions
14
15	Use phases to make placement explicit. A good phase should change one kind of
16	state at a time:
17
18	- Base-only movement: drive, yaw, translate, lift, or align the chassis while
19	arm joints stay static.
20	- Arm-only movement: approach, touch/grip, pull/insert, release, or retract
21	while base/lift joints stay static.
22	- Attachment state: activate/deactivate one semantic grasp, weld, connect, or
23	visual state change at an authored boundary.
24
25	For long or fragile motions, split into minute waypoints:
26
27	- `approach`: standoff point in free space, before contact.
28	- `at_target`: TCP/contact point on the surface.
29	- `hold_or_grip`: no pose change; only gripper/attachment state changes.
30	- `clearance`: back out along the same surface normal or lift direction.
31	- `transfer`: move base or lift while the object is held.
32	- `seat_or_release`: final surface/slot point, then deactivate the hold.
33
34	Derive these waypoints from layout geometry, not hand literals. Use:
35
36	```bash
37	uv run mwb debug surface-point ...
38	uv run mwb debug standoff ...
39	uv run mwb debug camera-look-at ...
40	```
41
42	Contract the boundary of each phase with outcome facts: base aux pose,
43	expected object pose, active/inactive attachments, static joint sets, held-object
44	levelness, and qacc sentinels. The indicator-check pattern is the model:
45	drive straight, yaw where the swept radius clears, translate into final click
46	pose, then move arms while the base is frozen.
47
48	Run all contracts:
49
50	```bash
51	uv run mwb debug contracts \
52	--scene examples.scenes.mobile_aloha_piper_indicator_check \
53	--out-root results/runs
54	```
55
56	Replay one phase:
57
58	```bash
59	uv run mwb debug phase wait_at_server \
60	--scene examples.scenes.mobile_aloha_piper_indicator_check \
61	--out-root results/runs
62	```
63
64	Render the phase graph:
65
66	```bash
67	uv run mwb debug phase-graph \
68	--scene examples.scenes.mobile_aloha_piper_indicator_check \
69	--out /tmp/phases.dot
70	```
71
72	Artifacts are plain files:
73
74	- `events.jsonl`
75	- `summary.json`
76	- `phase_contracts.json`
77	- `snapshots/*.npz`
78	- `renders/*.png`
79
80	When adding a new `Step` field that affects sim state, update both
81	`mujoco_workbench.runner` and `mujoco_workbench.runtime` so live behavior and
82	debug artifacts stay identical.
83
84	Do not make contracts assert implementation details. Assert outcomes: base pose,
85	attachment state, grippable pose, held-object invariants, static joints, gripper
86	state, or MuJoCo warning counts.

People who liked this also viewed

6 picks

Type