v0.7.0 to v0.8.0

64 added, 105 removed. Audit A to A.

---

name: i4h-workflow-create

- version: "0.7.0"

- description: Create a new agentic env by forking an existing env. Use for new env/task scaffolding, not scene edits or baking.

+ description: Create a minimal blank Workflow scaffold with a Scene containing ground and light plus an idle run mode. Use for fast new Workflow scaffolding.

license: Apache-2.0

metadata:

author: "Isaac for Healthcare Team <isaac-for-healthcare-support@nvidia.com>"

+ version: "0.8.0"

tags:

- isaac-for-healthcare

- i4h

- - agentic-workflow

- - environment

- - scaffolding

+ - isaac-sim

+ - workflow-authoring

---

- # i4h Workflow - Create Env

+ # Create a Blank i4h Workflow

## Purpose

- Create the first runnable version of a new `workflows/agentic` environment by forking the closest existing env. Keep this skill focused on env scaffolding: YAML, assets, task, env class, runtime, and validation. Do not use this skill to polish an existing scene, add optional props/cameras, or bake bridge edits; use [[i4h-workflow-scene-edit]] for that.

- ## Base Code

- Resolve and work from the i4h-workflows root:

- ```bash

- ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"

- if [ ! -d "$ROOT/workflows/agentic" ]; then

- ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"

- [ -d "$ROOT/workflows/agentic" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"

- fi

- export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

- ```

- ## What to Load

- Before editing, load only the references that match the request:

- - Always load `skills/i4h-workflow/references/repo-map.md`.

- - Always load `skills/i4h-workflow-create/references/create-contract.md`.

- - Load `skills/i4h-workflow-create/references/env-authoring-patterns.md` to choose the source env, robot owner, policy stack, and YAML pattern.

- - Load `skills/i4h-workflow-create/references/hybrid-layout-rules.md` only for hybrid scene+robot envs, G1 footprint/table-height work, catalog USD scale, or support-surface layout.

- - Load a recipe file only when the prompt matches it exactly enough to avoid re-deciding components.

- Recipe routing:

- | Prompt shape | Reference |

- |---|---|

- | Surgical tool sorting using G1 based on `scissor_pick_and_place` | `skills/i4h-workflow-create/references/g1-surgical-tool-sort.md` |

- ## Create Contract

+ Create a complete runnable blank Workflow without searching for an existing Workflow or booting Isaac Sim.

- Create the env shell first. A normal create task should produce exactly these surfaces unless the chosen existing pattern requires an explicit exception:

+ ## Instructions

- | Surface | Path |

- |---|---|

- | Env YAML | `workflows/agentic/config/environments/<env>.yaml` |

- | Assets | `workflows/agentic/arena/arena/assets/<env>.py` |

- | Task | `workflows/agentic/arena/arena/tasks/<env>.py` |

- | Env class | `workflows/agentic/arena/arena/environments/<env>_environment.py` |

- | Runtime | `workflows/agentic/arena/arena/runtimes/<env>.py` |

+ 1. Resolve the checkout using `I4H_WORKFLOWS` when set; otherwise use the current git root. If neither contains `workflows/i4h_workflows`, use the checkout resolver from the repository `AGENTS.md`.

+ 2. Choose a lowercase snake_case Workflow id.

+ 3. Select exactly one approved product specialty: `laparoscopic-robotics`, `ultrasound-robotics`, `endoluminal-robotics`, or `hospital-automation-robotics`.

+ 4. Generate the blank Workflow and run the static validation below.

- Keep all paths repo-root relative and keep the `workflows/agentic/` prefix. Do not create a new policy package, README, docs, or shared-module edits unless the user explicitly asks and the policy stack truly needs it.

+ If the request does not identify a specialty, ask the user to choose one; do not infer a product category from the workflow name alone.

- ## Workflow

+ Run:

- 1. Resolve components: env id, source env, scene/assets source, robot owner, policy stack, model/checkpoint, cameras, objects/destinations, success rule.

- 2. Inspect the selected source env YAML, env class, assets, task, runtime, and policy stack files before writing code.

- 3. Fork the closest working pattern. Preserve inline-scene vs registry-asset style; do not invent a new architecture.

- 4. Keep the first version minimal and runnable. Optional visual polish, extra props, new cameras, and layout changes happen through scene-edit after the env exists.

- 5. Run validation and fix source until the env builds and the rendered scene is visually sane.

+ ```bash

+ ./scripts/create_blank_environment.py <workflow_id> --specialty <specialty>

+ ```

- For an exact recipe match, do not re-derive the architecture after loading the recipe. Read only the source files the recipe names, skip large source runtime files when the recipe says the runtime is a re-export, then write the five contract files immediately. Do not inspect third-party framework internals unless a validation error requires it.

+ This is the only authoring utility that generates workflow-specific source. It rejects an existing public workflow id in any specialty before dry-run output or file creation. It writes the fixed empty templates that establish the design boundary; later scene and task code is written by the coding agent. Use `--dry-run` to preview its output, `--description TEXT` to customize the scene-manifest description, and `--validate` to run the focused static checks after creation. Do not combine `--dry-run` and `--validate`.

- Plan shape:

+ The script refuses to overwrite files and creates only:

```text

- Env id:

- Source env / recipe:

- Scene/assets source:

- Robot owner:

- Policy stack + model/checkpoint:

- Objects/destinations:

- Success rule:

- Files to create:

- Validation:

+ ./

+ ├── arena/i4h_arena/assets/<workflow_id>.py

+ ├── arena/i4h_arena/scenes/<workflow_id>.py

+ ├── arena/i4h_arena/scenes/manifest/<workflow_id>.yaml

+ ├── workflows/i4h_workflows/<specialty>/<workflow_id>.py

+ └── workflows/tests/test_<workflow_id>_contract.py

```

- ## Hard Rules

+ The result contains a ground plane, dome light, no embodiment or declared robots, no task-specific objects or cameras, and one `idle` mode. Its contract test verifies durable Workflow and manifest invariants rather than asserting that the Scene stays blank, so later Scene, Task, and run-mode authoring does not require rewriting the test. Do not inspect robot assets, choose a policy, create Task manifests, load upstream Isaac Sim skills, or launch the simulator during blank creation.

- - Env YAML is the source of truth for robot, policy, cameras, task text, dataset mapping, and train defaults.

- - Fork from the nearest existing implementation. For hybrid envs, robot integration comes from the robot owner and scene construction comes from the scene source.

- - Sorting tasks need at least two object types, at least two destinations, and a success rule that fails swapped placements.

- - Static/kinematic destination props may not expose `.data.root_pos_w`; success checks must fall back to `entity.get_world_poses()`.

- - Functions referenced by `func=` inside config classes must be defined above those classes.

- - G1 WBC envs need footprint clearance and matched ground/base-height values; load `hybrid-layout-rules.md` before choosing those numbers.

- - Additional fixed cameras are normally scene-edit/bake work. If a create prompt explicitly requires a policy/dataset camera, load the scene-edit camera and bake references and wire every surface in one pass.

+ ## Utility

- ## Validation

+ | Command | Purpose | Arguments |

+ |---|---|---|

+ | `./scripts/create_blank_environment.py` | Create the complete overwrite-safe blank Workflow | `<workflow_id> --specialty <specialty> [--description TEXT] [--dry-run] [--validate]` |

- Run these static checks:

+ ## Validate

+ Run only fast static checks:

```bash

- python -m py_compile <changed-python-files>

- workflows/agentic/policy/run.sh --list-envs

- workflows/agentic/arena/run.sh --env <env> --dry-run

- workflows/agentic/policy/run.sh --env <env> --dry-run

+ ./scripts/create_blank_environment.py <workflow_id> --specialty <specialty> --validate

```

- Then run the real build/visual gate from `skills/i4h-workflow-create/references/create-validation.md`. `--dry-run` is shallow: it does not prove the task/assets instantiate or the scene is visually usable. Do not report a new env as ready until the bridge reaches ready, key objects are valid, a viewport capture has been inspected, and the bridge is stopped with:

+ When the Workflow already exists because it was created without `--validate`, run the equivalent checks directly:

```bash

- workflows/agentic/arena/stop.sh --env <env>

+ cd "$(git rev-parse --show-toplevel)"

+ ./run.sh show <workflow_id> --mode idle

+ ./run.sh lint <workflow_id> --mode idle

+ ./run.sh lint --all

+ workflows/.venv/bin/python -m pytest workflows/tests/test_<workflow_id>_contract.py -q

+ arena/.venv/bin/python -m pytest arena/tests/test_scene.py -q

```

- If Isaac Sim cannot launch on the host, report that as a blocker and include the static check results; do not present static-only as success.

- ## Hand Off to Scene Edit

- After the env shell passes create validation, use [[i4h-workflow-scene-edit]] for:

+ `--validate` requires the workflow and Arena environments; run `./setup.sh` first if either is missing. It verifies the generated contract and the shared zero-DOF blank-scene runtime adapter without launching Isaac Sim. If a component virtual environment is elsewhere, use that component's Python for its direct test command. Do not run visible or dynamic validation unless the user explicitly requests it.

- - Adding, moving, resizing, or replacing objects/assets.

- - Adding fixed room/overhead/wrist cameras.

- - Live bridge edits.

- - Baking live changes into source.

- - Running `local-agent/validate-bake.sh`.

+ ## Troubleshooting

- The scene-edit workflow owns object snippets, camera snippets, bridge endpoint details, and bake checklists so this create workflow stays small.

+ - If the checkout cannot be resolved, set `I4H_WORKFLOWS` to the existing repository root or use the resolver in `AGENTS.md`.

+ - If generation reports that the workflow id already exists, report its specialty source and ask whether to edit it or use a different id; never overwrite, relocate, or duplicate it.

+ - If `--validate` reports a missing component environment, run `./setup.sh` and repeat the same validation.

## Prerequisites

- - Workflow setup has completed via [[i4h-workflow-setup]]; `.venv`, third-party checkouts, and Isaac Sim launch support are present.

- - The source env and target env id are known, or the prompt provides enough information to choose them from existing patterns.

- - Bridge validation runs on a GPU host that can launch Isaac Sim.

+ Require a writable root-level i4h-workflows checkout and Python 3.11 or newer. Static `--validate` also requires the workflow and Arena component environments.

## Limitations

- - Create one env per invocation.

- - Fork existing patterns; do not invent a new policy stack or shared framework.

- - Use scene-edit for post-create polish, optional props, camera baking, and source persistence of live edits.

- - `--dry-run` is not a substitute for the bridge build and visual validation gate.

+ This skill creates only the five-file idle scaffold. It does not add an embodiment, task behavior, policy, cameras, or task-specific assets, and it does not visibly validate the Scene.

- ## Troubleshooting

+ ## Continue

- - **Missing setup**: if `.venv`, third-party checkouts, or `run.sh` entrypoints are missing, run [[i4h-workflow-setup]] first.

- - **Env not listed**: check that the YAML exists at `workflows/agentic/config/environments/<env>.yaml` and all files use the full `workflows/agentic/` repo-root prefix.

- - **Build fails after static checks pass**: inspect the first Isaac/arena stack trace; common causes are bad cfg kwargs, a helper defined below a config class, or an observation pointing at a missing sensor.

- - **Scene looks wrong**: fix source or use scene-edit to live-adjust and bake; do not report success from static checks alone.

+ Treat creation as the first stage of an incremental workflow:

- ## Final Response

+ 1. Create the blank Workflow scaffold with this skill: blank Scene, scene manifest, and idle-only Workflow.

+ 2. Use `i4h-workflow-scene-edit` to add and visibly verify assets, robots, cameras, layout, and physics, then bake the confirmed Scene.

+ 3. Define behavior only after the user provides a concrete goal and success condition. Reuse compatible Tasks; create a focused Task only when the behavior is new. Do not create an empty placeholder Task.

+ 4. Add rule-based, teleop, replay, or policy modes only when requested and only when their Task and action contracts are runnable.

+ 5. Validate every newly enabled mode with the owning stage skill.

- Report the env id, source choices, files created, validation commands and results, capture paths, and any blocker. Do not commit changes unless the user explicitly asks.

+ The blank Workflow is intentionally useful before behavior exists: its shared idle Task opens the Scene for authoring, so a blank task manifest or implementation would add no capability.

+ ## Examples

+ - `Create a blank hospital-automation-robotics workflow named my_workflow.` → generate `my_workflow` in the hospital automation specialty and run static validation.

+ - `Make a new laparoscopic-robotics workflow called training_sandbox as fast as possible. Start blank.` → generate the same five-file idle-only scaffold under `training_sandbox` in the laparoscopic specialty.

+ ## Completion gate

+ Report the created id, five files, idle-only status, and static validation results. Do not commit unless explicitly asked.