architect ยท diff
git:20260919.b945c8f to git:20260919.498ea4e
54 added, 29 removed. Audit A to A.
---
name: architect
- description: Start a robotics project or first demo from a proven example, or choose the stack and smallest useful slice for a new application. Not for routine fixes in an existing app.
+ description: Start robotics apps or demos from compatible examples for mapping/navigation, robot assistants, or pretrained manipulation. Choose a stack if none fits; not existing-app maintenance.
---
# Architect
- Get the closest proven example working before adapting it. When no compatible
- example fits, choose the smallest slice that can disprove the biggest assumption.
+ Reach a visible robot result with the least new work, then customize. Inspect
+ existing examples before researching or designing a new stack.
+ Without an established app, an outcome-only request such as mapping a simulated
+ environment or running a pretrained policy is a first-run request even without
+ "new project", a robot brand, or "architect" in the prompt. Use this skill
+ inline, not the optional heavy-research architect subagent. If a domain skill
+ brought you here, select the baseline once and return to that skill for its
+ mechanics; do not loop through architecture again for the same task.
+
## Start from the outcome
- Inspect the current repository, the Robium app registry, and the closest
working example before asking questions.
+ Start with candidate READMEs, manifests, and launchers; exclude generated
+ environments, caches, and model assets from discovery scans.
- 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.
+ - Honor the user's stated target platform and restrictions even when the agent
+ runs on a different host. Ask about a compatible alternative, not for them to
+ restate constraints they already gave.
- ## Bring up the baseline, then adapt
+ ## Offer the shortest useful starting path
+ After a quick registry and candidate check, surface these paths briefly, mark
+ the recommendation, and explain what would run first. Do this before broad
+ research, architecture documents, cloning, or lengthy setup. Do not turn the
+ four paths into a mandatory questionnaire: when intent is clear, explain and
+ proceed within it; ask one short question only for a consequential choice.
+
+ | Path | When it fits | First step |
+ | --- | --- | --- |
+ | Try an example | Close compatible match; user wants to see it work | Run it unchanged in the existing checkout; no new project. |
+ | Adapt an example | Close match; user wants their own customized app | Verify the baseline, then make a separate derivative and change one behavior. |
+ | Reuse selected pieces | Partial overlap; useful components fit the new app | Reuse the smallest compatible pieces and prove one integrated behavior. |
+ | Start fresh | No useful compatible overlap, or explicitly requested | Use the domain skills to scaffold only the smallest visible slice. |
+
+ For "just try it", default to the compatible example with the fewest new moving
+ parts, not the most ambitious stack. Describe prerequisites and first-run work,
+ not unmeasured speed promises. Read [reuse paths](references/reuse-paths.md)
+ only for adaptation, component reuse, or a fresh scaffold.
+
+ ## Inspect candidates and prove the selected slice
+
- Resolve the user's workspace with `npx robium-ai workspace --json`; its
`repo` and `apps` paths are authoritative, not a hardcoded `~/robium` or the
installed plugin cache. For workspace discovery and an occasional quiet
freshness check before a new example, read
[workspace updates](references/workspace-updates.md). Checking is not updating.
- Discover candidates in the [Robium app registry](https://github.com/robium-ai/robium-apps/blob/main/REGISTRY.md),
using a sibling checkout when available. Match the task, host architecture,
runtime requirements, and relevant verification evidence, not just the name
or a `stable` label. Read the selected app's README and launcher; distinguish
tested conditions from assumptions. For the homepage's three first-run tasks,
use [first-run examples](references/first-run-examples.md).
- For a clear compatible match, explain the choice and proceed within the
user's request: "This matches Robium's navigation example. I'll get it
running first, then we can adapt it." Ask only when different candidates or
an incompatible platform materially change the outcome. Honor an explicit
request to build from scratch. Routine maintenance stays in the owning skill.
- Use the existing checkout without resetting or pulling over user changes;
acquire a separate checkout when necessary. Record the source revision and
- any local changes. Run the baseline unchanged with its launcher, pinned
- environment, assets, and viewer; do not create a derivative, upgrade
+ any local changes. For whole-app reuse, run the baseline with its launcher,
+ pinned environment, assets, and viewer; do not create a derivative, upgrade
dependencies, or recreate infrastructure just to demonstrate it.
- Check prerequisites, credentials, and occupied ports before lengthy builds.
Explain first-run downloads and reuse caches on later starts. Missing model
access is a blocker, not permission to substitute a mock and call it live.
Keep secrets out of prompts/logs; explain API charges and obtain authorization
before paid calls. Do not provision cloud resources or move physical hardware
as an implicit part of onboarding.
- - Verify the requested visible behavior, not merely an open port. Use the
- app's smallest relevant checks and stop only processes started for this run.
+ - Check the requested behavior at a meaningful milestone, not after each edit.
+ Use the app's smallest relevant check, not a new suite or repeated UI tours.
+ A low-risk visual check may be handed to the user with exact steps and an
+ explicit unverified status; an open port is not proof the demo works.
+ Stop only processes started for this run.
If blocked, report the exact unmet prerequisite without inventing a new stack.
- After the baseline works, offer one small customization; create a derivative
- only when customization is requested. Keep a working baseline for comparison.
+ Before a port, dependency overhaul, or prolonged troubleshooting, surface
+ the blocker and a simpler compatible path; let the user choose the tradeoff.
+ For try-only requests, offer one small customization after it works. For
+ requested customization, proceed with the agreed change and keep the baseline.
## Choose only the stack the slice needs
- - Establish the environment early with `environments`.
- - For mobile navigation, route through `ros2`, `navigation`, `simulation`, and
+ - When environment setup is needed, use `environments` early.
+ - For ROS-based 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.
+ - Use `testing` when risk, uncertainty, or requested test work needs a verification
+ decision; do not automatically author tests. Use `test-assets` for needed fixtures.
- 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`.
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.
## Keep the decision record light
- - Write `docs/architecture-brief.md` for a new application or genuine
- re-architecture, not for running an existing example or every bounded change.
+ - Keep decisions inline for tryouts and tiny demos. Use
+ `docs/architecture-brief.md` when a new app or re-architecture benefits from
+ a durable record, never as a gate before an agreed first visible result.
- 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.
-
- ## Done
-
- - 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.