git:20260626.b9ccff2 to git:20260626.e56711f

- # Roboclaws

-

- Household robot demo routes with MCP tools, reusable skills, and SDK/direct

- runtimes. Python 3.12+.

-

- `AGENTS.md` is the canonical repo playbook. This file is a Claude-specific

- overlay; when the two conflict, follow `AGENTS.md`.

-

- ## Required reading

-

- Before running commands or writing code, read only the orientation set in order:

- 1. `README.md` (project orientation, what you can run, mode discovery)

- 2. `ARCHITECTURE.md` (code map, four operating modes, MCP contract)

- 3. `STATUS.md` (human-facing current focus, next action, and source links)

- 4. `AGENTS.md` (canonical operating playbook, cloud-vs-local split, dual-stack workflow)

- 5. `CLAUDE.md` (this file)

-

- Then follow the links in `STATUS.md` only as needed:

-

- - Read `.planning/STATE.md` and the current `.planning/phases/*` plan when

- resuming or executing a GSD phase.

- - Read `docs/plans/<slug>.md` when shaping, reviewing, or handing off a

- pre-GSD plan.

- - Read `docs/human/technical-design.md` when design rationale or scenario specs are

- needed.

- - Read `docs/human/domain.md` when domain vocabulary matters.

- - Read `TODOS.md` or `THOUGHTS.md` only when asked about parked work or future

- ideas.

-

- Root `PLAN.md` is a legacy compatibility pointer, not an active plan. Shipped

- phase history lives under `docs/retrospectives/` and is not required reading.

-

- ## Build & test

-

- Use the repo-local `.venv/` as the canonical Python environment. It is managed

- by `uv` from `pyproject.toml` / `uv.lock`, and demos should not rely on hidden

- external virtualenvs under `/tmp` or another repo. The `dev` extra includes the

- standard MolmoSpaces/MuJoCo CPU runtime. If a demo needs another optional

- dependency group, add or use a declared `pyproject.toml` extra and install it

- into this checkout's `.venv/`.

- Use `uv sync` for declared project environments and `uv pip install` only for

- explicit local one-off installs. Do not use plain `pip install` for repo setup.

-

- For git worktrees, keep a separate `.venv/` at each worktree root. That keeps

- branch-specific dependency changes isolated while preserving the same

- uv-managed workflow everywhere.

-

- ```bash

- uv sync --extra dev

- ruff check .

- ruff format --check .

- pytest

- ```

-

- Isaac Lab remains intentionally isolated in `.venv-isaaclab/`; use the Isaac

- preflight harness when testing that backend.

-

- Run current public demos through the launch catalog:

-

- ```bash

- just run::surface surface=household-world agent_engine=direct-runner preset=map-build evidence_lane=camera-grounded-labels camera_labeler=grounding-dino

- just run::surface surface=household-world agent_engine=openai-agents-sdk preset=cleanup evidence_lane=world-public-labels

- just run::surface surface=household-world agent_engine=openai-agents-sdk prompt="find something useful to drink"

- ```

-

- Common `just` recipes use the small public facade:

-

- ```bash

- just run::surface surface=household-world agent_engine=direct-runner preset=map-build evidence_lane=camera-grounded-labels camera_labeler=grounding-dino

- just run::surface surface=household-world agent_engine=openai-agents-sdk preset=cleanup evidence_lane=world-public-labels

- just run::surface surface=planner-proof agent_engine=direct-runner intent=planner-proof mode=dry-run

- just agent::verify mock # maintainer confidence gate

- ```

-

- Work-network restriction: if `just dev::network-status` reports `network: work`

- (the probe can reach `https://api-router.evad.mioffice.cn/`), do not run

- OpenClaw workflows. Guarded recipes include OpenClaw Gateway recipes,

- `just chat::run`, and OpenClaw local/integration verification gates.

- System-provider Claude Code is also blocked on the work

- network. The current active live product route is `agent_engine=openai-agents-sdk`.

- It defaults to `provider_profile=codex-router-responses` and may run there when

- `CODEX_BASE_URL` and `CODEX_API_KEY` are configured. The mimo-mify-responses

- and MiniMax SDK routes are available only with explicit

- `ROBOCLAWS_PROVIDER_PROFILE=mimo-mify-responses|minimax-responses` and `XM_LLM_API_KEY` or `MM_API_KEY`.

- Model-only overrides do not bypass the guard.

-

- Live-agent runtime contract: run current live demos through

- `agent_engine=openai-agents-sdk`. `codex-cli` and `claude-code` are retired from

- active product launch; do not add new public recipes, operator-console rows, or

- eval rows for those engines. The pinned Docker-backed coding-agent runtime may

- remain for explicit manual debugging only when the human asks for it.

- Bare host `codex` or `claude` launches are unsupported unless the human

- explicitly asks for a system-CLI debugging run.

-

- See [`docs/human/contributing.md`](docs/human/contributing.md#dev-tooling-uv-and-just)

- for the one-line `just` install + tab completion. See [`just/README.md`](just/README.md)

- for the launch-axis grammar and prompt mappings.

-

- ## Code style

-

- - Ruff enforces style — do not duplicate linter rules here

- - Line length: 100

- - Target: Python 3.12

- - Type annotations on public APIs; `from __future__ import annotations` in all modules

-

- ## Architecture

-

- See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the code map. Current household

- product contracts use `surface=household-world` plus an open-task `prompt=...`

- or `preset=map-build|cleanup`. The planner proof route is

- `surface=planner-proof intent=planner-proof`.

-

- Map guidance:

- - Base Metric Map is the start-of-run map contract.

- - Runtime Metric Map owns semantic evidence produced during map-build and

- observations.

- - `smoke` is a verification preset/private runner mode, not an evidence lane.

- - Open-ended household runs omit `preset=` publicly and lower internally to

- `task_intent=open-ended`, not cleanup-specific custom mode language.

-

- ## Git workflow

-

- - Branch from `main`

- - Commit messages: `type: description` (feat, fix, ci, docs, refactor)

- - PR strategy: push fixes to the PR's source branch, don't open a new PR

-

- ## Cloud vs local development

-

- This project uses a two-topology dev setup — see `AGENTS.md §7` for the full spec. Short version:

-

- - **Cloud sessions** (this Claude Code web session): research, small bounded changes, CI/doc edits, anything validated by `lint-and-mock`. No API keys, no Unity, no GPU in the sandbox.

- - **Local sessions** (user's workstation): real provider keys, simulator/GPU

- resources when needed, and backend-specific services. Owns every task tagged

- `local-dev` on the issue tracker, plus any multi-round debug loop.

-

- Rule of thumb: if a PR's core claim depends on real hardware or real VLM behavior, the first validation happens **locally**. CI is where that proof stays continuously live, not where it starts. In a cloud session, if you can't actually run the thing, say so explicitly in the PR — don't paper over it with "CI will tell us". File a `local-dev` issue (see #50 for template) and hand off.

-

- **If the session IS local** (you have `docker`, real provider keys, and the

- needed simulator/backend available): the cloud -> local handoff protocol does

- not apply. Run the real thing yourself, iterate, and report what you observed.

- No need to file a `local-dev` issue or split bounded changes away from

- real-backend probes; a local session owns both. The cloud/local split exists to

- stop cloud sessions from papering over missing validation; it does not

- constrain a local session from carrying a full phase end-to-end.

-

- ### Local preflight ritual

-

- Local preflight steps (key loading, Docker hygiene, ROS env stripping for

- pytest) live in `AGENTS.md` §1. For the OpenClaw Gateway path specifically,

- see `docs/human/openclaw/local.md`.

-

- For local browser QA with gstack `browse` / Playwright, follow

- `AGENTS.md` §1.1.3: if Chromium fails with `No usable sandbox!` on Ubuntu

- 24.04/AppArmor hosts, run browse commands with

- `GSTACK_CHROMIUM_NO_SANDBOX=1` instead of changing system AppArmor or sysctl

- settings.

-

- ## Design principles

-

- | Principle | Practice |

- |-----------|----------|

- | **Thin & focused** | Not a heavy framework; give a good model enough context and it runs |

- | **Make it work first** | Day 1-2: simplest pipeline to validate core hypothesis. Day 3+: add OpenClaw |

- | **Visualization first** | Every feature must produce visible output (screenshots/GIFs/video) |

-

- ### Legacy support policy

-

- This repo has no backward-compatibility burden for obsolete demo surfaces. Code,

- docs, tests, skills, or recipes labeled `legacy`, `current-contract`, or kept

- only for compatibility are removal or replacement candidates, not APIs to

- preserve.

-

- Prefer the current docs and active profile contracts over preserving old paths.

- If a legacy surface conflicts with a cleaner current design, update or delete

- the legacy surface and its tests/docs in the same scoped change. Preserve a

- legacy path only when the user explicitly asks for it or when it is still the

- sole working route for the requested demo.

-

- ## Gotchas

-

- - Use `./scripts/dev/run_pytest_standalone.sh` on hosts where ROS site-packages

- leak into pytest.

- - Check `just dev::network-status` before OpenClaw or system-provider Claude

- workflows.

- - Keep Isaac Lab in `.venv-isaaclab/`; do not mix it into the normal `.venv/`.

- - Treat historical AI2-THOR/direct-VLM docs and reports as archived evidence,

- not current launch guidance.

-

- ## Planning workflow

-

- Use the current staged workflow directly: shape plans in `docs/plans/`, run the

- relevant review/autoplan/preflight step when needed, then move committed phases

- through GSD. Do not depend on a separate hybrid-router skill being installed.

-

- One source of truth per stage, with `STATUS.md` as the short human-facing

- dashboard:

-

- - Current orientation: `STATUS.md`.

- - Before execution: `docs/plans/*.md` or GitHub issues.

- - During execution: `.planning/STATE.md` and `.planning/phases/*`.

- - After shipping: summaries, verification reports, and retrospectives.

-

- Do not create `.planning/phases/*` for brainstorming. Once a phase is under GSD,

- execute and ship it with GSD unless the user explicitly changes the workflow.

- Root `PLAN.md` is retained only for compatibility and must not receive new

- active phase content. Current focus and active source links are in `STATUS.md`.

- During GSD closeout/verify/ship, update `STATUS.md` when current focus, latest

- phase, next action, or blocker changed; keep it short and do not mirror

- `.planning/STATE.md`. For parallel standalone terminal work, use one task-owned

- file under `docs/status/active/` instead of editing `STATUS.md` for routine

- progress.

-

- ## Agent skills

-

- ### Issue tracker

-

- Issues and PRDs are tracked in GitHub Issues for `MiaoDX/roboclaws`. See

- `docs/agents/issue-tracker.md`.

-

- ### Triage labels

-

- The repo uses the canonical five-label triage vocabulary. See

- `docs/agents/triage-labels.md`.

-

- ### Domain docs

-

- Single-context repo: project orientation lives in root docs, with ADRs in

- `docs/adr/`. See `docs/agents/domain.md`.

-

- ## Skill routing (gstack)

- When the user's request matches an available skill, ALWAYS invoke it using the Skill

- tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.

- The skill has specialized workflows that produce better results than ad-hoc answers.

- Key routing rules:

- - Product ideas, "is this worth building", brainstorming → invoke office-hours

- - Bugs, errors, "why is this broken", 500 errors → invoke investigate

- - Ship, deploy, push, create PR → invoke ship

- - QA, test the site, find bugs → invoke qa

- - Code review, check my diff → invoke review

- - Update docs after shipping → invoke document-release

- - Weekly retro → invoke retro

- - Design system, brand → invoke design-consultation

- - Visual audit, design polish → invoke design-review

- - Architecture review → invoke plan-eng-review

- - Save progress, checkpoint, resume → invoke checkpoint

- - Code quality, health check → invoke health

- ## Skill routing (GSD)

- For phase execution, verification, and work that needs `.planning/` structure,

- invoke GSD commands first:

- - Plan a phase in detail → `/gsd-plan-phase`

- - Execute a planned phase → `/gsd-execute-phase`

- - Verify UAT on built work → `/gsd-verify-work`

- - Create PR for a completed phase → `/gsd-ship`

- - Investigation / root cause → `/gsd-debug`

- - Small / bounded fix → `/gsd-quick` or `/gsd-fast`

- - What's the next step in the workflow? → `/gsd-next` or `/gsd-progress`

- - Ingest existing plan docs into `.planning/` → `/gsd-ingest-docs`

- - Start a fresh project / milestone under GSD → `/gsd-new-project` or `/gsd-new-milestone`