@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/ui-engineering/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ui-engineering
+description: "Use when the question is how interface should be BUILT — component boundaries, state that belongs in the URL vs the component, loading/empty/error states, forms, optimistic updates, build vs adopt. NOT the visual system (`design`), NOT framework mechanics (`react`/`nextjs`)."
+tags: [interface, frontend, architecture, components, state, craft]
+recommends: [design]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# UI engineering — the decisions between the design and the framework
+
+There is a layer that neither the design skill nor the framework skill owns. The design says what
+the screen should be. The framework says how its API works. **In between sits every decision that
+makes an interface either durable or a maintenance tax** — and it is where most interface work
+actually goes wrong.
+
+Nothing here is framework-specific. These decisions are the same in React, Vue, Svelte, SwiftUI and
+plain HTML; only the syntax moves.
+
+## The one rule
+
+**State goes to the outermost place that still needs it, and no further.** Almost every interface
+tangle is that rule broken in one of two directions: state hoarded in a component that others need,
+or state hoisted into a global store that only one component ever reads.
+
+| Where the state lives | When that is right |
+| --- | --- |
+| **The URL** | Anything a user would bookmark, share, or expect the back button to restore: filters, tabs, pagination, the open item |
+| **The server** | Anything that outlives the session or belongs to more than one user |
+| **A shared parent** | Two siblings genuinely need it, and it dies with the screen |
+| **The component** | Nobody else reads it: hover, focus, an open menu, an in-flight draft |
+
+The most common and most expensive mistake is the first row: state that belongs in the URL kept in a
+component. It looks fine until someone reloads, shares a link, or presses back — and then the
+interface silently loses what the user did.
+
+## Every state, not just the happy one
+
+An interface is not finished when it renders data. It is finished when it renders **all five**:
+
+| State | The question it answers | The usual failure |
+| --- | --- | --- |
+| **Loading** | "Is it working?" | A spinner where the shape is already known — use the shape |
+| **Empty** | "Is it broken, or is there nothing?" | Blank. It must say which, and what to do next |
+| **Error** | "What now?" | A message with no action. Every denial carries its own way out |
+| **Partial** | "Some of it failed" | Ignored entirely; the screen shows a half-truth |
+| **Success** | "It worked" | Silence, so the user does it twice |
+
+The empty state is the one that gets skipped, and it is the first state a new user ever sees.
+
+## Component boundaries
+
+A component earns its existence by **hiding a decision**, not by being reused. Splitting for reuse
+alone produces the worst interfaces: a wrapper around a wrapper, each passing props through, none
+owning anything.
+
+Draw the boundary where:
+
+- it owns a piece of state nothing outside needs;
+- it can be described in one sentence without "and";
+- swapping its internals changes nothing outside it.
+
+Do **not** draw a boundary because a file is long. Long is not a defect; a file that does two
+unrelated things is, and it is usually short.
+
+## Forms
+
+Forms are where interfaces most often insult people, and the rules are unglamorous:
+
+- **Validate on blur, not on keystroke.** Telling someone their email is invalid while they are on
+  the third character is scolding them for not having finished.
+- **Never clear what they typed.** Not on error, not on refresh, not on navigation. Their input is
+  theirs.
+- **Disable the submit only while submitting**, never as a way of enforcing validity — a disabled
+  button with no reason is a dead end.
+- **The error goes next to the field**, and says what to do, not what is wrong.
+
+## Optimistic updates
+
+Show the result before the server confirms **only** when you can honestly undo it. That means: the
+operation is idempotent, the failure is rare, and reverting it is visible and comprehensible.
+
+Optimism on a destructive or an expensive action is a lie you will have to retract in front of the
+user. Deleting, paying, sending — those wait.
+
+## Build or adopt
+
+Adopting a component costs bundle size, an API you did not design, and an upgrade you will owe
+later. Building costs the accessibility work you will get wrong.
+
+The split is not about difficulty, it is about **who is the authority on the behaviour**:
+
+- **Adopt** for behaviour with a specification you would otherwise be reimplementing badly: focus
+  trapping, combobox semantics, date handling, virtualisation.
+- **Build** for anything that is your product's own logic wearing a UI, or where the library gives
+  you 60% and you fight the remaining 40% forever.
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Put a filter or tab selection in component state | It belongs in the URL. Reload, share and back are part of the interface. |
+| Add a global store because passing props feels tedious | Tedious is not broken. Global state that one component reads is a leak with ceremony. |
+| Ship a screen with only the loaded state | Loading, empty, error and partial are not extras. The empty one is what a new user sees first. |
+| Split a component because the file got long | Length is not the defect. Two unrelated responsibilities are, and they are usually short. |
+| Show a delete as done before the server confirms | Optimism on a destructive action is a lie you will retract in public. |
+| Reach here for how the framework's hooks work | That is `../react/SKILL.md` or `../nextjs/SKILL.md`. This skill decides what to build; those decide how to express it. |
+
+## See Also
+
+- `../design/SKILL.md` — the visual system these decisions serve, its motion layer, and the
+  browser-measured critique that judges the result.
+- `../accessibility/SKILL.md` — the ground under focus, semantics and forms.

package/skills/shared/ui-engineering/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: ui-engineering
+
+should_trigger:
+  - prompt: "Where should the filter state live — component, context or the URL?"
+    why: "The canonical case: the one rule this skill exists to apply."
+  - prompt: "How should I split these components? The file is getting big."
+    why: "Component boundaries, and the file-length premise is one this skill corrects."
+  - prompt: "We only render the loaded state. What else does this screen need?"
+    why: "The five states are the checklist this skill owns."
+  - prompt: "¿Valido el formulario mientras escribe o al salir del campo?"
+    why: "Form behaviour, in Spanish; the trigger is the decision, not the language."
+  - prompt: "Should I use a component library for the date picker or build it?"
+    why: "Build vs adopt, decided by who owns the behaviour's specification."
+  - prompt: "Can we show the delete as done immediately and roll back if it fails?"
+    why: "Optimistic updates, and this is the case where the answer is no."
+
+should_not_trigger:
+  - prompt: "Design the pricing page — layout, type scale, the colour system."
+    route_to: "design"
+    why: "The visual system is decided before this layer has anything to build."
+  - prompt: "My useEffect runs twice in development and I don't understand why."
+    route_to: "react"
+    why: "Framework mechanics. This skill decides what to build, not how the framework behaves."
+  - prompt: "The dropdown animation feels cheap, what duration should it use?"
+    route_to: "design"
+    why: "Once the component exists, how it moves is motion craft."
+  - prompt: "Grade this dashboard and tell me if it is actually good."
+    route_to: "design"
+    why: "Judging a finished screen is the critique loop, not the build decisions."
+  - prompt: "Set up the Next.js App Router with server actions for this project."
+    route_to: "nextjs"
+    why: "Stack setup is the stack skill's; this one is framework-agnostic by construction."
+
+capability:
+  - prompt: "Our search page keeps its query and filters in component state. Users complain the back button loses everything. What is wrong and what is the fix?"
+    why: "The single most expensive instance of the one rule, stated as a real symptom rather than as theory."
+  - prompt: "This list screen shows a spinner, then rows. What states are we missing and why does each matter?"
+    why: "Forces the five-state checklist, including the empty state that a new user sees first."

package/skills/shared/unity/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: unity
+description: "Use when writing, reviewing or structuring Unity game code in C# for Unity 6 LTS — GameObjects and the Transform hierarchy, the MonoBehaviour lifecycle, prefabs and variants, ScriptableObjects for data, scenes and additive loading, the Input System, coroutines versus async and Awaitable, Addressables, and build settings for 2D and 3D. NOT Godot or GDScript (that is `godot`), NOT Unreal Blueprint or C++ engine work (that is `unreal`), NOT the netcode wire protocol (that is `gamedev-multiplayer`)."
+tags: [unity, csharp, game-dev, monobehaviour, input-system]
+recommends: [gamedev-multiplayer, gamedev-physics, gamedev-shaders, gamedev-pathing, gamedev-shipping, godot, unreal]
+profiles: [full]
+origin: ai-hub
+---
+
+# Unity + C# (Unity 6 LTS)
+
+> Idiomatic C# for the current Unity engine — 2D and 3D. Owns engine-side patterns (components,
+> lifecycle, prefabs, scenes, data, input, async, builds). Not Godot (`godot`) or Unreal (`unreal`);
+> stops at the netcode wire (`gamedev-multiplayer`).
+
+## Version contract — read first
+
+**Target: Unity 6 LTS, versioned `6000.x`.** Current LTS at authoring is **Unity 6.3 LTS (`6000.3`)**
+(supported to Dec 2027); **Unity 6.0 LTS (`6000.0`)** to Oct 2026. Unity 6 dropped the year-based names
+(2020/2021/2022 LTS) for the `6000.x` scheme. Confirm the project version in
+`ProjectSettings/ProjectVersion.txt` before assuming an API exists.
+
+**Ban-list — never emit these; use the modern replacement:**
+
+| Deprecated / removed | Use instead |
+| --- | --- |
+| `Input.GetAxis` / `GetKey` / `GetButton` (legacy Input Manager) | **new Input System** (`com.unity.inputsystem`): `InputActionAsset` / `InputAction` / `PlayerInput` — §6 |
+| `UnityEngine.Networking` (UNet), `NetworkServer`/`NetworkClient`, its `NetworkBehaviour` | **removed** since 2022.2. → **Netcode for GameObjects** (`com.unity.netcode.gameobjects`) + `gamedev-multiplayer` |
+| `Resources.Load(...)` for game content | **Addressables** (`com.unity.addressables`) — §8 |
+| `FindObjectOfType<T>()` / `FindObjectsOfType<T>()` | `FindFirstObjectByType<T>()` / `FindAnyObjectByType<T>()` / `FindObjectsByType<T>(FindObjectsSortMode.None)` (old ones obsolete since 2023.1) |
+| `WWW` | `UnityWebRequest` |
+| `OnGUI` / IMGUI for runtime game UI | **UI Toolkit** (runtime) or uGUI; keep IMGUI for editor tools only |
+| Setting `transform.position` on a `Rigidbody` in `Update` | `Rigidbody.MovePosition/MoveRotation` in `FixedUpdate` — §4 |
+| `GameObject.Find`/`FindWithTag` by string in `Update` | cache the ref in `Awake`, or `[SerializeField]` it |
+
+Prefer the new Input System even for single-player prototypes. Keep `Debug.Log` out of hot loops and
+strip it from ships.
+
+## 1. GameObject / Component model & Transform hierarchy
+
+A **GameObject** is an empty container; behaviour comes from **Components** you attach
+(`Transform`, `Rigidbody`, `MeshRenderer`, and your `MonoBehaviour` scripts). Every GameObject has
+exactly one `Transform` (or `RectTransform` under a Canvas) giving position/rotation/scale.
+
+- Get components: `TryGetComponent(out var rb)` (no-alloc, preferred), `GetComponent<T>()`,
+  `GetComponentInChildren/InParent<T>()`. Cache in `Awake` — `GetComponent` in `Update` is a perf sink.
+- Hierarchy: `transform.parent`, `transform.SetParent(newParent, worldPositionStays: true)`,
+  `transform.childCount`, `foreach (Transform child in transform)`. Child world = parent × local.
+- Same object model for 2D and 3D: 2D uses `Rigidbody2D`/`Collider2D`/`SpriteRenderer`; 3D uses
+  `Rigidbody`/`Collider`/`MeshRenderer`. Never mix 2D and 3D physics components on one body.
+
+```csharp
+[RequireComponent(typeof(Rigidbody))]
+public sealed class Mover : MonoBehaviour
+{
+    Rigidbody _rb;
+    void Awake() => _rb = GetComponent<Rigidbody>(); // cache once
+}
+```
+
+## 2. Prefabs & prefab variants; instantiation
+
+A **Prefab** is a reusable GameObject template (an asset). A **Prefab Variant** inherits from a base
+prefab and overrides selected properties/children — like subclassing for assets (e.g. `Enemy` base →
+`EnemyFast` variant). Edit the base and variants inherit the change unless they override that value.
+
+- Spawn with `Instantiate(prefab, position, rotation, parent)`; it returns the concrete type
+  (`var e = Instantiate(_enemyPrefab);` with `[SerializeField] Enemy _enemyPrefab;`). Store the
+  serialized reference; do not `Resources.Load` it.
+- Destroy with `Destroy(gameObject)` (end of frame) or `Destroy(obj, delay)`. Never `DestroyImmediate`
+  at runtime. For frequently spawned objects (bullets, VFX) **pool** them (`UnityEngine.Pool.ObjectPool<T>`)
+  instead of Instantiate/Destroy churn.
+- Editor-only prefab authoring uses `PrefabUtility` (wrap in `#if UNITY_EDITOR`); absent in builds.
+
+## 3. Scenes & scene management (additive loading)
+
+A **Scene** holds a set of GameObjects. Register scenes in **Build Profiles → Scene List** (Unity 6;
+formerly Build Settings) so they can load by index or name.
+
+```csharp
+using UnityEngine.SceneManagement;
+
+// Additive: keep the current scene, layer another on top (e.g. UI, a level chunk).
+var op = SceneManager.LoadSceneAsync("Level_02", LoadSceneMode.Additive);
+op.completed += _ => Debug.Log("Level_02 loaded");
+await op; // Unity 6: AsyncOperation is awaitable
+
+// Unload just that scene later:
+await SceneManager.UnloadSceneAsync("Level_02");
+```
+
+- `LoadSceneMode.Single` (default) unloads everything first; `Additive` composes scenes — the basis of
+  streaming worlds, persistent manager scenes, and separate UI scenes.
+- `SceneManager.MoveGameObjectToScene` moves an object between loaded scenes; `DontDestroyOnLoad` objects
+  survive `Single` loads (use for a bootstrap/services scene). Prefer `LoadSceneAsync` to avoid a hitch.
+
+## 4. MonoBehaviour lifecycle
+
+Order per frame and where each concern belongs (full ordering in `references/lifecycle-deep-dive.md`):
+
+| Method | When | Put here |
+| --- | --- | --- |
+| `Awake` | once, on instantiation (even if disabled) | cache `GetComponent`, self-init, no cross-object refs |
+| `OnEnable` | each time the object/component enables | subscribe to events, register callbacks |
+| `Start` | once, before first `Update`, only if active | cross-object wiring (other objects' `Awake` has run) |
+| `FixedUpdate` | fixed timestep (physics tick), 0..n / frame | **all physics** — `Rigidbody` forces/`MovePosition`, `ApplyForce` |
+| `Update` | every frame | input reads, game logic, timers (scale by `Time.deltaTime`) |
+| `LateUpdate` | every frame, after all `Update` | camera follow, look-at, anything tracking moved objects |
+| `OnDisable` | each disable / before destroy | **unsubscribe** everything subscribed in `OnEnable` |
+| `OnDestroy` | once, on destruction | release native/unmanaged resources, final cleanup |
+
+Rules that bite:
+- **Physics goes in `FixedUpdate`**, never `Update`. Reading input in `FixedUpdate` drops events —
+  read input in `Update`, cache intent, apply forces in `FixedUpdate`.
+- Frame-rate independence: multiply per-frame movement by `Time.deltaTime` (`Update`) — but
+  `FixedUpdate` already runs at a fixed `Time.fixedDeltaTime`.
+- `Awake` runs even on inactive objects; `Start` does not run until the object is active. Cross-object
+  references belong in `Start`, not `Awake`.
+- Every `OnEnable` subscription needs a matching `OnDisable` unsubscription or you leak and get
+  double-fires after re-enable.
+
+## 5. ScriptableObjects for data/config; serialization
+
+A **ScriptableObject** is a data asset that lives outside any scene — ideal for config, tuning tables,
+enemy/item definitions, and event channels. One asset is shared by reference (no per-instance copy),
+so it saves memory and lets designers tweak values without touching code.
+
+```csharp
+[CreateAssetMenu(fileName = "WeaponDef", menuName = "Game/Weapon Definition")]
+public sealed class WeaponDefinition : ScriptableObject
+{
+    [SerializeField] float _damage = 10f;
+    [SerializeField] float _fireRate = 2f;
+    public float Damage => _damage;      // expose read-only
+    public float FireRate => _fireRate;
+}
+```
+
+**`[SerializeField] private` vs `public`:** default to `[SerializeField] private` + a public
+property/method. It shows in the Inspector and survives serialization *without* letting arbitrary code
+mutate the field — encapsulation intact. Use bare `public` only for genuine data bags.
+
+**Serialization rules (they trip everyone):**
+- Unity serializes: `public` or `[SerializeField]` fields of supported types (primitives, `string`,
+  Unity types, enums, arrays/`List<T>` of those, and `[Serializable]` plain classes/structs).
+- Unity does **not** serialize: properties (use `[field: SerializeField] public float X { get; private set; }`),
+  `static`, `readonly`, `const`, `Dictionary<,>` (use two lists or a serializable wrapper), or
+  polymorphic references — for interface/abstract fields use `[SerializeReference]`.
+- Do not hold runtime mutable state on a shared ScriptableObject expecting it to reset — it persists in
+  the Editor between play sessions. Keep SOs for config; put mutable per-instance state on MonoBehaviours.
+
+## 6. Input System (new) — with a legacy contrast
+
+The new Input System (`com.unity.inputsystem`) is enabled by default in Unity 6 and is device-agnostic
+and event-driven. Define an **Input Action Asset** with **Action Maps** (e.g. "Player", "UI") and
+**Actions** (e.g. "Move" = Value/`Vector2`, "Jump" = Button). Generate a C# wrapper or use the
+`PlayerInput` component. Full setup, `PlayerInput`, and rebinding in `references/input-system.md`.
+
+```csharp
+// New Input System — subscribe to the generated actions (no per-frame polling).
+using UnityEngine.InputSystem;
+
+public sealed class PlayerController : MonoBehaviour
+{
+    InputSystem_Actions _controls;   // generated C# class from the .inputactions asset
+    Vector2 _move;
+
+    void Awake() => _controls = new InputSystem_Actions();
+    void OnEnable()
+    {
+        _controls.Player.Enable();
+        _controls.Player.Move.performed += ctx => _move = ctx.ReadValue<Vector2>();
+        _controls.Player.Move.canceled  += _  => _move = Vector2.zero;
+        _controls.Player.Jump.performed += _  => Jump();
+    }
+    void OnDisable() => _controls.Player.Disable();
+}
+```
+
+Legacy contrast (do not write this in new code):
+```csharp
+// LEGACY Input Manager — string axes, per-frame polling, device-blind. Avoid.
+float x = Input.GetAxis("Horizontal");
+if (Input.GetButtonDown("Jump")) Jump();
+```
+The new system also polls if you prefer: `_controls.Player.Move.ReadValue<Vector2>()` in `Update`.
+
+## 7. Coroutines vs async/await vs Awaitable
+
+| Use | Reach for | Why |
+| --- | --- | --- |
+| Frame-sequenced gameplay (timers, tweens, "wait then spawn") | **Coroutine** or **Awaitable** | frame-aware yields; auto-tie to object lifetime |
+| Unity-native async in Unity 6 (default for new async gameplay) | **`Awaitable`** | main-thread, low-alloc (pooled), frame + thread awaits, cancels via `destroyCancellationToken` |
+| True background CPU work / library `Task` APIs | **`async Task` + `await`** | thread pool; but marshal back — Unity APIs are main-thread only |
+
+```csharp
+// Coroutine — classic, MonoBehaviour-bound, stops when the object disables/destroys.
+IEnumerator SpawnWave()
+{
+    yield return new WaitForSeconds(1f);
+    Instantiate(_enemyPrefab);
+}
+void Start() => StartCoroutine(SpawnWave());
+
+// Awaitable (Unity 6) — the modern replacement. Cancels automatically on destroy.
+async Awaitable SpawnWaveAsync()
+{
+    await Awaitable.WaitForSecondsAsync(1f, destroyCancellationToken);
+    await Awaitable.NextFrameAsync(destroyCancellationToken);
+    Instantiate(_enemyPrefab);
+}
+```
+
+Rules:
+- **Coroutines** run only while the MonoBehaviour is enabled; they die silently on disable. No return
+  value; exceptions across `yield` are awkward.
+- **`Awaitable`**: never `await` the same instance twice (pooled → undefined behavior). Pass
+  `destroyCancellationToken` so it stops when the object is destroyed. Switch threads with
+  `Awaitable.BackgroundThreadAsync()` / `Awaitable.MainThreadAsync()`.
+- **`Task`**: does *not* auto-cancel on destroy — thread a `CancellationToken` yourself, and never touch
+  Unity API off the main thread (it throws). Prefer `Awaitable` in Unity 6 unless you need `Task`.
+
+## 8. Addressables (intro) + the Resources anti-pattern
+
+**Addressables** (`com.unity.addressables`) is the modern content-loading system: assets get string
+addresses, load asynchronously, and can ship in the build or from a remote CDN with dependency tracking
+and memory-managed release.
+
+```csharp
+using UnityEngine.AddressableAssets;
+
+var handle = Addressables.InstantiateAsync("Prefabs/Boss");
+GameObject boss = await handle.Task;      // or handle.Completed += ...
+// when done: Addressables.ReleaseInstance(boss);  // release to free memory
+```
+
+**`Resources/` is an anti-pattern for game content:** everything under it is forced into the build,
+loaded synchronously, bloats size/startup, and can't be patched or streamed. Reserve it for tiny
+always-needed defaults; migrate real content to Addressables.
+
+## 9. Build settings, platforms & player settings
+
+- **Build Profiles** (Unity 6, `File → Build Profiles`) supersede the old Build Settings window: per-platform
+  scene list, target platform, and overridable player settings.
+- **Scripting backend:** **IL2CPP** (AOT — required for iOS/consoles/WebGL, faster, harder to reverse)
+  vs **Mono** (JIT, Editor/desktop, faster iteration). Set per platform in Player Settings.
+- **Player Settings:** product/company name, bundle identifier, icons, orientation, API compatibility
+  level (`.NET Standard 2.1` default), managed stripping. **2D vs 3D** is a template choice, not a
+  different build path.
+- WebGL/mobile specifics and the shipping checklist: `references/build-and-platforms.md` + `gamedev-shipping`.
+
+## Guardrails / gotchas
+
+- `==`/`!= null` on a destroyed `UnityEngine.Object` works (overloaded), but `?.` and cached refs treat
+  a destroyed object as non-null. Re-check with `if (obj)` after possible destruction.
+- Don't mix input systems: with `PlayerInput`, don't also `Input.GetKey` — in "New" mode legacy calls throw.
+- One `Rigidbody` per body (child colliders fine); non-uniform scale breaks physics bodies.
+- Coroutines/`InvokeRepeating` stop on `SetActive(false)`; async `Task`s keep running unless cancelled.
+- No allocation (`new`, LINQ, boxing) in `Update`/`FixedUpdate` hot paths.
+
+## Related skills
+
+- `gamedev-multiplayer` — networking/netcode (Netcode for GameObjects); this skill hands off the wire.
+- `gamedev-physics` — deep physics tuning (joints, solver, determinism) beyond "put it in FixedUpdate".
+- `gamedev-shaders` — Shader Graph / HLSL, URP/HDRP materials and rendering.
+- `gamedev-pathing` — NavMesh, agents, steering, path solving.
+- `gamedev-shipping` — store builds, signing, size budgets, platform certification.
+- `godot` / `unreal` — the other engines; route Godot/GDScript and Unreal/Blueprint/C++ there.
+
+## Checklist
+
+- [ ] Confirmed the project's Unity version (`ProjectVersion.txt`); no year-based-LTS assumptions.
+- [ ] No banned API emitted (`Input.GetAxis`, `UnityEngine.Networking`, `Resources.Load` for content,
+      `FindObjectOfType`, `WWW`, runtime `OnGUI`).
+- [ ] `GetComponent` results cached in `Awake`; no string `Find` in `Update`.
+- [ ] Physics in `FixedUpdate`; input read in `Update`; camera/tracking in `LateUpdate`.
+- [ ] Every `OnEnable` subscription has a matching `OnDisable` unsubscription.
+- [ ] `[SerializeField] private` + property used instead of bare `public` where encapsulation matters.
+- [ ] New Input System used (actions/maps), not legacy polling; systems not mixed.
+- [ ] Async uses `Awaitable` (or coroutine) with `destroyCancellationToken`; no double-await.
+- [ ] Content via Addressables, not `Resources/`.
+- [ ] Scenes registered in Build Profiles; async/additive loading where it avoids a hitch.

package/skills/shared/unity/evals/README.md

@@ -0,0 +1,8 @@
+# unity evals
+
+These cases assert the skill fires on Unity/C# engine work (MonoBehaviour lifecycle, prefabs,
+ScriptableObjects, scenes, the new Input System, coroutines/async/Awaitable, Addressables, builds) and
+that it defers correctly: pathfinding→gamedev-pathing, shaders→gamedev-shaders, netcode→gamedev-multiplayer,
+Godot→godot, Unreal→unreal. Capability cases check current Unity 6 patterns (physics in FixedUpdate with
+Rigidbody.MovePosition, new Input System over Input.GetAxis, Awaitable + destroyCancellationToken, no
+double-await) rather than deprecated APIs.

package/skills/shared/unity/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: unity
+should_trigger:
+  - prompt: "My Unity player character teleports and jitters through walls when I move it with the arrow keys. Here's my MonoBehaviour."
+    why: "Physics-in-Update / setting transform on a Rigidbody — core lifecycle + FixedUpdate guidance this skill owns."
+  - prompt: "What's the difference between Awake and Start in Unity, and where should I grab my other components?"
+    why: "Directly the MonoBehaviour lifecycle section (Awake caches, Start does cross-object wiring)."
+  - prompt: "Help me convert my old Input.GetAxis(\"Horizontal\") movement to Unity's new Input System with an action map."
+    why: "Legacy→new Input System migration; ban-list + §6/input-system reference."
+  - prompt: "I want to store all my enemy stats (health, speed, damage) as data assets I can tweak in the Inspector. Best way in Unity?"
+    why: "ScriptableObject for data/config + [SerializeField] vs public + serialization rules."
+  - prompt: "How do I load a second Unity scene on top of the current one for my UI without unloading the level?"
+    why: "Scenes & additive loading (LoadSceneAsync + LoadSceneMode.Additive)."
+  - prompt: "Should I use a coroutine, async Task, or Awaitable for a 'wait 2 seconds then spawn' timer in Unity 6?"
+    why: "Coroutines vs async/await vs Awaitable decision — §7, including destroyCancellationToken."
+  - prompt: "Setting up multiplayer in Unity — I found UNet / UnityEngine.Networking tutorials, do they still work?"
+    why: "Version contract: UNet removed → Netcode for GameObjects; routes the wire itself onward but Unity owns the 'it's removed' fact."
+should_not_trigger:
+  - prompt: "How do I write a NavMeshAgent that chases the player and avoids obstacles smoothly?"
+    route_to: "gamedev-pathing"
+    why: "Pathfinding/steering algorithms are the pathing skill; Unity only owns the component wiring."
+  - prompt: "Design a Shader Graph for a dissolving-enemy effect with an emissive edge in URP."
+    route_to: "gamedev-shaders"
+    why: "Shader/material authoring belongs to the shaders skill."
+  - prompt: "I'm making a game in Godot 4 with GDScript and my _ready() isn't firing."
+    route_to: "godot"
+    why: "Godot/GDScript engine — explicitly out of scope; route to godot."
+  - prompt: "In Unreal Engine 5 my Blueprint Actor won't replicate movement to clients."
+    route_to: "unreal"
+    why: "Unreal/Blueprint engine work — route to unreal."
+  - prompt: "Write the authoritative server tick and client-side prediction/reconciliation for our netcode."
+    route_to: "gamedev-multiplayer"
+    why: "Netcode protocol/authority design is the multiplayer skill; Unity stops at 'use Netcode for GameObjects'."
+capability:
+  - scenario: "User asks how to move a Rigidbody with input from the new Input System without jitter, in Unity 6."
+    must_include:
+      - "reads input in Update (caches intent) but applies movement in FixedUpdate"
+      - "uses Rigidbody.MovePosition (or AddForce), not setting transform.position on the body"
+      - "uses the new Input System (InputAction / action map / ReadValue<Vector2>), not Input.GetAxis"
+  - scenario: "User asks whether to use a coroutine or async for a delayed spawn and how to make it stop when the object is destroyed."
+    must_include:
+      - "recommends Awaitable (or coroutine) over raw Task for Unity gameplay in Unity 6"
+      - "passes destroyCancellationToken to the Awaitable so it cancels on destroy"
+      - "warns never to await the same Awaitable instance twice (it is pooled)"

package/skills/shared/unity/references/build-and-platforms.md

@@ -0,0 +1,65 @@
+# Build, platforms & player settings (Unity 6)
+
+Reference: Unity Manual "Build Profiles", "Player Settings", "IL2CPP".
+
+## Build Profiles (Unity 6) — replaces the old Build Settings window
+
+`File → Build Profiles`. A **Build Profile** is a saved, per-platform configuration:
+- **Scene List** — which scenes are included and their build index (index 0 = first/boot scene). Scenes
+  not in the list can only be loaded Additively if already present, so register everything you load.
+- **Target platform & architecture** — Windows/macOS/Linux, Android, iOS, WebGL, consoles.
+- **Overrides** — a profile can override Player Settings (e.g. a "Demo" profile with a different bundle id).
+
+`Shared Settings` hold the defaults; each profile diffs from them. Build with `Build` or `Build And Run`.
+Headless/CI builds go through `BuildPipeline.BuildPlayer` in an editor script.
+
+## Scripting backend: IL2CPP vs Mono
+
+`Player Settings → Configuration → Scripting Backend`:
+
+| | IL2CPP | Mono |
+| --- | --- | --- |
+| How | C# → IL → C++ → native (AOT) | JIT at runtime |
+| Platforms | required for iOS, WebGL, consoles; available desktop/Android | Editor + desktop + Android |
+| Runtime speed | faster | slower |
+| Build time | slower | faster (good for iteration) |
+| Reverse-engineering | harder | easier |
+| Reflection/`dynamic` | AOT limits (no runtime codegen; `System.Reflection.Emit` unsupported) | full |
+
+Ship production builds on **IL2CPP**; iterate in the Editor (always Mono/interpreted). IL2CPP + AOT means
+generic code reached only via reflection can be stripped — see managed stripping below.
+
+## Player Settings essentials
+
+- **Identity**: Company Name, Product Name, **bundle identifier** (`com.company.game` — must match store
+  listing), version + build/bundle number.
+- **Icons & splash**, default orientation (mobile), resolution/presentation.
+- **API Compatibility Level**: `.NET Standard 2.1` (default, smaller) vs `.NET Framework` (broader API,
+  larger). Prefer Standard unless a dependency needs Framework.
+- **Managed Stripping Level** (`Minimal`/`Low`/`Medium`/`High`): strips unused IL to shrink builds. High
+  can strip types only used via reflection/serialization — preserve them with a `link.xml` or
+  `[Preserve]`.
+- **Graphics APIs** per platform (Vulkan/Metal/D3D12/GLES3/WebGPU), color space (Linear recommended).
+
+## Platform quick-notes
+
+- **WebGL**: IL2CPP only; **no multithreading by default** (so `System.Threading`/most `Task`
+  parallelism is unavailable — `Awaitable` frame awaits are fine); no synchronous file I/O; build size
+  and memory matter; use compression (Brotli/Gzip) + a server that serves the right headers.
+- **Android**: set target/min SDK, choose ARM64 (required for Play Store), build **AAB** for the store
+  (APK for sideload). Configure keystore signing.
+- **iOS**: Unity emits an Xcode project; sign & archive in Xcode. IL2CPP + ARM64.
+- **Desktop**: simplest; Mono or IL2CPP.
+
+## Rendering pipeline choice (affects builds & shaders)
+
+- **URP** (Universal RP) — default for most 2D/3D projects, scales phone→desktop.
+- **HDRP** — high-end desktop/console visuals.
+- **Built-in** — legacy; new projects should pick URP/HDRP.
+
+Pipeline choice changes materials and shader authoring — see the `gamedev-shaders` skill.
+
+## Handoff
+
+Store submission, signing, size budgets, certification, and release ops belong to the `gamedev-shipping`
+skill. This reference stops at producing a correct platform build from the Editor.

package/skills/shared/unity/references/input-system.md

@@ -0,0 +1,102 @@
+# Input System (new) — setup, patterns, migration
+
+Package: `com.unity.inputsystem`. Enabled by default in Unity 6. Device-agnostic, event-driven,
+supports rebinding, composites, local multiplayer, and touch. Reference: Unity Input System package
+manual.
+
+## Project mode
+
+`Edit → Project Settings → Player → Active Input Handling`:
+- **Input System Package (New)** — legacy `Input.*` calls throw. Recommended for new projects.
+- **Both** — new + legacy coexist (migration only; avoid mixing per-feature).
+- **Input Manager (Old)** — legacy only. Do not target for new work.
+
+Unity 6 also has **Project-wide Actions** (`Edit → Project Settings → Input System Package`): a default
+`InputActionAsset` shared across the whole project, reachable via `InputSystem.actions`.
+
+## Anatomy
+
+- **Input Action Asset** (`.inputactions`): the container. Enable "Generate C# Class" in its importer to
+  get a strongly-typed wrapper (e.g. `InputSystem_Actions`).
+- **Action Map**: a group of actions active together — e.g. "Player", "UI", "Vehicle". Enable/disable
+  maps to switch context (`_controls.Player.Disable(); _controls.UI.Enable();`).
+- **Action**: a named input with a **type**:
+  - *Value* (continuous, e.g. `Vector2` Move) — `performed` fires on change, `ReadValue<T>()`.
+  - *Button* (Jump, Fire) — `started` / `performed` / `canceled` phases.
+  - *Pass-Through* (raw device, every event).
+- **Binding**: the physical control → action. **Composite** bindings combine controls, e.g. a "2D Vector"
+  composite maps W/A/S/D to a single `Vector2`. **Control schemes** group bindings per device set
+  (Keyboard&Mouse, Gamepad).
+
+## Three ways to consume input
+
+### 1. Generated C# class (recommended for a single player)
+
+```csharp
+using UnityEngine.InputSystem;
+
+public sealed class PlayerController : MonoBehaviour
+{
+    InputSystem_Actions _controls;
+    Vector2 _move;
+
+    void Awake() => _controls = new InputSystem_Actions();
+    void OnEnable()
+    {
+        _controls.Player.Enable();
+        _controls.Player.Move.performed += OnMove;
+        _controls.Player.Move.canceled  += OnMove;
+        _controls.Player.Jump.performed += _ => Jump();
+    }
+    void OnDisable()
+    {
+        _controls.Player.Move.performed -= OnMove;
+        _controls.Player.Move.canceled  -= OnMove;
+        _controls.Player.Disable();
+    }
+    void OnDestroy() => _controls.Dispose();   // it owns native resources
+    void OnMove(InputAction.CallbackContext ctx) => _move = ctx.ReadValue<Vector2>();
+}
+```
+
+### 2. Polling (when event-driven feels heavy)
+
+```csharp
+Vector2 move = _controls.Player.Move.ReadValue<Vector2>();
+bool jumped  = _controls.Player.Jump.WasPressedThisFrame();   // edge-triggered, read in Update
+```
+
+### 3. `PlayerInput` component (fastest wiring, local multiplayer)
+
+Attach `PlayerInput`, assign the action asset, pick a **Behavior**:
+- *Send Messages* / *Broadcast Messages* — calls `OnMove(InputValue)` etc. by name.
+- *Invoke Unity Events* — wire in the Inspector.
+- *Invoke C# Events* — subscribe in code.
+
+For local co-op, `PlayerInputManager` spawns a `PlayerInput` per joined device, isolating each player's
+action instance and pairing devices automatically.
+
+## Rebinding at runtime
+
+```csharp
+var rebind = _controls.Player.Jump.PerformInteractiveRebinding()
+    .WithControlsExcluding("Mouse")
+    .OnComplete(op => { op.Dispose(); SaveBindings(); })
+    .Start();
+// Persist: string json = _controls.asset.SaveBindingOverridesAsJson();
+// Restore: _controls.asset.LoadBindingOverridesFromJson(json);
+```
+
+## Migration from legacy
+
+| Legacy | New Input System |
+| --- | --- |
+| `Input.GetAxis("Horizontal")` | Move action (Value/`Vector2`) → `ReadValue<Vector2>().x` |
+| `Input.GetButtonDown("Jump")` | Jump action (Button) → `WasPressedThisFrame()` or `performed` |
+| `Input.GetKey(KeyCode.E)` | action bound to `<Keyboard>/e` → `IsPressed()` |
+| `Input.mousePosition` | `Mouse.current.position.ReadValue()` |
+| `Input.GetMouseButtonDown(0)` | `Mouse.current.leftButton.wasPressedThisFrame` |
+| `Input.touchCount` / `Input.GetTouch` | `Touchscreen.current` / Enhanced Touch API |
+
+Do not leave `Input.*` polling alongside new-system actions — in "New" mode the legacy calls throw, and
+in "Both" mode you double-handle the same physical input.