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.