UnityLaparoscopicSceneSimulator/CLAUDE.md

# CLAUDE.md — operating contract for Claude Code in this project

This is the one-page contract every agent reads first. It complements the per-agent files under `.claude/agents/` and the per-skill commands under `.claude/commands/`. Read it once, then go to the relevant agent or command for the actual work.

## 1. Project identity (do not rediscover)

- **Unity 2022.3.25f1** (LTS).
- **Render pipeline: URP 14.0.11** (not HDRP). URP assets live in `Assets/Settings/URP-*.asset`.
- **MCP bridge: UnityMCP** (`com.coplaydev.unity-mcp` via `Packages/manifest.json`). Use `mcp__UnityMCP__*` tools.
- **Active emulation scene: `Assets/Scenes/LaparoscopicSurgeryEmulation.unity`**.
- **Authored contract**: `SurgeryBenchmark/Shared/{AnatomySlot,CavitySlot,InstrumentSlot}` are replacement anchors. The five `SurgeryBenchmark/Scenarios/Scenario_0X_*` roots are the external-automation toggle surface.
- **Preserved from `MainScene`**: stereo rig, `Blending`, UI, WebRTC, RPC. Do not rename, move, retarget, or delete.
- **Off-limits scripts**: `Rotator`, `BlendShaderController`, `DepthGetter`, `DepthRenderPassFeature`, `DepthTester`, `TexturesSettings`, `WEBRTCSender`, `CrpcApi`, `MinimalRpcServer`, plus `Assets/Scripts/UDP/`, `Assets/Scripts/VideoChat/`, `Assets/Scripts/Editor/`.
- **Five canonical materials**: `Tissue_Default`, `Tissue_Wet`, `Tissue_LowTexture`, `CavityWall`, `InstrumentProxy` in `Assets/Materials/LaparoscopicBenchmark/`. Names are part of the contract.

Full inventory and MCP tool mapping: `/unity-mcp-orchestrator` command.

## 2. MCP tool naming

Use `mcp__UnityMCP__<tool>` for all Unity Editor operations:
`find_gameobjects`, `manage_scene`, `manage_gameobject`, `manage_components`, `manage_material`, `manage_graphics`, `manage_camera`, `manage_prefabs`, `manage_asset`, `manage_texture`, `manage_animation`, `manage_vfx`, `manage_shader`, `manage_physics`, `manage_profiler`, `manage_ui`, `manage_editor`, `create_script`, `delete_script`, `manage_script`, `script_apply_edits`, `apply_text_edits`, `validate_script`, `read_console`, `refresh_unity`, `run_tests`, `execute_code`, `execute_menu_item`, `batch_execute`, `find_in_file`, `unity_reflect`, `unity_docs`.

## 3. Core priorities (in order)

1. **Visual realism** over feature quantity.
2. **Safe, non-clinical, non-instructional** representation. Visual emulation only.
3. **Reversible changes** — every bounded change must be easy to undo.
4. **Small, inspectable edits** — one parent container, one material variant, one Volume override, one prefab edit.
5. **Clear naming and scene organization** — see `/unity-hierarchy-hygiene`.
6. **No destructive edits** without explicit approval.
7. **Reusable prefabs / materials** over duplicated objects.
8. **Physically plausible lighting and PBR materials** — see `/urp-render-pipeline` and `/pbr-materials-tissue`.
9. **Performance budgets** appropriate for real-time Unity — see `/realtime-performance-budget`.
10. **Always report** what changed and what remains uncertain, in the handoff format — see `/change-reporting-handoff`.

## 4. The three-gate loop

Every agent works the same way. No agent may jump from idea → broad scene mutation.

### Gate 1 — Inspect
Read-only tools only: `find_gameobjects`, `manage_scene(get_hierarchy|get_active)`, `manage_graphics(pipeline_get_info|volume_get_info)`, `manage_material(get_material_info)`, `manage_asset(get_info)`, `read_console`, `manage_camera(screenshot)` for visual context. Confirm the change is bounded.

### Gate 2 — Propose a bounded change
State in one paragraph:
- **What** changes (one action, or a tightly-related set under the same authored root).
- **Why** it is bounded (which authored root, which slot, which asset).
- **What** is left alone (preserved subtrees, off-limits scripts, the other scenario roots).
- **Verification** you will run after (`read_console` + screenshot from the scope + a 30–45° offset).

If the change is destructive (delete, swap URP asset, modify `Packages/manifest.json`, edit off-limits scripts, move preserved subtrees), **stop and ask**.

### Gate 3 — Execute and verify
Apply the change with the appropriate MCP call. Re-read affected objects. `read_console(types=["error","warning"])`. Take a verification screenshot. Emit the handoff in the standard format.

## 5. The handoff format (mandatory)

After every action, emit a handoff. Full template in `/change-reporting-handoff`.

```
ROLE: <which agent>
OBSERVED: <what the inspection found, with concrete paths>
CHANGED: <exact objects/assets/settings/scripts modified, with paths>
NOT CHANGED: <relevant things intentionally left alone, including off-limits items>
RISKS: <visual, technical, performance, safety, or uncertainty notes>
NEXT SAFE OPTIONS: <one to three bounded suggestions for the next agent>
```

- `CHANGED: (none — read-only pass)` is allowed and often correct for director / safety / QA passes.
- Always fill `NOT CHANGED:` with the preserved subtrees and the off-limits scripts you confirmed untouched.
- Always fill `RISKS:` with at least one item, even if it's `none observed`.

## 6. Hard refusals

Any of the following is a refusal. The project does not do them.

- **Clinical / surgical content**: surgical steps, patient-specific advice, anatomical diagnosis, treatment decisions, operative guidance, performance claims, real-patient references.
- **HDRP-only features**: ray-traced reflections, planar reflection probes, path tracer, EV-based physical exposure. Translate to URP equivalents or refuse.
- **Global refactors**: scene-wide replacements, bulk deletes, package changes, `Packages/manifest.json` edits, `.csproj` / `.sln` / `ProjectSettings/*.asset` edits via the file system.
- **Moving preserved subtrees**: stereo rig, `Blending`, UI, WebRTC, RPC.
- **Renaming scenario roots or slot anchors**.
- **Modifying off-limits scripts** without explicit approval.
- **Bulk imports** of FBX / texture packages without bounded change approval.
- **Naming a material / scenario / script with a clinical term** (e.g., `Tissue_Inflamed.mat`, `Scenario_Bleeding`).

## 7. Subagents

| Agent | Owns | File |
|---|---|---|
| Scene Director | Visual intent, composition, framing, laparoscope feel | `.claude/agents/scene-director.md` |
| Unity Execution | All scene / hierarchy / material / script / prefab writes | `.claude/agents/unity-execution.md` |
| Lighting/Rendering | URP Volume overrides, reflection probes, post-processing | `.claude/agents/lighting-rendering.md` |
| Materials/Assets | PBR tissue / cavity / instrument materials, texture imports | `.claude/agents/materials-assets.md` |
| Medical-Simulation Safety Reviewer | Visual-only, non-clinical boundary review | `.claude/agents/medical-safety-reviewer.md` |
| Performance/QA | Real-time budget, console hygiene, visual regression | `.claude/agents/performance-qa.md` |

## 8. Commands (skills)

| Command | When to use |
|---|---|
| `/unity-mcp-orchestrator` | Before any `mcp__UnityMCP__*` call. Project facts, tool discipline, handoff format. |
| `/unity-hierarchy-hygiene` | Before creating, moving, parenting, renaming, or activating GameObjects. |
| `/urp-render-pipeline` | Before touching URP assets, Volume profiles, or any HDRP-flavoured request. |
| `/pbr-materials-tissue` | Before creating, editing, or assigning tissue / cavity / instrument materials. |
| `/cinematic-laparoscope-camera` | Before adjusting camera FOV, clipping, exposure, or framing. |
| `/medical-simulation-safety` | Whenever output mentions anatomy, surgery, instruments, tissue, or pathology. |
| `/realtime-performance-budget` | After any visual / hierarchy / material / lighting / post-processing change. |
| `/change-reporting-handoff` | After every bounded change and every cross-agent task. |

## 9. Verification is mandatory

Every bounded change ends with:
- `read_console(types=["error","warning"], count=20)`.
- A scope screenshot and, for visual changes, a 30–45° offset screenshot.
- A handoff in the standard format.

A change is **not** done until those three are present in the handoff.