TMHSDigital · TMHSDigital · Apr 26, 2026 · Apr 26, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,152 @@
+<!-- standards-version: 1.9.2 -->
+
+# CLAUDE.md
+
+Project documentation for Claude Code and AI assistants working on this repository.
+
+## Project Overview
+
+Unity Developer Tools is a Cursor IDE plugin for Unity game development. It includes 18 skills, 8 rules, 20 code snippets across C# / HLSL / Visual Scripting, 5 starter templates, and a companion Python MCP server with 4 tools for script scaffolding, Unity API lookup, shader patterns, and platform information.
+
+**Works with:** Cursor (plugin), Claude Code (terminal and in-editor), and any MCP-compatible client.
+
+This is a monorepo. Skills, rules, snippets, templates, and the companion MCP server live in the same repository because Unity development crosses all of those layers in a single workflow.
+
+**Version:** 1.4.3
+**License:** CC-BY-NC-ND-4.0
+**Author:** TMHSDigital
+
+## Plugin Architecture
+
+```
+Unity-Developer-Tools/
+  .cursor-plugin/
+    plugin.json              # Plugin manifest (version, skills, rules)
+  skills/
+    <skill-name>/
+      SKILL.md               # One skill per directory (kebab-case)
+  rules/
+    <rule-name>.mdc          # Cursor rule files
+  snippets/
+    csharp/                  # C# patterns and examples
+    shaders/                 # HLSL / ShaderLab patterns
+    visual-scripting/        # Visual Scripting graphs and notes
+  templates/                 # Starter project archetypes
+  mcp-server/
+    server.py                # MCP server entry point (Python, FastMCP)
+    data/                    # API reference, deprecated patterns, shader props, platform defines
+    requirements.txt
+  docs/                      # MkDocs Material site (ARCHITECTURE, ROADMAP, GETTING-STARTED)
+  .github/
+    workflows/               # CI / release / docs / drift-check automation
+```
+
+## Skills (18)
+
+| Skill | Description |
+|-------|-------------|
+| `project-setup` | Folder structure, assembly definitions, version control, and package management for Unity projects |
+| `monobehaviour-patterns` | MonoBehaviour lifecycle, async patterns with Awaitable, and common Unity design patterns |
+| `scriptableobjects` | Data-driven design with ScriptableObjects (events, variables, runtime sets, configuration) |
+| `physics-2d-3d` | Collision, raycasting, layers, and rigidbody management for 2D and 3D projects |
+| `ui-development` | UI Toolkit (primary) and Canvas/UGUI, including data binding, styling, responsive layouts |
+| `shader-development` | Shader Graph, HLSL, and ShaderLab for URP and HDRP projects |
+| `animation-systems` | Animator Controller, Timeline, DOTween, and sprite animation for 2D |
+| `audio-systems` | AudioSource, AudioMixer, spatial audio, and audio management patterns |
+| `input-systems` | New Input System package and migration guidance from the legacy Input Manager |
+| `networking` | Multiplayer networking with Netcode for GameObjects, Netcode for Entities, Mirror, Photon Fusion |
+| `editor-scripting` | Custom inspectors, editor windows, property drawers, gizmos, Scene View overlays via UI Toolkit |
+| `performance-optimization` | CPU, GPU, memory, and profiling tools (Profiler, Memory Profiler, Frame Debugger) |
+| `render-pipeline-detection` | Detect and adapt to URP, HDRP, or Built-in pipelines |
+| `ecs-dots` | Entity Component System with Unity Entities, Jobs, and Burst |
+| `visual-scripting` | Script Graphs, State Graphs, Subgraphs, and custom units |
+| `testing` | Unity Test Framework 2.x with Edit Mode and Play Mode tests, async Awaitable support |
+| `addressables-assets` | Async loading, memory management, and remote content delivery via Addressables |
+| `platform-targeting` | Scripting defines, build settings, and cross-platform considerations |
+
+## Rules (8)
+
+| Rule | Scope | Description |
+|------|-------|-------------|
+| `csharp-unity-conventions.mdc` | `**/*.cs` | C# coding conventions for Unity development |
+| `monobehaviour-lifecycle.mdc` | `**/*.cs` | Correct usage of MonoBehaviour lifecycle methods |
+| `performance-rules.mdc` | `**/*.cs` | Performance optimization rules (allocations, FindObject, tight loops) |
+| `naming-conventions.mdc` | `**/*.cs` | Naming conventions for Unity C# code |
+| `serialization-rules.mdc` | `**/*.cs` | Unity serialization best practices (`[SerializeField]`, ISerializationCallbackReceiver) |
+| `shader-conventions.mdc` | `**/*.shader`, `**/*.hlsl`, `**/*.cginc`, `**/*.shadergraph` | Conventions for Unity shader development (HLSLPROGRAM, SRP Batcher) |
+| `visual-scripting-conventions.mdc` | `**/*.asset` | Best practices for Unity Visual Scripting graphs |
+| `security-and-builds.mdc` | `**/*.cs`, `**/*.json`, `**/*.asset` | Security and build configuration rules (no hardcoded secrets, build target hygiene) |
+
+## MCP Server (4 tools)
+
+The companion MCP server is Python-based (FastMCP). It exposes Unity-aware tools that read from local data files (`mcp-server/data/`) and accept agent-supplied parameters.
+
+| Tool | Description |
+|------|-------------|
+| `scaffold_script` | Generate a structured C# script (MonoBehaviour, ScriptableObject, EditorWindow, custom inspector, property drawer, interface, state machine, test) with recommended folder placement |
+| `lookup_api` | Search the Unity API reference (name, namespace, signature, examples) with optional category filter and deprecated-pattern warnings |
+| `shader_helper` | Fetch shader patterns and property setups for common effects (dissolve, outline, toon, water, hologram, fresnel) per render pipeline |
+| `platform_info` | Get platform-specific scripting defines, capabilities, limitations, and recommendations (Windows, macOS, Linux, Android, iOS, WebGL, PS5, Xbox, Switch) |
+
+## Development Workflow
+
+### Plugin development (symlink)
+
+**macOS / Linux:**
+```bash
+ln -s "$(pwd)" ~/.cursor/plugins/unity-developer-tools
+```
+
+**Windows (PowerShell as Admin):**
+```powershell
+New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.cursor\plugins\unity-developer-tools" -Target (Get-Location)
+```
+
+### MCP server development
+
+```bash
+cd mcp-server
+pip install -r requirements.txt
+python server.py
+```
+
+### Running validation
+
+```bash
+# JSON schema and content-count checks (run by CI)
+python .github/scripts/validate_plugin.py
+```
+
+## Release Workflow
+
+Releases are automated. The `release.yml` workflow:
+
+1. Reads conventional commits since the last tag.
+2. Computes the next semver bump (PATCH for `fix:`, MINOR for `feat:`, MAJOR for `BREAKING CHANGE`).
+3. Updates `plugin.json` `version` and the README version badge.
+4. Creates the tag, the GitHub Release, and floating major / minor tags.
+5. Invokes `release-doc-sync` to update `**Version:**` in this file and prepend a CHANGELOG entry.
+
+Do not hand-edit `plugin.json` `version`, the README badge, or the `**Version:**` line above. The release pipeline owns them.
+
+## Key Conventions
+
+- **No em dashes.** Use regular dashes (`-`) or rewrite the sentence. CI flags em and en dashes in markdown.
+- **No hardcoded credentials.** Use environment variables, `EditorUserSettings`, or a secrets store. CI flags suspicious patterns.
+- **Skill frontmatter:** `title`, `description`, `globs` (when path-scoped), and `standards-version`.
+- **Rule frontmatter:** `title`, `description`, `globs`, `alwaysApply`, and `standards-version`.
+- **Snippets:** must compile against Unity 6.x and use modern APIs (Awaitable, `FindFirstObjectByType`, UI Toolkit). No placeholder credentials.
+- **Templates:** every template needs a top-level `README.md` describing usage, scripts, and any project setup notes (assembly definitions, package dependencies).
+- **MCP tool naming:** snake_case Python functions decorated with `@mcp.tool()`.
+
+## Unity Reference Quick Links
+
+| Resource | Use |
+|----------|-----|
+| `docs.unity3d.com/Manual/index.html` | Authoritative Unity manual |
+| `docs.unity3d.com/ScriptReference/index.html` | Scripting API reference |
+| `docs.unity3d.com/Packages/` | Package-specific manuals (URP, HDRP, Input System, Netcode, Entities) |
+| `mcp-server/data/unity_api_common.json` | Local Unity API quick-reference index |
+| `mcp-server/data/deprecated_patterns.json` | Deprecation map (legacy -> replacement) |
+| `mcp-server/data/shader_properties.json` | Shader effect patterns and property setups |
+| `mcp-server/data/platform_defines.json` | Platform scripting defines and capabilities |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,143 @@
+# Contributing to Unity Developer Tools
+
+Thanks for helping improve this plugin. This document describes how to set up locally, extend skills and rules, and submit changes.
+
+## Getting Started
+
+1. **Fork** the repository on GitHub.
+2. **Clone** your fork:
+
+   ```bash
+   git clone https://github.com/<your-username>/Unity-Developer-Tools.git
+   cd Unity-Developer-Tools
+   ```
+
+3. **Create a branch** for your work:
+
+   ```bash
+   git checkout -b your-feature-name
+   ```
+
+## Local Development
+
+Install the plugin from your working copy so Cursor loads your changes.
+
+Symlink the repo into the local plugins directory: `~/.cursor/plugins/local/unity-developer-tools/` (create parent folders if needed).
+
+**Windows (PowerShell):**
+
+```powershell
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools" | Out-Null
+cmd /c mklink /J "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools\Unity-Developer-Tools" (Get-Location)
+```
+
+Adjust the final path if your clone lives elsewhere.
+
+**macOS / Linux:**
+
+```bash
+mkdir -p ~/.cursor/plugins/local/unity-developer-tools
+ln -s "$(pwd)" ~/.cursor/plugins/local/unity-developer-tools/Unity-Developer-Tools
+```
+
+Restart Cursor after linking so it picks up the plugin.
+
+## Plugin Structure
+
+The repo is organized as a Cursor plugin with **18 skills** and **8 rules**, plus snippets, templates, and a companion MCP server.
+
+```text
+.cursor-plugin/
+  plugin.json
+skills/
+  <skill-name-kebab>/
+    SKILL.md
+rules/
+  <rule-name>.mdc
+snippets/
+  csharp/
+  shaders/
+  visual-scripting/
+templates/
+mcp-server/
+  server.py
+  data/
+docs/
+.github/
+  workflows/
+```
+
+- **`plugin.json`** - manifest (name, version, paths to skills/rules).
+- **`skills/`** - one directory per skill; each contains `SKILL.md`.
+- **`rules/`** - Cursor rules as `.mdc` files with YAML frontmatter.
+- **`snippets/`** - C#, HLSL/ShaderLab, and Visual Scripting examples organized by language.
+- **`templates/`** - starter project archetypes (2D platformer, 3D FPS, UI menu, ScriptableObject architecture, editor tool).
+- **`mcp-server/`** - Python MCP server exposing Unity-aware tools (script scaffolding, API lookup, shader patterns, platform info).
+
+## Adding a Skill
+
+1. Add a **kebab-case** directory under `skills/`, e.g. `skills/unity-example-flow/`.
+2. Create **`SKILL.md`** with YAML frontmatter including at least `title`, `description`, and `globs` (path-scoped patterns where applicable, e.g. `["**/*.cs"]`, `["**/*.shader", "**/*.hlsl"]`).
+3. In the body, include sections (use `##` headings) such as:
+   - **Overview / Why** - when the skill applies and what problem it solves.
+   - **Required Inputs** - what the agent or user must provide.
+   - **Workflow** - step-by-step guidance.
+   - **Key References** - Unity manual links, package names, or repo paths.
+   - **Example Interaction** - short example prompt/response pattern.
+   - **MCP Usage** - when to use the companion MCP server, if relevant.
+   - **Common Pitfalls** - mistakes to avoid (deprecated APIs, render-pipeline confusion, MonoBehaviour lifecycle traps, etc.).
+   - **See Also** - links to related skills or rules.
+
+Match tone, formatting, and frontmatter style of existing skills in this repo.
+
+## Adding a Rule
+
+1. Add a **`.mdc`** file under `rules/`, e.g. `rules/unity-example.mdc`.
+2. Start with YAML **frontmatter**:
+   - `title` - one-line summary.
+   - `description` - longer description for humans and tooling.
+   - `globs` - glob patterns scoping the rule (e.g. `["**/*.cs"]`, `["**/*.shader", "**/*.hlsl", "**/*.cginc", "**/*.shadergraph"]`).
+   - `alwaysApply` - `true` or `false` depending on whether the rule should apply globally.
+
+3. Below the frontmatter, write the rule content in Markdown (constraints, patterns, anti-patterns).
+
+Keep rules focused; prefer linking to a skill for long workflows.
+
+## Adding a Snippet or Template
+
+1. Snippets live under `snippets/` grouped by language (`csharp/`, `shaders/`, `visual-scripting/`). Each file should be self-contained, target Unity 6.x APIs (Awaitable, `FindFirstObjectByType`, UI Toolkit), and free of hardcoded credentials.
+2. Templates live under `templates/`. A new template needs at least a top-level `README.md` describing usage, the canonical scripts, and any project setup notes (assembly definitions, package dependencies, scripting defines).
+3. Run the validators before opening a PR; CI checks JSON validity, plugin manifest completeness, file count consistency, em/en dash detection, and credential scanning.
+
+## Pull Request Process
+
+1. **Update docs** if you change behavior, skill lists, snippet counts, or versioning (`README.md`, `CLAUDE.md`, `CHANGELOG.md`, `docs/ROADMAP.md` as appropriate).
+2. **Run validation** locally where possible. CI runs JSON schema checks, kebab-case enforcement, em/en dash detection, deprecated-API scans, and Python syntax checks for `mcp-server/`.
+3. **Open a PR** against `main` with a clear title and summary of changes. Use a conventional commit prefix (`feat:`, `fix:`, `docs:`, `chore:`).
+4. **Respond to review** feedback; CI must pass before merge.
+
+## Developer Certificate of Origin and Inbound License Grant
+
+This project uses CC-BY-NC-ND-4.0 as its outbound license, which forbids derivatives. Every pull request is a derivative. Contributions are accepted inbound under a broader grant via the Developer Certificate of Origin (DCO), which resolves the conflict so the project can accept and redistribute contributions.
+
+### Required grant
+
+By submitting a contribution to this repository, you certify that you have the right to do so under the Developer Certificate of Origin (DCO) 1.1, and you grant TMHSDigital a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute your contribution under the project's current license (CC-BY-NC-ND-4.0) or any successor license chosen by the project.
+
+### DCO sign-off
+
+Every commit in a pull request must have a `Signed-off-by:` trailer matching the commit author:
+
+```
+Signed-off-by: Jane Developer <jane@example.com>
+```
+
+Signing is done at commit time:
+
+```bash
+git commit -s -m "feat: add new skill"
+```
+
+The GitHub DCO App enforces this on every PR.
+
+For the full inbound/outbound model and rationale, see [`standards/licensing.md`](https://github.com/TMHSDigital/Developer-Tools-Directory/blob/main/standards/licensing.md) in the Developer-Tools-Directory meta-repo.