@deftai/directive-content 0.55.0

package/platforms/2600.md

@@ -0,0 +1,137 @@
+# Atari 2600 (VCS) Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md)
+
+## Hardware Reference
+
+- **CPU**: MOS 6507 (6502 variant), ~1.19 MHz (NTSC), ~1.18 MHz (PAL)
+- **RAM**: 128 bytes ($80–$FF) via RIOT (6532)
+- **ROM**: 4 KB standard cartridge (2 KB–32 KB+ via bankswitching)
+- **Video**: TIA (Television Interface Adapter) — no framebuffer
+- **TIA clock**: 3× CPU clock (228 color clocks/scanline, 76 CPU cycles/scanline)
+- **Display**: 160×192 visible pixels (NTSC), 160×242 (PAL)
+- **Sprites**: 2 players (8 px), 2 missiles (1 px), 1 ball (1 px)
+- **Playfield**: 20 bits wide, mirrored or copied to fill 40 bits (160 px)
+- **Audio**: 2 channels, 4-bit volume, 4-bit frequency, 4-bit waveform
+
+## Toolchain
+
+### Assembler
+- ! Use [DASM](https://dasm-assembler.github.io/) macro assembler
+- ! Include `vcs.h` and `macro.h` in all source files
+- ! Assemble with `-f3` (raw binary, no header)
+- ? Use VS Code with the `dasm-macro-assembler` extension
+
+### Emulator
+- ! Use [Stella](https://stella-emu.github.io/) as the primary development emulator
+- ! Enable Stella's developer settings (jitter/roll simulation) during testing
+- ~ Use Stella's built-in debugger for cycle counting and scanline verification
+
+### Alternative Languages
+- ? Use [batari Basic](https://www.randomterrain.com/atari-2600-memories-batari-basic-commands.html) for rapid prototyping
+- ? Use DPC+ / CDFJ coprocessor via Harmony/UnoCart for advanced projects
+
+## Standards
+
+### Initialization
+- ! Clear all RAM and TIA registers at startup (use `CLEAN_START` macro from `macro.h`)
+- ! Set the stack pointer explicitly (`LDX #$FF; TXS`)
+- ⊗ Assume any known state of RAM, TIA, or CPU registers at power-on
+
+### Frame Structure (NTSC)
+- ! Produce exactly 262 scanlines per frame (3 VSYNC + 37 VBLANK + 192 visible + 30 overscan)
+- ! Begin each frame with 3 scanlines of VSYNC (`STA VSYNC` with bit 1 set)
+- ! Maintain a consistent scanline count across all code paths in every frame
+- ≉ Deviate from 262 lines — variable counts cause visible rolling/jitter on real hardware
+
+### Frame Structure (PAL)
+- ! Produce exactly 312 scanlines per frame (3 VSYNC + 45 VBLANK + 242 visible + 22 overscan)
+- ! Always produce an **even** number of total scanlines (odd counts lose color on PAL TVs)
+- ~ Provide separate NTSC and PAL builds with appropriate color palettes
+
+### TV Compatibility
+- ! Target 262 scanlines (NTSC) or 312 scanlines (PAL) exactly
+- ~ Keep visible content within the safe area (avoid first/last ~8 scanlines of the picture region)
+- ~ Test with Stella's jitter simulation enabled to catch timing issues before hardware testing
+- ~ Test on real hardware (CRT television) before release
+
+### Kernel (Display Loop)
+- ! Account for exactly 76 CPU cycles per scanline in all kernel code
+- ! Use `STA WSYNC` to synchronize to scanline boundaries
+- ! Document cycle counts inline for every instruction in tight kernel sections
+- ~ Use the Y register as the scanline counter (required for indirect indexed addressing `LDA (zp),Y`)
+- ~ Store sprite data bottom-up in ROM for natural kernel scanning order
+- ≉ Perform game logic during the visible kernel — use VBLANK and overscan periods instead
+- ⊗ Exceed 76 cycles between WSYNC strobes without accounting for the extra scanline(s)
+
+### Cycle Counting
+- ! Count and annotate CPU cycles in all time-critical code (kernel, positioning routines)
+- ! Account for the extra cycle on page-boundary crossings with `(Indirect),Y` addressing
+- ~ Align data tables to avoid page-boundary penalties in kernel loops
+- ~ Use constant-cycle-count code paths (pad shorter branches with NOPs or `SLEEP` macro)
+
+### Horizontal Positioning
+- ! Issue `STA HMOVE` immediately after `STA WSYNC` (within HBLANK)
+- ! Wait at least 24 CPU cycles after HMOVE before modifying any motion registers (HMPx/HMMx/HMBL)
+- ! Clear motion registers with `STA HMCLR` before setting new values
+- ~ Use the divide-by-15 loop technique for coarse positioning with HMOVE fine adjustment
+- ? Use `STA RESP0,X` timing loop for multi-object positioning
+
+### Vertical Positioning
+- ~ Use the "skipdraw" technique: compare scanline counter to sprite Y position in kernel
+- ~ Pre-calculate sprite pointers during VBLANK to minimize kernel overhead
+
+### Memory Management
+- ! Treat all 128 bytes of RAM as precious — plan allocation carefully
+- ~ Use zero-page addressing ($80–$FF) for all variables (saves 1 byte and 1 cycle vs. absolute)
+- ~ Reuse RAM locations across non-overlapping game states
+- ⊗ Use the stack for deep call chains — the stack shares the 128-byte RAM space
+
+### ROM Management
+- ! Place reset vector at $FFFC–$FFFD and interrupt vector at $FFFE–$FFFF
+- ! For ROMs > 4 KB, use well-known bankswitching schemes (F8, F6, F4, etc.)
+- ~ Keep the most time-critical code (kernel) in a single bank to avoid mid-scanline bank switches
+- ~ Place lookup tables in the same bank as the code that references them
+- ? Use Superchip (128 bytes extra RAM) for games needing more working memory
+
+### Code Quality
+- ! Comment all TIA register writes with the purpose and expected timing
+- ~ Label all major sections: VSYNC, VBLANK, Kernel, Overscan
+- ~ Use DASM macros and `REPEAT`/`REPEND` to reduce repetitive code
+- ~ Use meaningful labels and constants from `vcs.h` (never write to magic addresses directly)
+- ≉ Use undocumented 6502 opcodes unless targeting specific hardware and documenting the risk
+
+### Sound
+- ! Turn off sound by setting `AUDV0`/`AUDV1` to 0 (not `AUDC0`/`AUDC1` — the latter causes artifacts on SECAM)
+- ~ Update audio registers during VBLANK or overscan, not mid-kernel
+- ? Use a music sequencer driver for multi-voice music
+
+### Testing & Debugging
+- ! Verify scanline count in Stella (Developer → Video → Frame Stats overlay)
+- ! Test both player difficulty switch positions (A/B)
+- ! Test color/BW switch behavior
+- ~ Test with Stella's phosphor mode for games using sprite flicker
+- ~ Test on real hardware with Harmony/UnoCart cartridge before physical release
+- ~ Disassemble and study classic games for proven techniques (use DiStella)
+- ? Test on multiple TIA revisions if targeting broad hardware compatibility
+
+### Anti-Patterns
+- ⊗ Write to TIA registers at unpredictable or variable cycle positions within a scanline
+- ⊗ Assume the electron beam position without explicit WSYNC synchronization
+- ⊗ Ignore HMOVE timing constraints (causes visual corruption / "HMOVE bars")
+- ⊗ Use absolute addressing for variables in the $80–$FF range (wastes ROM and cycles)
+- ⊗ Produce ROMs with sizes that don't match standard cartridge formats (2K, 4K, 8K, 16K, 32K)
+- ⊗ Hard-code color values without considering NTSC/PAL/SECAM palette differences
+
+## Resources
+
+- [Stella Programmer's Guide](https://alienbill.com/2600/101/docs/stella.html) — official TIA/RIOT register reference
+- [6502.org](http://www.6502.org/) — 6502 instruction set, addressing modes, and tools
+- [AtariAge 2600 Programming Forum](https://forums.atariage.com/forum/50-atari-2600-programming/) — community support
+- [Nick Bensema's Guide to Cycle Counting](https://www.randomterrain.com/atari-2600-memories-guide-to-cycle-counting.html)
+- [Andrew Davie's 2600 Programming for Newbies](https://www.randomterrain.com/atari-2600-memories-tutorial-andrew-davie-01.html)
+- [2600 Advanced Programming Guide](https://www.qotile.net/minidig/docs/2600_advanced_prog_guide.txt) — bankswitching, skipdraw, HMOVE tricks
+- [TIA Color Charts](https://www.randomterrain.com/atari-2600-memories-tia-color-charts.html) — NTSC/PAL/SECAM palettes
+- [Cart Sizes and Bankswitching Methods](https://www.randomterrain.com/atari-2600-memories-tutorial-andrew-davie-25.html) — Kevin Horton's reference

package/platforms/unity.md

@@ -0,0 +1,329 @@
+# Unity Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [PROJECT.md](../../PROJECT.md) | [csharp.md](../languages/csharp.md)
+
+**Stack**: Unity 6+, C# (see [csharp.md](../languages/csharp.md) for general C# rules); Rendering: URP (default) or HDRP; Testing: Unity Test Framework (NUnit); Asset Management: Addressables
+
+**Note**: Rules in [csharp.md](../languages/csharp.md) apply to all Unity C# code. This file covers Unity-specific overrides and additions.
+
+## Standards
+
+### Project Structure
+
+- ! Use Assembly Definition files (`.asmdef`) for all script folders — separate Runtime, Editor, and Tests
+- ! Organize by feature or domain (`Player/`, `UI/`, `Audio/`, `Networking/`), not by type (`Scripts/`, `Prefabs/`)
+- ! Place all project assets under a top-level folder named after the project (e.g., `Assets/MyGame/`)
+- ! Match namespaces to folder structure
+- ! One public class per file; filename matches the class name
+- ~ Use a consistent asset naming convention: `Prefix_BaseAssetName_Variant_Suffix`
+- ~ Keep a `_Shared/` or `Common/` folder for cross-feature assets
+- ⊗ Leave loose assets in `Assets/` root
+
+### Naming Conventions (Unity-Specific)
+
+- ! `PascalCase` for MonoBehaviours, ScriptableObjects, classes, methods, properties, events
+- ! `camelCase` for parameters and local variables
+- ! `_camelCase` for private/protected fields
+- ! `[SerializeField] private` fields instead of `public` for Inspector-exposed values
+- ! Use `[Header("Section")]` and `[Tooltip("Description")]` to document Inspector fields
+- ~ Suffix scripts by role: `*Controller`, `*Manager`, `*System`, `*Data`, `*Settings`, `*Editor`
+- ~ Use `I` prefix for interfaces: `IDamageable`, `IInteractable`
+- ⊗ Hungarian notation or type prefixes (`strName`, `intCount`, `goPlayer`)
+
+### MonoBehaviour Guidelines
+
+- ! Keep MonoBehaviours thin — glue between data/systems and visuals only
+- ! Cache component references in `Awake()` or `OnEnable()`; ⊗ call `GetComponent<T>()` in `Update()`
+- ! Remove empty Unity lifecycle methods (`Update()`, `Start()`, etc.) — they have overhead even when empty
+- ! Order members: Fields → Properties → Events → Unity Lifecycle → Public Methods → Private Methods
+- ~ Use `[RequireComponent(typeof(T))]` to enforce dependencies
+- ~ Use `[DisallowMultipleComponent]` where only one instance makes sense
+- ≉ Use `Awake()` for cross-object dependencies; use `Start()` or lazy init instead
+- ⊗ Use `SendMessage()`, `BroadcastMessage()`, or `Invoke()` with string method names
+
+### ScriptableObjects
+
+- ! Use ScriptableObjects for shared configuration, game data, and design-tunable parameters
+- ! Use `[CreateAssetMenu]` attribute for designer-facing ScriptableObjects
+- ~ Use ScriptableObject-based events for decoupled inter-system communication (observer pattern)
+- ~ Use ScriptableObject variables (e.g., `FloatVariable`, `IntVariable`) for shared runtime state
+- ~ Copy runtime values from ScriptableObject data to avoid persisting play-mode changes to disk
+- ~ Favor ScriptableObjects over singletons for global state and cross-scene data
+- ≉ Store mutable per-instance state in ScriptableObjects (they are shared assets)
+
+### Architecture & Patterns
+
+- ! Favor composition over inheritance for game behaviors
+- ! Apply SOLID principles; keep classes single-responsibility
+- ! Use event-driven communication (C# events, ScriptableObject events, or `UnityEvent`) over direct references
+- ~ Use dependency injection (VContainer or similar) for testable architecture
+- ~ Use interfaces to define contracts between systems
+- ~ Hybrid approach: GameObjects for scene logic + Jobs/Burst for compute-heavy paths
+- ≉ Deep MonoBehaviour inheritance hierarchies (prefer composition)
+- ≉ Global singletons as primary architecture — use ScriptableObjects or DI instead
+- ? Use ECS/DOTS for entity-heavy systems (physics, AI, large simulations)
+
+### Performance & Memory
+
+- ! Profile first — use Unity Profiler and Project Auditor before optimizing
+- ! Eliminate per-frame heap allocations in hot paths (Update, FixedUpdate, coroutines)
+- ! Use object pooling (`UnityEngine.Pool.ObjectPool<T>`) for frequently spawned/despawned objects
+- ! Cache all expensive lookups: `GetComponent<T>()`, `Camera.main`, `Transform` references
+- ! Cache `WaitForSeconds` and other yield instructions in coroutines
+- ! Use non-allocating Physics APIs: `Physics.RaycastNonAlloc()`, `Physics.OverlapSphereNonAlloc()`
+- ~ Reuse collections (`List<T>`, `StringBuilder`, arrays) instead of allocating new ones
+- ~ Use `Span<T>` and `ReadOnlySpan<T>` for zero-allocation slicing
+- ~ Prefer structs for small data-only types on hot paths
+- ~ Use Jobs + Burst Compiler for heavy math, physics, AI, and procedural generation
+- ~ Use `Awaitable` (Unity 6+, pooled, player-loop aware) over raw `Task` for async
+- ≉ Use LINQ, reflection, or string concatenation in hot paths
+- ⊗ Call `GameObject.Find()`, `FindObjectOfType()`, or `FindObjectsOfType()` at runtime in hot paths
+- ⊗ Use `Resources.Load()` at runtime — use Addressables instead
+
+### Asset Management
+
+- ! Use Addressables for all runtime asset loading in production projects
+- ! Set up asset groups with sensible packing strategies (by label, scene, feature)
+- ! Release loaded Addressables when no longer needed to free memory
+- ~ Pre-warm object pools during loading screens or scene initialization
+- ~ Use texture compression appropriate to target platform (ASTC for mobile, BC7 for desktop)
+- ~ Enable mipmaps for 3D textures; disable for UI/2D sprites
+- ~ Use Sprite Atlases for 2D/UI to reduce draw calls
+- ≉ Use `Resources/` folder for production assets (non-strippable, increases build size)
+
+### Rendering
+
+- ! Choose render pipeline at project start: URP (default/mobile) or HDRP (high-fidelity)
+- ! Use SRP Batcher–compatible shaders for draw call optimization
+- ! Implement LOD (Level of Detail) for 3D assets
+- ! Use occlusion culling for complex 3D scenes
+- ~ Enable GPU Instancing for repeated meshes (foliage, debris, crowds)
+- ~ Use static batching for non-moving geometry
+- ~ Use Shader Graph for custom shaders; avoid hand-written shaders unless performance demands it
+- ~ Set per-platform quality levels and resolution scaling
+- ? Use UI Toolkit for new UI work; uGUI for legacy or simple use cases
+
+### Unity-Specific C# Gotchas
+
+- ! Use `if (myUnityObject == null)` — Unity overrides `==` on `UnityEngine.Object` (fake null)
+- ! Use `Object.Destroy()` at runtime; `DestroyImmediate()` is Editor-only
+- ! All Unity API calls must execute on the main thread
+- ! Guard Editor-only code with `#if UNITY_EDITOR` and separate Assembly Definitions
+- ! Use `CompareTag("Tag")` instead of `gameObject.tag == "Tag"` (avoids allocation)
+- ⊗ Use `ReferenceEquals(obj, null)` or `is null` on UnityEngine.Object types
+- ⊗ Use C# finalizers (`~ClassName()`) in runtime code
+- ⊗ Use `async void` — use `async Awaitable` (Unity 6+) or coroutines
+
+### Testing
+
+See [testing.md](../coding/testing.md) for universal testing requirements.
+
+- ! Use Unity Test Framework (NUnit-based) for all automated tests
+- ! Separate Edit Mode and Play Mode tests into distinct assemblies (`.asmdef`)
+- ! Use `[Test]` for synchronous logic; `[UnityTest]` only when yielding frames or time
+- ! Test assemblies must reference production assemblies via Assembly Definitions
+- ~ Write Edit Mode tests for pure logic, ScriptableObject behavior, and Editor extensions
+- ~ Write Play Mode tests for runtime behaviors, physics, coroutines, and integration
+- ~ Use `LogAssert.Expect()` before log-emitting code under test
+- ~ Run tests in CI via batch mode: `-batchmode -runTests -testPlatform EditMode`
+- ~ Install Code Coverage package (`com.unity.testtools.codecoverage`) for coverage reports
+- ? Run Play Mode tests on target platform builds for platform-specific validation
+
+### Coverage
+
+- ! ≥75% coverage for runtime logic assemblies
+- ! Exclude Editor scripts, generated code, and third-party plugins from coverage
+- ~ Prioritize coverage on gameplay systems, state machines, and data processing
+
+### Editor Workflow
+
+- ! Enable "Enter Play Mode Options" (disable Domain Reload) for fast iteration
+- ! Manually reset all static fields when Domain Reload is disabled
+- ~ Use Roslyn analyzers and `.editorconfig` for code style enforcement
+- ~ Use custom Editor tools and PropertyDrawers to improve designer workflows
+- ~ Use `[ContextMenu("...")]` for quick debug actions on components
+- ? Use Presets for standardizing import settings across asset types
+
+### Source Control
+
+- ! Use a Unity-appropriate `.gitignore` (exclude `Library/`, `Temp/`, `Logs/`, `obj/`)
+- ! Set Asset Serialization to "Force Text" (Project Settings → Editor)
+- ! Enable Visible Meta Files (Project Settings → Editor → Version Control Mode)
+- ! Use `.gitattributes` to mark binary assets (textures, audio, models) with Git LFS
+- ~ Use Smart Merge (UnityYAMLMerge) for scene and prefab conflict resolution
+- ~ Commit `.meta` files alongside their assets — never delete one without the other
+
+### Native Plugins (C++/Rust)
+
+- ~ Only reach for native plugins when Jobs + Burst is insufficient
+- ! Expose a C-style interface (`extern "C"`) to avoid name mangling
+- ! Use `[DllImport("PluginName")]` in C# (`"__Internal"` for iOS)
+- ! Minimize P/Invoke boundary crossings — batch work inside the native library
+- ! Place platform-specific binaries in correct `Plugins/` subfolders
+- ? Prefer Rust over C++ for new native plugins (memory safety, fewer crashes)
+
+### Safety
+
+- ⊗ Hardcode secrets, API keys, or credentials in source or ScriptableObjects
+- ! Validate all external input (network data, user input, file I/O)
+- ~ Scan third-party packages for vulnerabilities before importing
+- ~ Use signed packages (Unity 6.3+) and verify trust indicators in Package Manager
+
+## Anti-Patterns
+
+Items marked ⊗ in Standards above are not repeated here.
+
+- ≉ **God MonoBehaviours**: Split large scripts (>300 lines) into focused components
+- ≉ **Deep inheritance**: Favor composition and interfaces over class hierarchies
+- ≉ **String-based identification**: Use enums, ScriptableObject references, or tags — not magic strings
+- ≉ **Scene-dependent singletons**: Use ScriptableObjects or DI for cross-scene state
+- ≉ **Resources folder**: Use Addressables for runtime loading
+- ≉ **Coroutines for everything**: Use `async/Awaitable` (Unity 6+) for non-frame-dependent async
+- ≉ **Manual `new` for poolable objects**: Use `ObjectPool<T>` or Addressables pooling
+
+## Patterns
+
+### ScriptableObject Variable
+
+```csharp
+[CreateAssetMenu(menuName = "Variables/Float")]
+public class FloatVariable : ScriptableObject
+{
+    [SerializeField] private float _initialValue;
+
+    [System.NonSerialized] public float RuntimeValue;
+
+    private void OnEnable() => RuntimeValue = _initialValue;
+}
+```
+
+### ScriptableObject Event
+
+```csharp
+[CreateAssetMenu(menuName = "Events/Game Event")]
+public class GameEvent : ScriptableObject
+{
+    private readonly List<GameEventListener> _listeners = new();
+
+    public void Raise()
+    {
+        for (int i = _listeners.Count - 1; i >= 0; i--)
+            _listeners[i].OnEventRaised();
+    }
+
+    public void Register(GameEventListener listener) => _listeners.Add(listener);
+    public void Unregister(GameEventListener listener) => _listeners.Remove(listener);
+}
+
+public class GameEventListener : MonoBehaviour
+{
+    [SerializeField] private GameEvent _event;
+    [SerializeField] private UnityEvent _response;
+
+    private void OnEnable() => _event.Register(this);
+    private void OnDisable() => _event.Unregister(this);
+    public void OnEventRaised() => _response.Invoke();
+}
+```
+
+### Object Pooling (Unity 2021+)
+
+```csharp
+public class ProjectilePool : MonoBehaviour
+{
+    [SerializeField] private Projectile _prefab;
+    private ObjectPool<Projectile> _pool;
+
+    private void Awake()
+    {
+        _pool = new ObjectPool<Projectile>(
+            createFunc: () => Instantiate(_prefab),
+            actionOnGet: p => p.gameObject.SetActive(true),
+            actionOnRelease: p => p.gameObject.SetActive(false),
+            actionOnDestroy: p => Destroy(p.gameObject),
+            defaultCapacity: 20,
+            maxSize: 100
+        );
+    }
+
+    public Projectile Get() => _pool.Get();
+    public void Release(Projectile p) => _pool.Release(p);
+}
+```
+
+### Cached Component References
+
+```csharp
+[RequireComponent(typeof(Rigidbody))]
+public class PlayerMovement : MonoBehaviour
+{
+    private Rigidbody _rb;
+    private Transform _transform;
+
+    private void Awake()
+    {
+        _rb = GetComponent<Rigidbody>();
+        _transform = transform; // Cache the property accessor
+    }
+
+    private void FixedUpdate()
+    {
+        // Use cached references — never GetComponent in Update/FixedUpdate
+        _rb.AddForce(_transform.forward * 10f);
+    }
+}
+```
+
+### Play Mode Test
+
+```csharp
+[UnityTest]
+public IEnumerator Rigidbody_WithGravity_FallsOverTime()
+{
+    var go = new GameObject("TestObj");
+    go.AddComponent<Rigidbody>();
+    var startY = go.transform.position.y;
+
+    yield return new WaitForSeconds(1f);
+
+    Assert.Less(go.transform.position.y, startY);
+    Object.Destroy(go);
+}
+
+[Test]
+public void FloatVariable_OnEnable_ResetsToInitialValue()
+{
+    var variable = ScriptableObject.CreateInstance<FloatVariable>();
+    // Test pure logic without frames — use [Test], not [UnityTest]
+    Assert.AreEqual(0f, variable.RuntimeValue);
+}
+```
+
+## Compliance Checklist
+
+- ! Assembly Definitions for all script folders (Runtime, Editor, Tests)
+- ! `[SerializeField] private` for Inspector fields; no public fields for serialization
+- ! ScriptableObjects for shared data, configuration, and events
+- ! Object pooling for frequently spawned objects
+- ! Addressables for runtime asset loading (not `Resources/`)
+- ! Unity Test Framework with separate Edit Mode and Play Mode assemblies
+- ! Profile with Unity Profiler before and after optimization
+- ! Zero per-frame heap allocations in hot paths
+- ! Force Text serialization + Visible Meta Files for version control
+- ! See [csharp.md](../languages/csharp.md) for general C# compliance
+- ⊗ `GetComponent` in `Update`, `GameObject.Find` at runtime, empty lifecycle methods
+- ! Run `task check` before commit
+
+## Resources
+
+- [Unity Programming Best Practices Manual](https://docs.unity3d.com/6000.3/Documentation/Manual/best-practice-guides.html)
+- [C# Code Style Guide for Unity 6](https://unity.com/resources/c-sharp-style-guide-unity-6) (2nd ed., 2025)
+- [Create Modular Architecture with ScriptableObjects](https://unity.com/how-to/architect-game-code-scriptable-objects) (e-book + demo)
+- [Level Up Your Code with Game Programming Patterns](https://unity.com/how-to/level-up-your-code-with-game-programming-patterns) (SOLID + design patterns)
+- [Unity Test Framework Documentation](https://docs.unity3d.com/Packages/com.unity.test-framework@2.0/manual/index.html)
+- [Unity Performance Optimization (PC/Console)](https://docs.unity3d.com/6000.3/Documentation/Manual/best-practice-guides.html)
+- [Unity Performance Optimization (Mobile/XR/Web)](https://docs.unity3d.com/6000.3/Documentation/Manual/best-practice-guides.html)
+- [Addressables Documentation](https://docs.unity3d.com/Packages/com.unity.addressables@latest)
+- [Unity 6 Roadmap (Unite 2025)](https://www.youtube.com/watch?v=rEKmARCIkSI)

package/references/composer-skill-porting.md

@@ -0,0 +1,152 @@
+# Composer Skill Porting — Warp to Composer
+
+Reference for skill authors porting Warp-tuned playbooks into Composer-friendly
+skills (Grok Build / Cursor-style single-session agents). Issue:
+[#1518](https://github.com/deftai/directive/issues/1518).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also**: [skills/deft-directive-write-skill/SKILL.md](../skills/deft-directive-write-skill/SKILL.md) | [scm/github.md](../scm/github.md)
+
+---
+
+## Why This Document Exists
+
+Warp skills often assume multi-agent orchestration: worktrees per task, long
+scorecards pasted into chat, and human-readable tables as the source of truth.
+Composer agents load skills via YAML `description` and trigger phrases, respect a
+strict markdown rule stack (USER.md → AGENTS.md → SKILL.md), and default to
+short chat plus file/issue ceremony.
+
+Without adaptation, ported skills fight project `AGENTS.md`, spawn unnecessary
+worktrees, or fire the wrong playbook because triggers overlap. This reference
+captures the reusable authoring rules so Warp intent survives the harness change.
+
+---
+
+## Thin SKILL.md + references/ Split
+
+! Keep `SKILL.md` under ~150 lines — ordered steps, hard stops, and pointers only.
+
+⊗ Put scorecard templates, 40-line tables, triage playbooks, or output schemas
+inside `SKILL.md`. Move them to `references/*.md` and link from the skill.
+
+| Content type | Location |
+| --- | --- |
+| Triggers, prerequisites, step order | `SKILL.md` |
+| Canonical output schema, FP appendix rules | `references/canonical-output.md` |
+| Warp parity (what Warp still does that Composer skips) | `references/warp-parity.md` |
+| Long triage or pipeline docs | `references/triage-*.md` |
+
+~ Ship one Composer skill plus `references/` docs. Maintain Warp alignment in a
+single parity reference instead of duplicating two full `SKILL.md` files.
+
+---
+
+## Negative Triggers in Description
+
+The `description` field is the only surface Composer uses to decide whether to
+load a skill. Near-miss phrases cause wrong-playbook misfires.
+
+! Include explicit negative triggers in the `description` paragraph:
+
+```yaml
+description: >
+  Runs the recall loop and posts Block A/B to the tracking issue.
+  Use when the user says "run recall" or "recall loop".
+  Do NOT trigger on "run tests" alone or generic "check CI".
+```
+
+! Name Composer variants distinctly (`…-composer`, `/my-workflow-composer`) when
+a Warp skill with a similar name still exists.
+
+⊗ Rely on vague positive triggers alone — overlapping phrases (`run tests` vs
+`recall loop`) need a `Do NOT trigger on …` line.
+
+---
+
+## Fast Path vs Isolation
+
+Warp playbooks often assume per-task worktrees and merge choreography. Composer
+defaults to a single checkout.
+
+! Lead every ported skill with a **Fast path (default)** table near the top:
+
+| When | What |
+| --- | --- |
+| Default | Work on the main checkout (or single active branch) |
+| Skip worktree steps | Unless merge lock, parallel fixtures, or user requests isolation |
+| Still mandatory before commit | Script gates with exit codes (tests, ship-check, coupling) |
+
+? Document full Warp isolation steps in `references/warp-parity.md` — one page,
+gated as optional (`use when lock busy`, `use when user asks for parallel fixtures`).
+
+⊗ Force colleagues to read 200 lines before learning the default is no worktree.
+
+---
+
+## Short Chat Expectations
+
+Composer projects commonly enforce operator voice in `AGENTS.md`:
+
+- Shortest useful answer; lead with the claim.
+- No multi-line code fences in assistant chat (paths in prose are fine).
+- Long structured output belongs in vBRIEF, issues, or reference docs.
+
+### Warp habit → Composer adaptation
+
+| Warp habit | Composer markdown |
+| --- | --- |
+| Paste full scorecard tables in chat | One-line claim + stable metrics in chat |
+| User skims chat and says "go" | Run status script; attach tables to tracking issue |
+| "Show the user the table below" in a step | "Run `<script>`; post output via `--body-file`" |
+
+~ Every milestone step should name a script or file target, not a prose table to
+recall from memory.
+
+---
+
+## Windows-Safe GitHub Body Files
+
+Skills that create or comment on GitHub issues MUST NOT use inline multi-line
+`--body` strings — they break on PowerShell 5.1 quoting, nested quotes, and
+newlines.
+
+! Prefer `--body-file` for any body longer than one line. Write temp files to the
+OS temp directory, not the worktree. See [scm/github.md](../scm/github.md)
+Standing gh CLI Rules.
+
+| Unsafe Warp example | Composer-safe pattern |
+| --- | --- |
+| `gh issue create --body "…nested quotes…"` | Write body to temp `.md`; `gh … --body-file $path` |
+| `cmd1 && cmd2` on PowerShell 5.1 | `cmd1; cmd2` or separate invocations |
+| Inline heredocs in shell | Temp file under `$env:TEMP` or `%TEMP%` |
+
+! Add one row to the Fast path table when the skill shells out on Windows:
+`Shell: PowerShell 5.1; gh bodies via --body-file`.
+
+---
+
+## Authorization Wording
+
+Warp playbooks sometimes infer implement intent from lifecycle words or partial
+`git status`. Composer + Deft intent gates require explicit action verbs.
+
+! Add a short instruction-parsing block or point at project `AGENTS.md`:
+
+- Explicit verbs: `implement`, `ship`, `run agents`, `build`.
+- ⊗ Treat checklist presence or broad approval (`sounds good`) as permission to commit.
+
+---
+
+## Migration Checklist
+
+Copy when porting a Warp skill to Composer:
+
+- [ ] New `name` and `description` with `Do NOT trigger on …` lines
+- [ ] Fast path table (default checkout, shell notes)
+- [ ] Split long content into `references/` (output schema, triage, parity)
+- [ ] Replace "paste scorecard in chat" with script + issue body
+- [ ] Align with project `AGENTS.md` operator voice
+- [ ] `--body-file` for GitHub bodies on Windows-sensitive paths
+- [ ] `references/warp-parity.md` for optional Warp-only steps