Add pixi-workspace skill

[T-K-233]

Adds a skill capturing the pixi workspace interface protocol — now at rev 2 (2026-07-05), which dissolves rev 1's packaged hc CLI tier into workspace tasks — so any Claude session touching a pixi.toml, pixi task, or workspace script applies the conventions automatically.

skills/pixi-workspace/SKILL.md carries the operational rules: the two-level command model (lifecycle core + workspace tasks), the reserved scenario vocabulary incl. deploy-sim/deploy-real (one-command bring-up + policy; sim/real mean plant bring-up only, uniformly) and the at-most-one-qualifier rule (secondary parameters stay launch args), the utility one-liner tasks (ping-bus/scan-bus/profile-bus — pure aliases of their canonical ros2 run commands), the rarely-used-tools-get-no-task rule, the canonical cached setup task shape and guarded activate.sh, environment rules, and the empirically-verified gotchas. Registered in marketplace.json; matches the terse imperative style of robotics-conventions.

Rev 1 was implemented via humanoid_control#16, Lite-Deployment#1, Humanoid-Control-Website#13; the rev-2 migration ships as a second round of PRs alongside this one: humanoid_control#18 (CLI retired, deploy.launch.py added), Lite-Deployment#2 (deploy-sim/deploy-real + viz/calibrate), Humanoid-Control-Website#14 (two-level docs); the dev workspace and Lite-Specialist-Deployment manifests are adopted locally.

The full RFC (rev 2) follows below for traceability.

🤖 Generated with Claude Code

---

Pixi Workspace Interface Protocol

Title	Pixi Workspace Interface Protocol
Type	Process (convention)
Status	Ratified 2026-07-05 — rev 2 (see Status)
Created	2026-07-05
Revised	2026-07-05 — dissolved the hc CLI tier into workspace tasks
Applies to	All Berkeley Humanoids pixi workspaces (see Scope)

Abstract

This document defines how every Berkeley Humanoids pixi workspace exposes
its environment, tasks, and scripts. It establishes a two-level command
model:

1. a universal lifecycle core of five reserved pixi tasks
   (setup, build, test, clean, doctor), and
2. a workspace-task vocabulary — reserved scenario names
   (sim, real, policy, deploy-sim, deploy-real, viz,
   calibrate, …) whose semantics each workspace defines, plus free
   kebab-case utility tasks (ping-bus, profile-bus, …) that wrap
   canonical commands one-to-one.

It further specifies a one-command day-one ritual (pixi run build),
rules for authoring tasks, and an environment-activation protocol. The
goal is that anyone who has learned one workspace can operate any other,
and that the canonical ROS 2 commands keep working verbatim underneath.

Revision note (rev 2). The first draft had a third level: a
packaged hc CLI carrying "invariant-meaning" verbs (hc bus ping,
hc viz, …). Review judged the dispatcher not worth the indirection —
it needed a PATH-shim install mechanism, a scope-policing litmus test,
and a deferred extension mechanism, all to avoid re-declaring a
handful of one-line tasks. The tier is dissolved: its verbs are now
ordinary workspace tasks (§4.2), and the drift
risk it addressed is handled by requiring utility tasks to be one-line
wrappers over canonical commands, copied from the docs reference
block.

Status

Rev 1 was ratified and implemented 2026-07-05 (humanoid_control#16,
Lite-Deployment#1, Humanoid-Control-Website#13). Rev 2 — this text —
is ratified; its migration is being executed via a second round of
PRs. The durable normative text lives in AGENTS.md → "Environment,
tooling & version control", and the public walkthrough in the docs
site (Humanoid-Control-Website). This file is the review copy; the
migration plan in
Appendix A is transitional
and will be dropped once executed.

Scope

This protocol governs:

• humanoid_control_ws — the development workspace,
• the *-Deployment repositories — operator workspaces,
• the humanoid_control repo-root buildfarm manifest — packaging
  (a maintainer-CI surface, partially exempt; see
  Lifecycle tasks).

There is no official pixi task style guide beyond this document; it sets
convention rather than follows one. Its choices were informed by the
official pixi/RoboStack guidance, a survey of ~15 real pixi + ROS 2
projects (ros2/ros2, NVIDIA IsaacSim, NASA-JSC, ros-controls, bit-bots,
RobotecAI, rerun, …), and the uv ecosystem's day-one conventions. Key
findings from that survey are cited inline as rationale.

Throughout, must, must not, should, and may are used in
the RFC 2119 sense.

Audiences and design goals

Three audiences must find the interface natural:

• uv-native Python developers expect the ritual uv sync →
  uv run <thing> and one runner verb for everything. Pixi maps 1:1:
  pixi install → pixi run.
• ROS-native developers expect colcon build,
  ros2 launch pkg file.launch.py, key:=value launch arguments, and a
  sourced overlay. All of that must keep working verbatim inside
  pixi shell / pixi run --; tasks are shortcuts over canonical
  commands, never a replacement layer.
• Robot operators need a short, memorable, self-documenting menu:
  one health check, one command per everyday scenario.

When to deviate

Reserved names carry the weight of this protocol: a reserved name
must not be repurposed, and its reserved semantics must not be
altered. Beyond that, the protocol is deliberately thin:

• Workspaces may add archetype-local tasks (see
  §3.1) provided each carries a
  description and is never required of other workspaces.
• The canonical ros2 / colcon commands are part of the interface
  (see §7.5); when no task fits, documenting the
  canonical command is preferred over inventing a task.
• If following a rule would clearly make a specific workspace worse,
  deviate — and record why in the task description or workspace README
  so the deviation reads as a decision, not an accident.

1. The two command levels

Every command a user types belongs to exactly one level:

Level	Commands	Mechanism	Defined by	Scope
1. Pixi-ROS lifecycle	setup build test clean doctor	pixi tasks; names and semantics reserved by this protocol	each workspace's pixi.toml (re-declared — pixi tasks cannot ship with a dependency)	any pixi-ROS repo — ours match the ecosystem's de-facto canon
2. Workspace tasks	scenario vocabulary (sim real policy deploy-* viz calibrate + qualifiers), utility tasks (ping-bus, profile-bus, teleop, …)	pixi tasks; scenario/utility names reserved where listed, semantics workspace-defined	that workspace's pixi.toml only	that workspace

1.1 Why no packaged CLI tier

Pixi offers no mechanism for tasks that travel with a dependency —
[tasks] are strictly workspace-manifest-level — so a command either
lives in each workspace's manifest or ships as a packaged executable.
The first draft packaged the invariant-meaning commands into an hc
dispatcher. In practice the cost side dominated: the dispatcher needed a
bin/-shim install mechanism (ament_python puts console scripts in
lib/<pkg>/, off PATH), a litmus test to police its scope, and a
deferred ament-index extension mechanism — while the benefit was
avoiding a few one-line task declarations per workspace, in scenario
tiers that barely overlap anyway.

Rev 2 therefore keeps everything a pixi task and neutralizes the drift
risk (the original motivation — two broken aliases in the dev workspace)
by rule instead of by packaging:

• a utility task must be a one-line wrapper over the canonical
  ros2 run / ros2 launch command (§4.2) — there is nothing to
  drift but the one line;
• the docs site keeps a copy-paste reference block of the reserved and
  utility tasks for new/consumer workspaces (A.5).

2. The day-one ritual

Day one, in every developer-facing workspace, must be one command:

pixi run build     # auto-installs the env, fetches sources, colcon-builds
pixi run doctor    # (recommended) verify; prints what to fix if unhealthy

2.1 How it collapses to one command

• pixi run self-heals the environment (installs from the lockfile if
  needed). pixi install remains an optional explicit step, kept in
  the docs for uv users who expect a sync verb.

• setup must be safe to chain from build, achieved by two
  mechanisms together (both verified empirically):

  • vcs import --skip-existing — exits 0 on re-run, and unlike
    plain vcs import it never resets a locally-checked-out branch in
    a third-party repo back to its pin.

  • pixi inputs/outputs caching — because --skip-existing
    alone still fetches every remote (and exits 1 offline; a bare
    chain would put the network in front of every build and make an
    offline robot unable to rebuild):

    [tasks.setup]
    cmd = "vcs import src --skip-existing --input humanoid_control.repos && touch build/.setup-stamp"
    inputs = ["humanoid_control.repos"]
    outputs = ["build/.setup-stamp"]

    Verified semantics: cache hit (no network) when nothing changed;
    re-runs on a .repos edit; re-runs after clean or on a fresh
    clone (the stamp lives under build/).

  Caveat (must be documented on the task): --skip-existing never
  moves an existing checkout to a new pin — after a .repos pin bump,
  delete that repo directory and re-run setup. This is no worse than
  the pre-protocol behavior.

2.2 Nothing else auto-builds

The chain stops at build → setup by design. No scenario or utility
task may ever auto-build — hardware bringups must not trigger
surprise rebuilds. doctor is the staleness/health check instead, and
colcon owns build incrementality.

2.3 The doctor check

doctor must check: workspace root, environment active, overlay
built and sourced, /opt/ros contamination (fail hard),
ROS_DOMAIN_ID, source tree present, key packages visible. Fixable
findings are warnings; fatal findings exit non-zero.

3. Level 1 — lifecycle tasks

These five names are the only fully reserved names — reserved in
both name and semantics. Every developer-facing workspace must
provide them (with the test exception noted):

Task	Meaning
setup	fetch/prepare sources beyond pixi itself; idempotent; chained by build
build	build the workspace default lane (depends on setup)
test	run the workspace's tests (omit only if a workspace truly has none)
clean	wipe build/ install/ log/; never touches src/ or .pixi/
doctor	workspace health check (§2.3)

Rationale. The de-facto standard task core across every credible
surveyed project is build / test / clean — kebab-case, flat;
nobody namespaces. Workspace-type repos keep tasks to lifecycle only;
demo/deployment repos add scenario tasks. prefix.dev's only official
task-set prose adds lint and a check aggregate, which this protocol
treats as archetype-local (§3.1) rather than universal.

3.1 Archetype-local extras

Allowed, described, never required of other workspaces:

• Dev workspace: build-all (include the EtherCAT/Prime lane),
  test-result (singular, matching the colcon verb), lint (the
  .githooks ament linter set), check (test + lint pure alias;
  the local pre-push gate — its description notes local linter versions
  ≠ CI), gen-dds, test-dds.
• Buildfarm (maintainer CI, exempt from the developer core):
  setup (aggregating hidden _import + _overlay), package
  (build .conda artifacts — deliberately not build, ending the
  collision with the colcon verb), publish.

Convenience variants that duplicate an existing mechanism must not
be added. Deleted at migration: build-pkg (equivalent to
pixi run build --packages-select <pkg> via trailing-argument
forwarding), test-lint, test-results, launch-policy-tracking.

4. Level 2 — workspace tasks

4.1 Scenario vocabulary and grammar

Scenario tasks follow <scenario>[-<qualifier>], kebab-case, with
at most one qualifier. The reserved scenario words below must
be used by every workspace that has the concept; launch-* prefixes
must not be used:

Scenario	Meaning (stack scope is workspace-defined)
sim	bring up this workspace's primary stack in simulation — environment only, no policy
real	same, on hardware (hardware_config:=, calibration_file:=)
policy	prepare + load the RL policy against an already-running stack (wandb_run_path:= / checkpoint_file:=)
deploy-sim	one-command sim2sim deployment = sim bringup + policy in one
deploy-real	one-command real deployment = hardware bringup + policy in one (hardware_config:=, calibration_file:=)
viz	live state viewer of a running robot (viewer:=viser default; viewer:=rerun, viewer:=rviz)
calibrate	run the calibration procedure; writes calibration.yaml

sim / real mean plant bringup only — uniformly, in every
workspace (rev 2 change: the first draft let deployment workspaces
overload sim/real as the full stack). The deploy-* pair is the
full pipeline. A workspace where a plant-only bringup is not meaningful
may declare only the deploy-* pair. Because sim and policy
are both blocking launches, deploy-* must wrap a combined launch
file — two blocking tasks cannot be chained with depends-on.

The unqualified name is the workspace's default target; the suffix
selects the primary task variant only. Every secondary parameter
(robot, backend, checkpoint, scene, …) must remain a ROS launch
argument, forwarded verbatim — task names must never stack qualifiers.
With a robot × task × backend × policy matrix:

pixi run sim-piano robot:=prime policy:=latest    # right
pixi run sim-prime-piano-latest                   # wrong — name explosion

Which axis is "primary" is the workspace's call (in the dev workspace
today it is the robot or scene: -prime, -piano; for deploy it is
the target: -sim, -real); everything else rides the launch-argument
surface, which is exactly what ros2 launch users expect and what §6
forwarding preserves. The task description must state the scope
and the main launch arguments.

Examples — dev workspace: sim, real, sim-prime, real-prime,
sim-piano, policy, policy-piano, deploy-sim, deploy-real
(unqualified = Lite). Lite-Deployment: sim is the plant bringup,
deploy-sim / deploy-real run the full reach-task pipeline, plus
teleop for its repo-local gamepad script.

Names outside the reserved vocabulary may be used for concepts the
vocabulary doesn't cover (teleop), in free kebab-case.

4.2 Utility tasks

Diagnostics and small tools are ordinary workspace tasks in free
kebab-case, verb-first where natural. Each must be a one-line
wrapper over the canonical ros2 run / ros2 launch command — the
task is an alias, never a place where behavior lives — and must
carry a description. The current set:

Task	Meaning
ping-bus	single-actuator GetDeviceId ping — no Enable, safe on a powered robot
scan-bus	scan a CAN bus for Robstride device ids (read-only)
profile-bus	link probe: RTT/jitter (inert) or +lumped delay (PRBS torque)

Only workspaces whose robots have the underlying hardware/tooling
declare them; the docs reference block (A.5) is the copy source, which
keeps the one-liners from drifting apart across workspaces.

Rarely-used companions deliberately get no task (§5 rule 4): the
profile-bus report/plot generator, the static URDF inspector
(view_lite.launch.py), and the MIT-mode slider GUI are documented in
their canonical ros2 run/launch forms instead.

4.3 Size cap

The workspace-task tier should stay under roughly a screenful. A
launch file gets a task only if it is an everyday entry point;
everything else is documented in canonical ros2 launch form, which
always works (§7.5).

5. Choosing where a new entry point goes

Apply the first rule that matches:

1. Operates on the workspace (fetch, build, verify) → lifecycle
   task, universal names only.
2. Everyday robot scenario or utility → workspace task, using the
   §4.1 reserved vocabulary where it applies (sim, real, policy,
   deploy-*, viz, calibrate), free kebab-case otherwise
   (teleop, ping-bus).
3. Needs root or mutates host state (CAN buses, kernel) →
   scripts/*.sh, run explicitly with sudo, never a task.
4. Rarely used → nothing; document the canonical ros2 … command.

6. Task authoring rules

6.1 Every public task has a description

pixi task list is the workspace menu. A task without a description
is invisible to onboarding.

# Correct:
sim = { cmd = "ros2 launch <pkg> <file>.launch.py", description = "Bring up the Lite stack in MuJoCo" }

# Wrong: no description — invisible in `pixi task list`
sim = "ros2 launch <pkg> <file>.launch.py"

Plumbing tasks are prefixed with _ (hidden from the menu).

6.2 Launch-wrapping tasks are arg-less strings

Trailing key:=value arguments must forward verbatim:

pixi run sim enable_gamepad:=false
pixi run deploy-real wandb_run_path:=…

Typed pixi args (defaults/choices) are reserved for non-launch tasks
where they collapse variants; they must not appear on tasks whose
users pass launch arguments.

6.3 Chaining and caching

• build chains setup (idempotent, §2.1); nothing else
  auto-chains.
• No pixi inputs caching on build — colcon owns incrementality.

6.4 Task strings are legible

The task string shows the canonical command it wraps; non-obvious flags
get a why-first comment above the task. Style flags belong in
COLCON_DEFAULTS_FILE, not the task string (§7.3).

6.5 Forbidden names

• No install or shell — they shadow pixi's own verbs.
• No run or start — pixi run run reads badly, and the
  scenario vocabulary already names what starts.
• No launch-* prefixes — the scenario vocabulary replaces them.
  (deploy-* was banned in the first draft; rev 2 reserves it instead
  — see §4.1.)
• No colon namespacing (build:all).
• No same-name tasks in multiple environments — the interactive
  picker breaks CI.

# Correct:   setup  build  sim  sim-prime  deploy-real  teleop  ping-bus  _import
# Wrong:     install  shell  run  start  build:all  launch-mujoco

7. Environment and activation protocol

7.1 Overlay sourcing

Every colcon workspace must source its overlay through a guarded
activation script (NASA-JSC pattern):

[activation]
scripts = ["scripts/activate.sh"]

# scripts/activate.sh — sourced by pixi on every run/shell
if [ -f "$PIXI_PROJECT_ROOT/install/setup.sh" ]; then
  . "$PIXI_PROJECT_ROOT/install/setup.sh"
fi

POSIX setup.sh, not setup.bash. The guard makes the first,
pre-build activation a no-op instead of an error.

7.2 [activation.env] carries the workspace identity

• Deployment workspaces pin their robot's ROS_DOMAIN_ID (Lite = 5 per
  the lab guide; Lite-Specialist = 6). The dev workspace leaves it
  unpinned, and doctor prints it.
• RCUTILS_COLORIZED_OUTPUT=1 and the standard
  RCUTILS_CONSOLE_OUTPUT_FORMAT go in every workspace.

7.3 Colcon flags

Style flags move to COLCON_DEFAULTS_FILE
(config/colcon-defaults.yaml: --symlink-install, compile-commands
export) so plain colcon build inside pixi shell behaves exactly
like pixi run build. Semantic selection flags
(--packages-skip-regex, --packages-up-to) stay visible in the task
string — policy, not preference.

7.4 Channels and environments

• Channel order: https://prefix.dev/robostack-jazzy before
  https://prefix.dev/conda-forge, full URLs. Binary-consumer
  manifests put https://prefix.dev/berkeley-humanoids first.
• Single default environment. Adopt features/environments only when
  dependencies genuinely diverge (the same criterion as the Tier-2 rule
  in AGENTS.md).

7.5 Escape hatches

Escape hatches are part of the interface and must be documented in
every README:

• pixi shell — all ros2/colcon commands work verbatim,
• pixi run -- <any command>,
• the canonical ros2 launch forms for anything without a task.

7.6 The scripts/ directory

scripts/ at the workspace root holds host-side helpers that can't run
inside the environment or as tasks: activate.sh, canup.sh (sudo),
doctor.sh.

---

Appendix A — Migration map (non-normative)

Transitional; describes how the repos move from the implemented
rev 1 state (landed via humanoid_control#16, Lite-Deployment#1,
Humanoid-Control-Website#13, and the local humanoid_control_ws
manifest) to rev 2. Delete once executed.

A.1 humanoid_control_cli (retire)

Rev 1 shipped the hc dispatcher with a bin/ shim
(data_files('bin', …); colcon emits the path.sh hook) so it is on
PATH in any activated environment. Rev 2 retires it: the verbs are
pure execvp dispatchers — the wrapped executables live in their
owning packages — so retirement means deleting the package (and its
buildfarm manifest entry) once the A.2 workspace tasks cover its
surface. The _DISPATCH checklist comment in cli.py (hc-verb
changes must update usage/tests/skill/docs) retires with it; the same
duty moves to the utility-task tables (A.5 reference block and the
pixi-workspace skill).

A.2 humanoid_control_ws/pixi.toml (19 tasks → 25)

Current (rev 1)	New	Note
setup build build-all test test-result lint check clean doctor gen-dds test-dds	unchanged	doctor drops its hc-on-PATH check
sim real sim-prime real-prime sim-piano policy policy-piano	unchanged	semantics here were already plant-bringup / policy-attach
hc	deleted	CLI retired (A.1)
—	deploy-sim, deploy-real	new; each wraps a combined bringup+policy launch file (§4.1) — new launch files in humanoid_bringup_lite
—	viz, calibrate	one-line wrappers over the commands hc viz / hc calibrate dispatched to
—	ping-bus, scan-bus, profile-bus	one-line wrappers over the commands hc bus ping|discover|probe dispatched to (discover renamed scan, probe renamed profile)
hc bus probe-report, hc viz urdf, hc motor slider	no task	rarely-used rule (§5 rule 4): documented canonical ros2 run/launch forms

Final dev-ws task list: setup build build-all test test-result lint check clean doctor gen-dds test-dds sim real sim-prime real-prime sim-piano policy policy-piano deploy-sim deploy-real viz calibrate ping-bus scan-bus profile-bus.

A.3 Lite-Deployment/pixi.toml (7 tasks → 9)

Rev 1 gave this workspace setup build clean doctor sim real teleop,
with sim/real as the full reach-task pipeline. Under the uniform
rev 2 semantics:

Current (rev 1)	New	Note
setup build clean doctor teleop	unchanged	build drops humanoid_control_cli from --packages-up-to; doctor drops its hc check
sim / real	deploy-sim / deploy-real	already bringup + policy in one (task_reach.launch.py backend:=…)
—	viz, calibrate	one-line wrappers over humanoid_bringup_lite's launches (replace hc viz / hc calibrate, both part of this workspace's operator flow)
—	(optional) sim, policy	add when a plant-only composition exists; until then document the canonical ros2 launch forms (§7.5)

Lite-Specialist-Deployment (pre-protocol, local-only) adopts
directly: launch-mujoco/launch-real/launch-grippers →
sim/real/real-grippers (plant-only semantics are already correct
there — no policy exists yet; deploy-* lands with the first one),
dxl-scan → scan-bus (the Dynamixel bus), plus clean, the
stamp-cached setup, the build→setup chain, and
config/colcon-defaults.yaml. Its backends:= stays a launch arg;
ROS_DOMAIN_ID stays 6.

A.4 humanoid_control repo-root buildfarm manifest

Migrated at rev 1 (_import/_overlay aggregated by setup,
package, publish; CI workflow updated in the same PR). No rev 2
changes beyond dropping the humanoid_control_cli package when A.1
lands.

A.5 Documentation

• Humanoid-Control-Website PR #13 (the rev 1 three-level rewrite of
  how_to/use_pixi_tasks.md) must be reworked to the two-level model
  before merge; its reference block becomes the anti-drift copy source
  for the scenario + utility tasks (§4.2).
• AGENTS.md → "Command interface": update to two levels; refresh the
  decision-log rows (Appendix B).
• pixi-workspace skill (Berkeley-Humanoids/Skills): updated alongside
  this revision.

Appendix B — Decision log entries (for AGENTS.md)

Choice	Picked	Why (vs the alternative)
Command levels	L1 lifecycle tasks (reserved names+semantics) / L2 workspace tasks (reserved scenario names, local semantics; free kebab-case utilities)	everything stays a pixi task — one mechanism, one menu (pixi task list); scenario tiers barely overlap across workspaces so re-declaration is nominal. vs the first draft's packaged hc CLI tier (dispatcher needed a PATH-shim mechanism, scope policing, and an extension mechanism to avoid a few one-line tasks) or convention-only with no reserved names (per-tool alias sprawl).
Utility-task drift control	utility tasks are one-line wrappers over canonical ros2 run/launch commands, copied from a docs reference block	behavior lives in the packaged executables, tasks are pure aliases — nothing to drift but one line (the failure mode that motivated the CLI: two aliases were broken in the dev ws).
Universal task core	setup build test clean doctor only	matches the ecosystem's de-facto canon; everything else is archetype-local. vs an 11-verb reserved set (over-standardized).
Combined deployment task	deploy-sim / deploy-real reserved = bringup + policy in one; sim/real uniformly = plant bringup only	one memorable command for operators; uniform sim/real semantics across workspaces (first draft overloaded them per-workspace). Lifts the first draft's deploy-* ban — safe once launch-* aliases are gone and deploy has reserved semantics.
Day-one ritual	one command: pixi run build (env auto-installs; chained setup is --skip-existing + stamp-cached on the .repos file)	uv-like self-healing; fewer steps to memorize; cache keeps the network out of daily/offline builds (a bare chain would fetch every remote per build and fail offline — verified). vs install→setup→build→doctor sequence.
Build freshness	build→setup chain only; scenario and utility tasks never auto-build; doctor for health	colcon owns incrementality; no surprise rebuilds before hardware bringup.
Overlay activation	guarded scripts/activate.sh sourcing install/setup.sh	explicit first-build handling, POSIX, matches NASA-JSC/ros-controls.
Colcon flags	style flags in config/colcon-defaults.yaml, selection flags in task strings	manual colcon build == pixi run build; policy stays visible.
Buildfarm verb	package (not build*)	packaging ≠ compiling; ends the build-all double meaning.