architect · diff

v2.2.0 to git:20260907.863840e

48 added, 190 removed. Audit A to A.

---

name: architect

- version: 2.2.0

- description: >

- Entry-point skill for shaping new robotics applications: lightweight

- brainstorming, project ideation, requirement/risk discovery, stack selection,

- comparing or choosing simulators/models/visualization, a first

- user-visible slice, and a concise architecture decision record. Use when:

- starting a new robotics app; 'brainstorm a robot app', 'build a robot app',

- 'which robotics stack', 'choose between simulators', 'decide the simulator,

- model, robot, and visualization', 'what robotics project can we build',

- 'cheapest useful demo', 'rethink the architecture', genuine re-architecture,

- 'scaffold a robotics project', 'mobile robot',

- 'robot arm', 'manipulation policy', 'navigation stack', 'let's do demo 1',

- or when requirements exist but the stack is unchosen. Load first for a new

- app, then route to domain skills. Excludes narrow maintenance work after stack

- selection and skill authoring (skill-author).

+ description: Shape a new robotics application around its smallest useful slice, stack, and decision record.

---

- # architect

- The entry point for a new Robium application. It combines a lean design

- conversation with robotics stack selection, chooses the cheapest meaningful

- proof, records decisions without freezing provisional assumptions, and routes

- implementation to the skills that own each layer.

- ## When to use this skill

- - Starting a new robotics application from a rough idea.

- - Choosing or reconsidering the stack, simulator, embodiment, environment,

- data path, visualization, or compute target.

- - Decomposing a multi-subsystem robotics idea into a first buildable slice.

- - Writing a durable decision record for a new app or genuine re-architecture.

- - Skip architect for a bounded change in an existing flow. Read the affected

- code and use the matching tool skill directly.

- ## Key directives

- - **Delegation posture: route + embed decision logic.** Architect owns the

- product/stack choices and routing. Tool mechanics stay in the skill that owns

- them.

- - **Brainstorm only where a real decision exists.**  Inspect the repository and

- `robium-apps` registry first. Ask only questions whose answers materially

- change the first slice. For a genuine choice, offer 2–3 approaches with

- trade-offs and recommend one. Never announce a process classification.

- - **One direction gate, then build.**  A new app or material architecture

- gets one rough direction approval. After that, proceed through implementation

- and verification; pause only for a material pivot, scope expansion, paid or

- publishing action, deployment, or safety concern.

- - **Prove the riskiest assumption cheaply.**  Before polishing infrastructure or

- scaling compute, run the smallest probe that can disprove the stack and

- deliver the first user-visible working slice. Label provisional choices and

- update them when evidence changes.

- - **Use a decision record, not a contract.**  Create or update

- `docs/architecture-brief.md` for a new application or genuine

- re-architecture. It records validated decisions, provisional assumptions,

- risks, and authorized pivots. Bounded feature/fix work does not require a new

- brief or approval cycle.

- - **Environment first, syntax verified.**  Route reproducibility to

- `environments` before substantial code. Verify volatile versions, commands,

- and platform constraints against current primary sources or installed CLI

- help when implementation reaches that decision. Record the combination that

- works; do not turn current recommendations into architecture pins unless the

- first slice actually depends on them.

- - **Lock outcomes, not implementation tactics.**  Decide the user-visible result, genuine constraints, and the next risk-reducing slice. Keep exact methods, versions, hardware SKUs, training parameters, metric thresholds, protocols, and deployment details provisional unless the user requires them, compatibility/safety/cost makes them necessary, or a cheap probe has validated that choice for the next slice. Verify and record what actually worked during implementation.

- ## Quick start

- 1. **Read before asking.** Inspect the app registry, closest reference app,

- current repository, and available hardware/compute facts.

- 2. **Frame the first outcome.** Establish robot/embodiment, user-visible task,

- sim-vs-real target, and the pass/fail signal for the first slice. Record a

- reasonable assumption instead of asking about low-impact details.

- 3. **Compare only meaningful alternatives.** Recommend one stack. If cost,

- hardware, or an unfamiliar integration is uncertain, define a cheap spike

- that resolves it before full implementation.

- 4. **Write the decision record when warranted.** Use

- `references/brief-template.md` for a new app or re-architecture. Keep the

- core concise; add optional detail only when the system needs it.

- 5. **Bootstrap, then diverge.** Check `REGISTRY.md` in the sibling

- [robium-apps](https://github.com/robium-ai/robium-apps) repository. Copy the

- closest app's environment, test, and launch shape when one exists; otherwise

- use `references/scaffold-patterns.md`.

- 6. **Build the first slice.** Hand each phase to the lowest owning skill and

- update the decision record only when a decision or risk actually changes.

- Use the Claude-only `robium-architect` agent only for an explicitly requested

- or genuinely ambiguous heavy comparison that would otherwise flood the main

- conversation. Normal new-app design stays in the main conversation.

- ## Decision guidance

- ### Choose the first vertical

- - **Navigation:** `ros2` + `nav2` + `simulation` → `gazebo`, then

- `visualization` → `rviz2` or `foxglove`. Use `environments` before bring-up.

- - **Learned manipulation:** `lerobot` + `data` + `huggingface`, with

- `simulation` selecting MuJoCo/Gazebo/Isaac as the task requires. Add

- `isaac-sim`/`isaac-lab` only after their NVIDIA GPU requirements are proven.

- - **Hybrid or unfamiliar stack:** define module boundaries with `integration`,

- identify the costliest uncertainty, and spike that boundary before building

- the whole system.

+ # Architect

- ### Route by build phase

+ Choose the smallest robotics application slice that can disprove the biggest

+ assumption.

- | Decision or work | Owning skill |

- |---|---|

- | Environment/reproducibility | `environments` |

- | Module boundaries, protocols, containers | `integration` |

- | ROS 2 substrate | `ros2` |

- | Mobile navigation/localization | `nav2` |

- | Simulator selection/sensor fidelity | `simulation` |

- | Modern ROS simulation | `gazebo` |

- | Lightweight non-ROS manipulation sim | `mujoco` |

- | NVIDIA photoreal simulation | `isaac-sim` |

- | NVIDIA RL/IL training | `isaac-lab` |

- | Manipulation policies/VLAs | `lerobot` |

- | Dataset sourcing/collection strategy | `data` |

- | Hub models, datasets, Jobs, Spaces | `huggingface` |

- | Visualization selection | `visualization` |

- | ROS desktop visualization | `rviz2` |

- | Remote/web ROS visualization | `foxglove` |

- | ML/data timelines | `rerun` |

- | Test strategy and smoke bar | `testing` |

- | Fixtures/worlds/datasets | `test-assets` |

- | Publish app overview, live surface, article voice, and media | `app-publishing` |

- | Public interactive demo | `live-demo` |

- | Cloud Run deployment mechanics | `cloud-run` |

- | RunPod GPU execution | `runpod` |

- | External example mining | `mining` |

- | Learning consolidation/absorption | `learning-loop` |

- | Skill authoring/quality | `skill-author` |

+ ## Start from the outcome

- ## Platform gotchas

+ - Inspect the current repository, the Robium app registry, and the closest

+ working example before asking questions.

+ - Define what the robot should visibly do, where it will run, and what evidence

+ would make the first slice credible.

+ - Ask only about choices that change that slice. When a real choice exists,

+ offer a few meaningful alternatives and recommend one.

+ - Treat versions, hardware, protocols, thresholds, and deployment details as

+ provisional until compatibility, cost, safety, or a quick probe makes them

+ consequential.

- - Isaac Sim/Lab require a supported NVIDIA RTX-class GPU and do not run on

- macOS. Load `isaac-sim` and verify its current floor before selecting it.

- - Native ROS 2/Gazebo development is Linux-centric. On macOS, choose a

- container or Linux remote through `environments`.

- - Headless remote work needs web/recorded visualization (`foxglove` or

- `rerun`) rather than assuming RViz2/display forwarding.

- - Cloud/GPU inventory, pricing, quotas, and framework versions are volatile.

- Verify them only when they affect the selected path; do not turn every design

- into a broad research pass.

+ ## Choose only the stack the slice needs

- ## Customization

+ - Establish the environment early with `environments`.

+ - For mobile navigation, route through `ros2`, `navigation`, `simulation`, and

+ the selected simulator and visualizer.

+ - For learned manipulation, route through `lerobot`, `data`, and

+ `huggingface`; add a simulator only when the first slice needs one.

+ - Use `integration` when module boundaries or cross-process communication are

+ themselves a design decision.

+ - Use `testing` to define the cheapest evidence for the slice, and

+ `test-assets` when its fixtures are not already available.

+ - Route provider mechanics to `cloud-run` or `runpod` only after deployment is

+ part of the approved slice. A public session layer belongs to `live-demo`;

+ publishing a finished app belongs to `app-publishing`.

- - Scale the decision record to the project. A small one-process demo may need

- only outcome, chosen stack, environment, pass bar, and risks. Add modules,

- communications, data, or rollout sections only when they contain decisions.

- - A discovered constraint may change a provisional choice without invalidating

- the whole design. Record the evidence and pivot; request another direction

- decision only when the user-visible outcome or material scope changes.

- - Decompose an idea with several independent products into ordered slices. Fully

- design only the first slice; record later slices as non-binding follow-ups.

+ When the stack is genuinely undecided, read

+ [stack-selection.md](references/stack-selection.md). Keep upstream project

+ documentation as the source of truth for supported versions and hardware.

- ## References

+ ## Keep the decision record light

- - `references/stack-selection.md`: simulator, middleware, and training decision

- trees; verify volatile defaults before use.

- - `references/scaffold-patterns.md`: starting layouts for navigation and

- manipulation applications.

- - `references/brief-template.md`: concise decision-record template with

- optional depth.

- - `examples/architecture-brief-example.md`: filled hypothetical brief (status:

- unverified).

- - Upstream: [ROS 2](https://docs.ros.org/), [Nav2](https://docs.nav2.org/),

- [Gazebo](https://gazebosim.org/docs/),

- [LeRobot](https://github.com/huggingface/lerobot),

- [Isaac Sim](https://docs.isaacsim.omniverse.nvidia.com/), and the MIT-licensed

- [Superpowers brainstorming skill](https://github.com/obra/superpowers), whose

- useful exploration/alternatives/YAGNI principles were adapted here without

- its global classification and repeated-approval gates.

+ - Write `docs/architecture-brief.md` for a new application or genuine

+ re-architecture, not for every bounded change.

+ - Record the outcome, chosen direction, provisional assumptions, risks, next

+ probe, and allowed pivots. It is a living decision record, not a contract.

+ - Read [brief-template.md](references/brief-template.md) only when creating or

+ revising that record. The

+ [filled example](examples/architecture-brief-example.md) is illustrative,

+ not a source of current compatibility facts.

+ - If no close app exists, read

+ [scaffold-patterns.md](references/scaffold-patterns.md) and prune the starting

+ shape to the first slice.

- ## Changelog

+ ## Done

- - 2.2.0 (2026-08-28): add outcomes-not-tactics (Key directives); update env-first-route-environments; annotate references/brief-template.md [reasons: obs-architect-002] (applied by apply_deltas)

- - 2.1.0 (2026-08-28): routing table gained app-publishing for the public app

- overview/live/article composition that follows a green application smoke;

- live-demo remains the hosted runtime lifecycle owner. Clarified two legacy

- trigger fixtures whose missing conversational context made project selection

- indistinguishable from downstream tool or publishing work.

- - 2.0.0 (2026-08-27): absorbed lightweight brainstorming into architect;

- replaced global classification/repeated approval with one direction gate;

- made the brief a scalable decision record; added risk-first/user-visible

- slicing; narrowed the heavy Claude architect agent; repointed bootstrapping

- to robium-apps.

- - 1.9.0 (2026-08-24): route RunPod inventory, provisioning, diagnostics,

- validation, billing, and cleanup to the new generic `runpod` skill.

- - 1.8.1 (2026-08-03): style pass; removed em dashes throughout.

- - 1.8.0 (2026-08-02): routing: learning-loop added; retired skill-updater.

- - 1.7.0 (2026-08-02): routing table gained mining; skill-author narrowed.

- - 1.6.1 (2026-08-01): anchor IDs added to claim-bearing items.

- - 1.6.0 (2026-08-01): routing table gained cloud-run.

- - 1.5.0 (2026-07-31): routed MuJoCo manipulation simulation.

- - 1.4.0 (2026-07-18): routing table gained test-assets.

- - 1.3.1 (2026-07-18): refreshed transferred repository links.

- - 1.3.0 (2026-07-15): added backlog kickoff triggers and prior brainstorming

- handoff.

- - 1.2.0 (2026-07-13): routing map gained live-demo.

- - 1.1.1 (2026-07-12): clarified dated provenance.

- - 1.1.0 (2026-07-12): made scaffolding bootstrap-first.

+ - The user-visible outcome and first proof are clear.

+ - The selected stack satisfies known platform, cost, and hardware constraints.

+ - High-risk assumptions have cheap probes and explicit fallback directions.

+ - Implementation can continue in the owning domain skills without another

+ architecture gate unless the outcome or material scope changes.