1.0.0

architect

The entry point to robium. Given a robotics application idea, this skill turns requirements into a concrete stack decision — middleware, simulation, data, visualization, and training frameworks — plus a scaffold plan and a written architecture brief. It is the only skill that knows the whole robium catalog; everything else is reached by routing from here. Load it first on any new robotics app, then hand off to the domain skills for the actual build.

When to use this skill

• Starting a brand-new robotics application from a rough idea ("build a mobile robot that navigates a warehouse", "train a manipulation policy on an arm").
• The requirements exist but the stack is unchosen, or half-chosen and you want a sanity check before committing.
• You need a durable, written architecture record the whole project builds from.
• You want the routing map: "which robium skill do I load for phase X?"
• Cross-references — go straight to the tool skill, skipping architect, when the stack is already chosen and the question is narrow:
  • Debugging or configuring an existing stack → the matching tool skill (nav2, ros2, gazebo, lerobot, …). "My costmap isn't updating" is a nav2 question, not an architect question.
  • Authoring or improving robium skills themselves → skill-author.
  • Deep-diving one decision (uv vs Docker, which visualizer) → the umbrella that owns it (environments, visualization); architect points you there.

Key directives

• Delegation posture: route + embed the decision logic. The decisions (which stack, why) live here; the how-to lives in the skill each decision routes to. Never duplicate a tool skill's content — link to it.
• Always produce or update docs/architecture-brief.md in the app repo. It is the living architecture contract — every later build step reads from it, and refinements edit it in place. No brief, not done. Use references/brief-template.md for its required sections.
• Virtual-environment-first. Reproducibility is decided before code: route the env question to the environments skill (uv/venv vs Docker) and record the choice in the brief. Do not let a project start with an ad-hoc setup.
• Never invent syntax or tools. Recommend only real, current tools at versions you have verified — robium ships curation, not a framework. When a version fact matters (ROS 2 distro, Gazebo pairing, GPU floor), confirm it against current docs (e.g. docs.ros.org for ROS 2 distro/EOL status) rather than memory. See references/stack-selection.md for the verified defaults this skill ships with.
• State open risks explicitly in the brief. Unverified assumptions (GPU availability, hardware you can't see, sim-to-real gaps) go in the brief's open-risks section, not silently into a decision.

Quick start

1. Collect the requirement checklist (ask for anything missing; if a critical item is still unknown, record the assumption in the brief rather than guessing silently):

• Robot type — mobile base, arm/manipulator, humanoid, drone, custom?
• Task — navigate, manipulate/grasp, inspect, learn a policy, teleop?
• Hardware — real robot (which?), sim only, or sim-first then real?
• Sim vs real — where does the MVP need to run?
• GPU — is an NVIDIA RTX GPU available? VRAM? (gates Isaac Sim / Lab.)
• Local vs remote — laptop, workstation, or headless remote server? (drives the visualization choice — remote favors foxglove.)

2. Pick a golden path. The two MVP verticals:

• Navigation (mobile robot, autonomous nav in sim): ros2 + nav2 + gazebo + visualization → ROS 2 Jazzy (LTS) middleware, Nav2 for the nav stack, Gazebo Harmonic as the paired simulator, an RViz2 or Foxglove view. Dockerized env via environments. This is the classic, well-supported path — favor it when the task is "get from A to B autonomously."

• Manipulation (arm, learned policy): lerobot (+ isaac-sim / isaac-lab if a capable GPU is available) + huggingface + data → LeRobot for policy training/eval (ACT, Diffusion, SmolVLA, π0), datasets and models sourced through the huggingface delegation, data for the sourcing strategy. Add isaac-sim/isaac-lab only when the GPU floor is met (see Platform gotchas); otherwise stay in LeRobot's own sim/eval tools and a CPU/uv env. Favor this when the task is "learn to grasp / manipulate."

3. Write the brief. Fill docs/architecture-brief.md from references/brief-template.md — chosen stack + reasoning, module breakdown, comms plan, env strategy, data plan, robium skills per phase, open risks.

4. Scaffold. Lay out the repo per references/scaffold-patterns.md (ROS 2 app layout or LeRobot app layout), then hand each phase to its skill.

For the heavy version of step 2 (a full stack-comparison research burst that keeps the noise out of the main conversation), launch the robium-architect subagent; it runs this skill as its playbook and writes the brief.

Decision guidance

The routing map. Architect is the only skill that sees the whole catalog; it hands each build phase to the skill below. Grouped by phase.

Design / architecture

Skill	Hand off when…
architect	You are here — requirements → stack → brief → scaffold, and routing to everything below.
integration	Module boundaries and comms are the question: topics/services vs zenoh/gRPC, Dockerfiles, compose wiring across nodes.
environments	Deciding reproducibility: uv/venv vs Docker, identical local/remote repro, GPU passthrough. Resolve this early, per the env-first directive.

Middleware & motion

Skill	Hand off when…
ros2	The app uses ROS 2 — core usage, packages, nodes, launch files, message/topic wiring. The substrate for the nav vertical.
nav2	Autonomous navigation for a mobile base — costmaps, planners, controllers, behavior trees, localization.

Simulation

Skill	Hand off when…
simulation	Choosing a simulator or getting sensor simulation right, before committing to a specific engine.
gazebo	Simulating a ROS 2 robot — the paired sim for the nav vertical (Gazebo Harmonic ↔ ROS 2 Jazzy).
isaac-sim	Photoreal / GPU-accelerated sim or synthetic data — only when the NVIDIA RTX GPU floor is met.
isaac-lab	GPU-parallel reinforcement-learning environments on top of Isaac Sim — same GPU gate.

Learning & data

Skill	Hand off when…
lerobot	Training or running a manipulation/imitation policy — the substrate for the manipulation vertical.
huggingface	Pulling datasets/models or pushing artifacts to the Hub — delegate to hf-cli@huggingface-skills; robium adds only the robotics glue.
data	Deciding where data comes from: offline datasets vs sim generation vs teleop collection.

Visualization

Skill	Hand off when…
visualization	Choosing a viz tool or applying viz best practices, before picking a specific one.
rviz2	Classic ROS 2 visualization on a local Linux machine with a display.
foxglove	Web-based viz — the go-to for a headless remote server or cross-platform team viewing.
rerun	Timeline/multimodal logging for ML and perception debugging (heavy pointer to Rerun's own docs).

Verification & meta

Skill	Hand off when…
testing	Standing up smoke tests, sim-based regression, or launch testing — plan this into the brief, don't bolt it on later.
skill-author	Editing robium's own skills (fresh authoring, mining, hardening from learnings). Not an app-building skill.
skill-updater	End-of-session absorption: folding this session's gotchas back into the robium skills. Not an app-building skill.

See references/stack-selection.md for the decision trees behind these hand-offs (middleware yes/no, simulator gazebo-vs-isaac, training framework).

Platform gotchas

• Isaac Sim / Isaac Lab are GPU-gated. Per NVIDIA's current requirements (docs.isaacsim.omniverse.nvidia.com), the floor is an RTX 4080 with 16 GB VRAM (minimum), an RTX 5080 or better recommended (16 GB+ VRAM), and 32 GB+ system RAM (64 GB recommended; Isaac Lab RL training wants more of both). Linux (Ubuntu) is the primary target; there is no macOS support. If the GPU floor isn't met, do not route to Isaac — keep the manipulation path in LeRobot's own sim/eval tooling. Verify the current floor in isaac-sim before committing; treat GPU availability as an open risk if unconfirmed.
• macOS / Apple Silicon cannot run the native ROS 2 + Gazebo desktop stack cleanly — plan for Docker (route to environments) or a Linux remote.
• Remote / headless servers have no display for RViz2 — default the viz choice to foxglove (web UI) in that case, and note it in the brief.
• ROS 2 distro choice: Lyrical Luth (LTS, GA 2026-05-22, supported to May 2031) is the current newest LTS — default new apps to it unless a dependency forces otherwise. Exception: the ROS 2 + Nav2 + Gazebo navigation vertical still defaults to Jazzy Jalisco (LTS, supported to May 2029) for now, because Nav2 has not yet shipped binary packages for Lyrical (tracked in ros-navigation/navigation2#6123 as of 2026-07) — re-check before picking Lyrical for that path. Kilted Kaiju is non-LTS and nearing its own EOL (~Dec 2026); don't pick it as a new default. Record the chosen distro in the brief.

Customization

• Different robot/task: re-run the requirement checklist and the decision trees in references/stack-selection.md. The two golden paths are starting points, not the only shapes — a drone-inspection app is still ROS 2 + a sim + viz, just with different nodes; a real-hardware manipulation app is LeRobot with the sim swapped for a hardware driver.
• Adapt the scaffold: references/scaffold-patterns.md gives a ROS 2 layout and a LeRobot layout; rename packages and prune directories your app doesn't need, but keep the docs/architecture-brief.md location fixed — tooling and every later phase expect it there.
• Adapt the brief: every section in references/brief-template.md is required, but its depth scales with the project — a one-robot sim demo needs a short comms plan; a multi-robot fleet needs a real one.

References

• references/stack-selection.md — the decision trees: middleware (ROS 2 yes/no), simulator (Gazebo vs Isaac), and training framework, with the verified version defaults this skill ships.
• references/scaffold-patterns.md — repo layouts for a ROS 2 app and a LeRobot app: directory trees plus what each directory holds.
• references/brief-template.md — the required sections of docs/architecture-brief.md (chosen stack + reasoning, module breakdown, comms plan, env strategy, data plan, robium skills per phase, open risks).
• examples/architecture-brief-example.md — a filled brief for a hypothetical diff-drive warehouse robot (status: unverified).
• Upstream: ROS 2 docs, Nav2 docs, Gazebo docs, LeRobot, Isaac Sim, Isaac Lab. The robium-architect subagent (agents/robium-architect.md) runs this skill as its playbook.

Changelog

<!-- One dated line per battle-tested change, added by skill-author hardening sessions. -->