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/`](./README.md). 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`](./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`](./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`](./skills/urp-render-pipeline/SKILL.md) and [`skills/pbr-materials-tissue/SKILL.md`](./skills/pbr-materials-tissue/SKILL.md).
9. **Performance budgets** appropriate for real-time Unity — see [`skills/realtime-performance-budget/SKILL.md`](./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`](./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`](./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.