UnityLaparoscopicSceneSimulator/.opencode/README.md

opencode — LaparoscopicSurgeryEmulator

This directory is the opencode configuration for the UnityLaparoscopicSceneSimulator project (Unity 2022.3.25f1, URP 14.0.11, Coplay MCP bridge).

It defines the rules, responsibilities, and safe operating workflow for agents that drive Unity. It is deliberately not a build plan — the project is built one bounded change at a time, by the right specialist agent, with the right safety review.

Top-level rule (read first)

Read-only by default. Write only after a bounded change statement. Never perform global refactors, package changes, asset deletions, or scene-wide replacements unless explicitly authorized.

The full operating contract is in AGENTS.md.

Subagents

Each subagent has a narrow authority and a handoff protocol. They do not step on each other.

Subagent	Owns	Authority	File
Scene Director	Visual intent, composition, framing, realism priorities, laparoscope feel	Read + propose; no scene writes	subagents/scene-director.md
Unity Execution	All scene / hierarchy / material / script / prefab writes through MCP	The only subagent that mutates scene state	subagents/unity-execution.md
Lighting / Rendering	URP Volume overrides, reflection probes, color/HDR, post-processing, render-quality tradeoffs	Read + bounded Volume / URP writes (via Unity Execution for hierarchy-affecting changes)	subagents/lighting-rendering.md
Materials / Assets	PBR tissue / cavity / instrument materials, texture import settings, asset assignment	Read + material / texture writes; no scene hierarchy writes	subagents/materials-assets.md
Medical-Simulation Safety Reviewer	Visual-only, non-clinical, non-instructional boundary	Read-only; flag, rewrite, or refuse	subagents/medical-safety-reviewer.md
Performance / QA	Real-time budget, console hygiene, scene cleanliness, visual regression	Read-only; verify and request rollback	subagents/performance-qa.md

Skills

Skills are project-scoped reference material. Load them on demand. They encode the facts of this repository so agents do not have to rediscover them on every turn.

Skill	When to load
unity-mcp-orchestrator	Before any mcp__unity__* call. Project facts, MCP tool discipline, the handoff format pointer.
unity-hierarchy-hygiene	Before creating, moving, parenting, renaming, prefab-ifying, or activating GameObjects. The SurgeryBenchmark/* authoring contract.
urp-render-pipeline	Before touching URP assets, Volume profile overrides, reflection probes, or any HDRP-flavoured request. The URP 14.0.11 translation table.
pbr-materials-tissue	Before creating, editing, or assigning tissue / cavity / instrument materials. The five canonical materials and their starting values.
cinematic-laparoscope-camera	Before adjusting camera FOV, clipping, exposure, depth of field, or framing. The laparoscope-feel rules.
medical-simulation-safety	Whenever a comment, README, log, screenshot caption, or handoff note touches anatomy, surgery, instruments, tissue, or pathology. The hard refusals.
realtime-performance-budget	After any visual / hierarchy / material / lighting / post-processing change. The budget table and the verification routine.
change-reporting-handoff	After every bounded change and every cross-agent task. The ROLE / OBSERVED / CHANGED / NOT CHANGED / RISKS / NEXT SAFE OPTIONS format.

The three-gate loop

Every subagent works the same way:

1. Inspect — read-only MCP tools and project resources. No mutation.
2. Propose — a one-paragraph bounded change statement: what, why bounded, what stays the same, verification.
3. Execute and verify — apply the change, then re-read affected objects, read_console, take a verification screenshot, and emit the handoff.

The key rule: agents should not jump from idea → broad scene mutation. They go: inspect → bounded change → verify.

Cross-agent handoff

After any action, every subagent emits a handoff in this format (full template in change-reporting-handoff):

ROLE: <which agent>
OBSERVED: <what the inspection found>
CHANGED: <exact objects/assets/settings/scripts modified>
NOT CHANGED: <relevant things intentionally left untouched>
RISKS: <visual, technical, performance, safety, or uncertainty notes>
NEXT SAFE OPTIONS: <bounded improvements another agent may consider>

Handoffs are short, scannable, and honest. A CHANGED: (none) is allowed and often correct for a director / safety / QA pass.

Authored contract (do not change without explicit approval)

• The five SurgeryBenchmark/Scenarios/Scenario_0X_* roots are the external-automation surface. Toggle activation, never rename.
• The three SurgeryBenchmark/Shared/*Slot anchors are replacement anchors. Fill them; never rename them.
• The preserved MainScene subtrees (stereo rig, Blending, UI, WebRTC, RPC) are the interop surface. Do not move, rename, retarget, or delete.
• The five canonical materials (Tissue_Default, Tissue_Wet, Tissue_LowTexture, CavityWall, InstrumentProxy) are visual. Do not rename.
• The off-limits scripts (Rotator, BlendShaderController, DepthGetter, DepthRenderPassFeature, DepthTester, TexturesSettings, WEBRTCSender, CrpcApi, MinimalRpcServer, plus Assets/Scripts/UDP/, Assets/Scripts/VideoChat/, Assets/Scripts/Editor/) are interop / pipeline. Modify only with explicit approval.

What this configuration refuses

• HDRP-only features (ray-traced reflections, planar reflection probes, path tracer, EV exposure) — refuse; translate to URP.
• Clinical / anatomical / surgical content, claims of medical accuracy, patient-specific advice. The scene is a visual / technical simulation only.
• Global refactors, package changes, asset deletions, scene-wide replacements.
• Modifications to the preserved MainScene subtrees or the off-limits scripts without explicit approval.