Unity Agent Workflows

Proof Gates

Owner chain before visible/runtime edits:

visible object -> scene/prefab/reference -> script/component -> mutating method -> serialized/runtime override

Runtime Visible Output Hard Stop before changing coordinates, anchors, offsets, padding, scale, layout timing, camera conversion, or fallback constants:

user-visible output
-> active source object
-> selected source bounds: markerRect / visualRect / interactiveRect / logicRect
-> source parent chain
-> owner script/component
-> runtime writer after creation/layout
-> source space and camera/canvas
-> destination root/canvas/space
-> conversion API path
-> converted output rect/position
-> validation method

Runtime numeric proof required after any visible patch is wrong/unchanged/challenged:

source object:
source parent chain:
source bounds: markerRect / visualRect / interactiveRect / logicRect
source canvas/root/renderMode/scaleFactor/camera:
destination object/root/canvas/renderMode/scaleFactor/camera:
conversion API path:
converted rect min/max:
converted center/size:
final drawn object:
final drawn position:
final drawn size/bounds:
spatial IoU / threshold:
center offset delta / tolerance:
predictive intercept / ballistic roots / drag limit / quaternion antipodal check:
runtime writer checked:
validation:

Missing source bounds, converted rect, final drawn rect, or spatial IoU < 0.95 for UI / < 0.85 for HUD is FAIL; return a runtime probe plan only.

Multi-Surface Visible Behavior Lock for the same visual behavior across scenes/surfaces:

requested behavior:
surface list:
surface 1 visible object:
surface 1 owner/caller/writer:
surface 1 asset/factory dependency:
surface 1 fallback behavior:
surface 2 visible object:
surface 2 owner/caller/writer:
surface 2 asset/factory dependency:
surface 2 fallback behavior:
shared helper/factory/global selector:
callers outside requested surfaces:
patch order:
validation per surface:

If any requested surface lacks owner/caller/writer or asset/fallback proof, stay read-only for patches and return the missing proof plan. Do not patch only a preview/transition surface when the user also requested gameplay/runtime behavior.

State-step proof: screen open, click, analytics, or prompt shown is not completion. Prove relevant steps separately: shown, clicked, opened, selected, applied, completed, persisted, old-save path, reset path.

Sub-agent permission guard: default to one main agent. Before spawning any sub-agent, decide that the work needs independent proof tracks, explain why, list each sub-agent task, state read-only vs edit permission, allowed files/surfaces, forbidden files/surfaces, and checker need, then ask the user. Do not spawn until the user explicitly approves in the same turn, except when the user already explicitly requested sub-agents in that turn.

Multi-agent guard: main agent owns Routing Card, scope, allowed files, not-touched files, allowed runtime caller(s), and forbidden callers/surfaces before workers patch. Workers use disjoint ownership and stop if a different owner, shared caller blast radius, or out-of-scope file appears. Checker fails missing runtime numeric proof, state-step proof, or caller blast-radius proof for shared changes.

For screenshot, visible UI, runtime text, or single-surface fixes, the scope lock must include exact text/key/object searched, owner file, creator method, refresh/update writer, allowed files, explicitly not touched files, allowed runtime caller(s), forbidden callers/surfaces, and nearby candidates rejected. Shared factories/helpers/styles/global methods are not owners unless the visible callsite proves their use and caller search proves no non-target surface will change.

For Unity visual/model/sprite/asset integration, the visible runtime object identity must be proven before editing. If the user-visible target and semantic feature name disagree, or if the first owner candidate is a factory/helper/registry/bridge/global selector, list competing owners and reject them with file-backed proof. If competing owners cannot be rejected, stay read-only and ask whether to continue single-agent investigation or use read-only sub-agent discovery.

Asset/source ID lock: when the user provides a generator ID, asset ID, sprite sheet, prefab, scene, surface, or object name, use only that source and surface. Do not substitute another asset/source or broaden to gameplay/global behavior without asking first.

Asset Variant Availability Gate: before changing directional sprites, model poses, animation frames, sprite selectors, model factories, or fallback visuals, prove the requested variants exist and identify the runtime fallback when they do not. Missing variants are not a license to patch unrelated surfaces or shared factories; either add a surface-local fallback with caller proof, generate/obtain the missing source asset through the approved asset workflow, or stop and ask.

Shared Caller Blast Radius Gate:

target surface/object:
allowed runtime caller(s):
shared method/helper/factory:
all callers searched:
callers outside target:
surface-local API/branch exists or will be added:
non-target behavior unchanged:
validation:

If a shared factory/helper/global method has callers outside the requested surface, do not change its existing behavior for the single visible target. Add a surface-local API/adapter, patch the proven owner callsite, or stop and ask for approval.

After a visible patch is challenged as unchanged/wrong, static source reasoning is not enough. Capture runtime object/asset/sprite name, active caller, converted/final drawn values where relevant, and the writer that overwrites them before another patch.

Architecture Rules

• No fixed structure; derive module/layer/folder/namespace/assembly/scene/prefab ownership from the user project.
• Core/Contracts/Systems/Features is fallback example only.
• No guessed targeting: if asked to bind, focus, highlight, click, or align a visible object, resolve the real runtime object and coordinate space before editing.
• Do not grow hubs when a focused collaborator, data object, contract, event, bridge, or service can own the work.
• Do not add direct sibling feature references; use contracts/events/gateways/bridges.
• Do not add new scripts to broad folders when a specific owner, module, assembly, feature folder, scene owner, or content definition path exists.
• Do not treat scene YAML, prefab scale, or searched constants as runtime truth until startup/layout/animation writers are checked.
• Do not mix source refactors with cache cleanup, generated build output, or unrelated scene/prefab churn.
• Visual source asset creation/replacement happens before integration code; if required tool is unavailable, stop and report.
• Cleanup needs code refs, YAML GUID refs, Resources/addressables, scene/prefab refs, generated-vs-source status, and runtime reachability proof.

Routing Card

Task type:
Structural trigger:
Runtime-visible target:
Current owner file(s):
Project structure source: live scan / docs / graph / UNITY_STRUCTURE.md / mixed
Placement layer/category from repo:
Module/system name:
Data/definition source:
Runtime source-of-truth values:
Active asset/sprite/model name:
Asset variants checked: yes/no + exact paths/names
Fallback behavior checked: yes/no + exact method/value
Allowed runtime caller(s):
Forbidden callers/surfaces:
Coordinate/rendering space checked: yes/no
Shared helper/factory/global method touched: yes/no + caller proof
Asset/source ID lock: yes/no + exact ID/path/name
New responsibility added? yes/no
Cross-module communication needed? yes/no
Hub risk: low / medium / stop
Visual source asset required? yes/no
Validation plan:
Files allowed to touch:
Files explicitly not touched:

Add graph/God Node/edge count/over-500 status only when architecture or C# responsibility changed and graph/source data exists.

Closeout Schema

Always report:

• Changed files.
• Non-requested systems touched: yes/no.
• Runtime-owner or structural proof.
• Runtime numeric proof for repeated visible-output fixes, or probe plan if not captured.
• Validation command and result.
• References loaded: or References missing:.
• Project maps loaded: or Project maps missing:.
• Residual risk.

Add only when relevant: largest touched .cs files and over-500 status, graph/God Node/edge-gate status, visual asset tool used, Play Mode/Game view/device/batchmode/graph gaps.