# 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](./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](./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](./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](./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](./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](./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](./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](./skills/unity-mcp-orchestrator/SKILL.md) | Before any `mcp__unity__*` call. Project facts, MCP tool discipline, the handoff format pointer. |
| [unity-hierarchy-hygiene](./skills/unity-hierarchy-hygiene/SKILL.md) | Before creating, moving, parenting, renaming, prefab-ifying, or activating GameObjects. The `SurgeryBenchmark/*` authoring contract. |
| [urp-render-pipeline](./skills/urp-render-pipeline/SKILL.md) | Before touching URP assets, Volume profile overrides, reflection probes, or any HDRP-flavoured request. The URP 14.0.11 translation table. |
| [pbr-materials-tissue](./skills/pbr-materials-tissue/SKILL.md) | Before creating, editing, or assigning tissue / cavity / instrument materials. The five canonical materials and their starting values. |
| [cinematic-laparoscope-camera](./skills/cinematic-laparoscope-camera/SKILL.md) | Before adjusting camera FOV, clipping, exposure, depth of field, or framing. The laparoscope-feel rules. |
| [medical-simulation-safety](./skills/medical-simulation-safety/SKILL.md) | Whenever a comment, README, log, screenshot caption, or handoff note touches anatomy, surgery, instruments, tissue, or pathology. The hard refusals. |
| [realtime-performance-budget](./skills/realtime-performance-budget/SKILL.md) | After any visual / hierarchy / material / lighting / post-processing change. The budget table and the verification routine. |
| [change-reporting-handoff](./skills/change-reporting-handoff/SKILL.md) | 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.