git:20260515.cbe9afb to git:20260516.459fd92

---

name: unity-agent-workflows

description: Use for AI-assisted Unity work that needs live repo discovery, project-derived routing, runtime-owner proof, runtime-visible output hard stops, runtime numeric proof for repeated visible-output failures, state-step guards, multi-agent scope ownership, modular C#/asmdef safety, UI/scene/visual asset gates, data-first content changes, validation, cleanup proof, or durable workflow rules. Best when agents must prove the actual folder/module/scene/prefab/runtime owner before editing, especially runtime UI, generated assets, code graphs, tutorial/state flows, guided equipment/shop flows, overlay/dim source-bound mistakes, coordinate conversions, focus/highlight/marker/HUD alignment, or repeated "fix still not visible" failures.

license: MIT

---

# Unity Agent Workflows

AI contract for Unity work. Keep answers compact, but never remove exact paths, object/class names, commands, errors, validation, rollback notes, or proof requirements.

## Core Loop

0. No proof, no edit.

1. Treat this injected `SKILL.md` as authoritative; do not search for its own path unless missing or asked for diagnostics.

3. Run `git status --short`; preserve unrelated dirty files.

4. If user says only `$unity-agent-workflows. Teach`, run Teach.

5. Derive only relevant live structure before architecture claims: folders, namespaces, `.asmdef`, scenes/prefabs, bootstraps, graphs, docs, `UNITY_STRUCTURE*`.

6. Classify task with `Task Gate`, then load required references before edits.

7. Inspect real owner files; never start from memory, nearest-name guessing, semantic similarity, or screenshot proximity alone.

8. Fill useful `Routing Card` fields for structure, visible output, state flow, multi-agent, or hub changes.

9. Patch the smallest proven owner/artifact.

10. Validate, sync mirrors if package skill files changed, then close out with proof.

## Task Gate

| Trigger | Required action |

|---|---|

| Runtime/visible bug | Prove owner chain before editing. |

| Runtime-visible output, target alignment, focus/highlight/marker/HUD, overlay, input blocker, modal dimming, duplicate names, hardcoded layout, "do not guess" | Runtime Visible Output Hard Stop. |

| Screenshot or visible UI text fix | Screenshot Text Owner Gate; search exact visible text/localization key and prove creator plus refresh writer before editing. |

| Overlay/dim source-bound mistakes | Prove source target bounds; overlay/dim/mask/blocker rects are destination output unless explicit marker proof exists. |

| Repeated visible-output mismatch after patch | Runtime numeric proof before another coordinate/layout/fallback patch. |

| New/moved files, expanded C# responsibility, asmdef/module routing, hub deflation | Project-derived routing, no fixed structure, hub stop gate. |

| UI, screenshot, HUD, menu, safe area, TMP, spotlight | UI workflow plus runtime-owner proof and validation. |

| Visual source asset | Source asset/generator gate before Unity integration code. |

| Content, progression, economy, levels, objectives, gameplay tuning | Data-first content workflow. |

| Tutorial, onboarding, mission, unlock, equipment, reward, shop, navigation, state transition, guided equipment/shop flows | State-step guards. |

| Compile/runtime doubt, stale Bee/Roslyn response files, Play Mode proof | Validation workflow. |

| Cleanup/deletion/generated files/git hygiene | Cleanup proof. |

| Rule/session mining/workflow update | Patch only the owning artifact. |

## Required References

Load only matching files; resolve relative to this skill directory. If a required reference is missing, stop broad edits, use only visible rules here, and report `References missing:`.

| Task trigger | References before editing |

|---|---|

| New files/classes, moved scripts, asmdef/module routing, dependency direction, hub deflation/refactor | `references/project-structure-discovery.md`, `references/modular-architecture.md`, `references/ai-workflows.md` |

| New runtime feature, content, progression, levels, economy, objective/data-first work | `references/project-structure-discovery.md`, `references/content-and-systems.md`, `references/ai-workflows.md` |

| Tutorial, onboarding, mission step, unlock, equipment, reward, shop, navigation gate, state transition | `references/project-structure-discovery.md`, `references/content-and-systems.md`, `references/ai-workflows.md`, `references/unity-validation.md` |

| Compile error, validation repair, stale Bee/Roslyn response files, Play Mode proof | `references/unity-validation.md` |

| Cleanup/deletion/generated files/git hygiene | `references/cleanup-and-git.md` |

| Rule/session mining/workflow update | `references/session-mining.md` |

Reference map: `references/ai-workflows.md` = Routing Card/workflow/closeout; `references/workflow-recipes.md` = named recipes; `references/project-structure-discovery.md` = Teach and `UNITY_STRUCTURE*`; `references/modular-architecture.md` = layering/asmdef/hub gates; `references/runtime-owner-proof.md` = owner chain/numeric gate; `references/runtime-visible-targets.md` = focus/click/overlay/fallback target rules; `references/target-bounds-catalog.md` = `markerRect`/`visualRect`/`interactiveRect` choices; `references/coordinate-space-conversion.md` = world/screen/canvas/camera/safe-area conversions; `references/unity-validation.md` = validation ladder/checker failures; `references/ui-and-visual-assets.md` = UI/safe area/visual asset gate; `references/content-and-systems.md` = data-first systems/state steps; `references/cleanup-and-git.md` = deletion/git hygiene; `references/session-mining.md` = durable rules.

## Teach

```text

UNITY_STRUCTURE.ui.md

UNITY_STRUCTURE.runtime.md

UNITY_STRUCTURE.content.md

UNITY_STRUCTURE.assemblies.md

UNITY_STRUCTURE.cleanup.md

```

## Proof Gates

Owner chain before visible/runtime edits:

```text

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:

```text

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:

```text

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:

runtime writer checked:

validation:

```

Missing source bounds, converted rect, or final drawn rect is FAIL; return a runtime probe plan only.

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

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

```text

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:

Coordinate/rendering space checked: yes/no

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.