UnityLaparoscopicSceneSimulator/.opencode/AGENTS.md

AGENTS — operating contract for opencode in this project

This is the one-page contract every opencode agent reads first. It complements the per-agent and per-skill files under .opencode/. Read it once, then go to the relevant skill and subagent 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: Coplay (com.coplaydev.unity-mcp via Packages/manifest.json).
• 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.

The full inventory and MCP tool mapping are in skills/unity-mcp-orchestrator/SKILL.md.

2. 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 skills/unity-hierarchy-hygiene/SKILL.md.
6. No destructive edits without explicit approval.
7. Reusable prefabs / materials over duplicated objects.
8. Physically plausible lighting and PBR materials — see skills/urp-render-pipeline/SKILL.md and skills/pbr-materials-tissue/SKILL.md.
9. Performance budgets appropriate for real-time Unity — see skills/realtime-performance-budget/SKILL.md.
10. Always report what changed and what remains uncertain, in the handoff format — see skills/change-reporting-handoff/SKILL.md.

3. 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.

4. The handoff format (mandatory)

After every action, emit a handoff. Full template in skills/change-reporting-handoff/SKILL.md.

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.

5. Hard refusals

Any of the following, in any context, 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. The project is URP. Translate to URP equivalents or refuse.
• Global refactors: scene-wide replacements, bulk deletes, package changes, Packages/manifest.json edits, .csproj / .sln edits, 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.
• Procedural textures inside the project without explicit approval.
• Naming a material / scenario / script with a clinical term (e.g., Tissue_Inflamed.mat, Scenario_Bleeding). The boundary is in the names too.

6. The orchestrating agent's job

If you are the top-level orchestrator (or acting as one), the job is not to build the whole simulation in one pass. The job is to:

• Keep specialist subagents on small, reversible, realism-focused changes.
• Preserve the authored scene contract and the medical-safety boundary.
• Preserve project stability (no Packages/manifest.json churn, no bulk ops, no global refactors).
• Route work: a Material change goes to Materials/Assets; a Volume override goes to Lighting/Rendering; a hierarchy change goes to Unity Execution; a framing / composition question goes to the Scene Director; a safety concern goes to the Medical-Simulation Safety Reviewer; a budget / cleanliness question goes to Performance/QA.
• Chain handoffs: agent A's handoff is agent B's first input. B re-verifies A's claimed state with one targeted read, then acts.

7. 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.

8. If something is wrong, say so

If a previous agent's handoff is wrong (the change was not applied, the path is wrong, the contract was violated), the next agent says so in its own handoff's OBSERVED and proceeds cautiously. Handoffs do not paper over drift.