Skip to content

Commit 00233c8

Browse files
TMHSDigitalTMHSDigital
authored
fix: backfill CONTRIBUTING.md and CLAUDE.md per ecosystem standards (#14)
Tracks DTD#48 (expanded scope: original issue noted CONTRIBUTING.md only; CLAUDE.md absence surfaced during DTD#47 work). Identical surgery to CFX-Developer-Tools (DTD#48 canary, merged previously). CONTRIBUTING.md follows the Plaid pattern with the verbatim DCO grant from standards/licensing.md. CLAUDE.md includes the standards-version marker and `**Version:**` convention so release-doc-sync can reconcile version markers on future releases (which DTD#51 just fixed at the runner level). Made-with: Cursor
1 parent 93e01a8 commit 00233c8

2 files changed

Lines changed: 295 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
<!-- standards-version: 1.9.2 -->
2+
3+
# CLAUDE.md
4+
5+
Project documentation for Claude Code and AI assistants working on this repository.
6+
7+
## Project Overview
8+
9+
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.
10+
11+
**Works with:** Cursor (plugin), Claude Code (terminal and in-editor), and any MCP-compatible client.
12+
13+
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.
14+
15+
**Version:** 1.4.3
16+
**License:** CC-BY-NC-ND-4.0
17+
**Author:** TMHSDigital
18+
19+
## Plugin Architecture
20+
21+
```
22+
Unity-Developer-Tools/
23+
.cursor-plugin/
24+
plugin.json # Plugin manifest (version, skills, rules)
25+
skills/
26+
<skill-name>/
27+
SKILL.md # One skill per directory (kebab-case)
28+
rules/
29+
<rule-name>.mdc # Cursor rule files
30+
snippets/
31+
csharp/ # C# patterns and examples
32+
shaders/ # HLSL / ShaderLab patterns
33+
visual-scripting/ # Visual Scripting graphs and notes
34+
templates/ # Starter project archetypes
35+
mcp-server/
36+
server.py # MCP server entry point (Python, FastMCP)
37+
data/ # API reference, deprecated patterns, shader props, platform defines
38+
requirements.txt
39+
docs/ # MkDocs Material site (ARCHITECTURE, ROADMAP, GETTING-STARTED)
40+
.github/
41+
workflows/ # CI / release / docs / drift-check automation
42+
```
43+
44+
## Skills (18)
45+
46+
| Skill | Description |
47+
|-------|-------------|
48+
| `project-setup` | Folder structure, assembly definitions, version control, and package management for Unity projects |
49+
| `monobehaviour-patterns` | MonoBehaviour lifecycle, async patterns with Awaitable, and common Unity design patterns |
50+
| `scriptableobjects` | Data-driven design with ScriptableObjects (events, variables, runtime sets, configuration) |
51+
| `physics-2d-3d` | Collision, raycasting, layers, and rigidbody management for 2D and 3D projects |
52+
| `ui-development` | UI Toolkit (primary) and Canvas/UGUI, including data binding, styling, responsive layouts |
53+
| `shader-development` | Shader Graph, HLSL, and ShaderLab for URP and HDRP projects |
54+
| `animation-systems` | Animator Controller, Timeline, DOTween, and sprite animation for 2D |
55+
| `audio-systems` | AudioSource, AudioMixer, spatial audio, and audio management patterns |
56+
| `input-systems` | New Input System package and migration guidance from the legacy Input Manager |
57+
| `networking` | Multiplayer networking with Netcode for GameObjects, Netcode for Entities, Mirror, Photon Fusion |
58+
| `editor-scripting` | Custom inspectors, editor windows, property drawers, gizmos, Scene View overlays via UI Toolkit |
59+
| `performance-optimization` | CPU, GPU, memory, and profiling tools (Profiler, Memory Profiler, Frame Debugger) |
60+
| `render-pipeline-detection` | Detect and adapt to URP, HDRP, or Built-in pipelines |
61+
| `ecs-dots` | Entity Component System with Unity Entities, Jobs, and Burst |
62+
| `visual-scripting` | Script Graphs, State Graphs, Subgraphs, and custom units |
63+
| `testing` | Unity Test Framework 2.x with Edit Mode and Play Mode tests, async Awaitable support |
64+
| `addressables-assets` | Async loading, memory management, and remote content delivery via Addressables |
65+
| `platform-targeting` | Scripting defines, build settings, and cross-platform considerations |
66+
67+
## Rules (8)
68+
69+
| Rule | Scope | Description |
70+
|------|-------|-------------|
71+
| `csharp-unity-conventions.mdc` | `**/*.cs` | C# coding conventions for Unity development |
72+
| `monobehaviour-lifecycle.mdc` | `**/*.cs` | Correct usage of MonoBehaviour lifecycle methods |
73+
| `performance-rules.mdc` | `**/*.cs` | Performance optimization rules (allocations, FindObject, tight loops) |
74+
| `naming-conventions.mdc` | `**/*.cs` | Naming conventions for Unity C# code |
75+
| `serialization-rules.mdc` | `**/*.cs` | Unity serialization best practices (`[SerializeField]`, ISerializationCallbackReceiver) |
76+
| `shader-conventions.mdc` | `**/*.shader`, `**/*.hlsl`, `**/*.cginc`, `**/*.shadergraph` | Conventions for Unity shader development (HLSLPROGRAM, SRP Batcher) |
77+
| `visual-scripting-conventions.mdc` | `**/*.asset` | Best practices for Unity Visual Scripting graphs |
78+
| `security-and-builds.mdc` | `**/*.cs`, `**/*.json`, `**/*.asset` | Security and build configuration rules (no hardcoded secrets, build target hygiene) |
79+
80+
## MCP Server (4 tools)
81+
82+
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.
83+
84+
| Tool | Description |
85+
|------|-------------|
86+
| `scaffold_script` | Generate a structured C# script (MonoBehaviour, ScriptableObject, EditorWindow, custom inspector, property drawer, interface, state machine, test) with recommended folder placement |
87+
| `lookup_api` | Search the Unity API reference (name, namespace, signature, examples) with optional category filter and deprecated-pattern warnings |
88+
| `shader_helper` | Fetch shader patterns and property setups for common effects (dissolve, outline, toon, water, hologram, fresnel) per render pipeline |
89+
| `platform_info` | Get platform-specific scripting defines, capabilities, limitations, and recommendations (Windows, macOS, Linux, Android, iOS, WebGL, PS5, Xbox, Switch) |
90+
91+
## Development Workflow
92+
93+
### Plugin development (symlink)
94+
95+
**macOS / Linux:**
96+
```bash
97+
ln -s "$(pwd)" ~/.cursor/plugins/unity-developer-tools
98+
```
99+
100+
**Windows (PowerShell as Admin):**
101+
```powershell
102+
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.cursor\plugins\unity-developer-tools" -Target (Get-Location)
103+
```
104+
105+
### MCP server development
106+
107+
```bash
108+
cd mcp-server
109+
pip install -r requirements.txt
110+
python server.py
111+
```
112+
113+
### Running validation
114+
115+
```bash
116+
# JSON schema and content-count checks (run by CI)
117+
python .github/scripts/validate_plugin.py
118+
```
119+
120+
## Release Workflow
121+
122+
Releases are automated. The `release.yml` workflow:
123+
124+
1. Reads conventional commits since the last tag.
125+
2. Computes the next semver bump (PATCH for `fix:`, MINOR for `feat:`, MAJOR for `BREAKING CHANGE`).
126+
3. Updates `plugin.json` `version` and the README version badge.
127+
4. Creates the tag, the GitHub Release, and floating major / minor tags.
128+
5. Invokes `release-doc-sync` to update `**Version:**` in this file and prepend a CHANGELOG entry.
129+
130+
Do not hand-edit `plugin.json` `version`, the README badge, or the `**Version:**` line above. The release pipeline owns them.
131+
132+
## Key Conventions
133+
134+
- **No em dashes.** Use regular dashes (`-`) or rewrite the sentence. CI flags em and en dashes in markdown.
135+
- **No hardcoded credentials.** Use environment variables, `EditorUserSettings`, or a secrets store. CI flags suspicious patterns.
136+
- **Skill frontmatter:** `title`, `description`, `globs` (when path-scoped), and `standards-version`.
137+
- **Rule frontmatter:** `title`, `description`, `globs`, `alwaysApply`, and `standards-version`.
138+
- **Snippets:** must compile against Unity 6.x and use modern APIs (Awaitable, `FindFirstObjectByType`, UI Toolkit). No placeholder credentials.
139+
- **Templates:** every template needs a top-level `README.md` describing usage, scripts, and any project setup notes (assembly definitions, package dependencies).
140+
- **MCP tool naming:** snake_case Python functions decorated with `@mcp.tool()`.
141+
142+
## Unity Reference Quick Links
143+
144+
| Resource | Use |
145+
|----------|-----|
146+
| `docs.unity3d.com/Manual/index.html` | Authoritative Unity manual |
147+
| `docs.unity3d.com/ScriptReference/index.html` | Scripting API reference |
148+
| `docs.unity3d.com/Packages/` | Package-specific manuals (URP, HDRP, Input System, Netcode, Entities) |
149+
| `mcp-server/data/unity_api_common.json` | Local Unity API quick-reference index |
150+
| `mcp-server/data/deprecated_patterns.json` | Deprecation map (legacy -> replacement) |
151+
| `mcp-server/data/shader_properties.json` | Shader effect patterns and property setups |
152+
| `mcp-server/data/platform_defines.json` | Platform scripting defines and capabilities |

‎CONTRIBUTING.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Contributing to Unity Developer Tools
2+
3+
Thanks for helping improve this plugin. This document describes how to set up locally, extend skills and rules, and submit changes.
4+
5+
## Getting Started
6+
7+
1. **Fork** the repository on GitHub.
8+
2. **Clone** your fork:
9+
10+
```bash
11+
git clone https://github.com/<your-username>/Unity-Developer-Tools.git
12+
cd Unity-Developer-Tools
13+
```
14+
15+
3. **Create a branch** for your work:
16+
17+
```bash
18+
git checkout -b your-feature-name
19+
```
20+
21+
## Local Development
22+
23+
Install the plugin from your working copy so Cursor loads your changes.
24+
25+
Symlink the repo into the local plugins directory: `~/.cursor/plugins/local/unity-developer-tools/` (create parent folders if needed).
26+
27+
**Windows (PowerShell):**
28+
29+
```powershell
30+
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools" | Out-Null
31+
cmd /c mklink /J "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools\Unity-Developer-Tools" (Get-Location)
32+
```
33+
34+
Adjust the final path if your clone lives elsewhere.
35+
36+
**macOS / Linux:**
37+
38+
```bash
39+
mkdir -p ~/.cursor/plugins/local/unity-developer-tools
40+
ln -s "$(pwd)" ~/.cursor/plugins/local/unity-developer-tools/Unity-Developer-Tools
41+
```
42+
43+
Restart Cursor after linking so it picks up the plugin.
44+
45+
## Plugin Structure
46+
47+
The repo is organized as a Cursor plugin with **18 skills** and **8 rules**, plus snippets, templates, and a companion MCP server.
48+
49+
```text
50+
.cursor-plugin/
51+
plugin.json
52+
skills/
53+
<skill-name-kebab>/
54+
SKILL.md
55+
rules/
56+
<rule-name>.mdc
57+
snippets/
58+
csharp/
59+
shaders/
60+
visual-scripting/
61+
templates/
62+
mcp-server/
63+
server.py
64+
data/
65+
docs/
66+
.github/
67+
workflows/
68+
```
69+
70+
- **`plugin.json`** - manifest (name, version, paths to skills/rules).
71+
- **`skills/`** - one directory per skill; each contains `SKILL.md`.
72+
- **`rules/`** - Cursor rules as `.mdc` files with YAML frontmatter.
73+
- **`snippets/`** - C#, HLSL/ShaderLab, and Visual Scripting examples organized by language.
74+
- **`templates/`** - starter project archetypes (2D platformer, 3D FPS, UI menu, ScriptableObject architecture, editor tool).
75+
- **`mcp-server/`** - Python MCP server exposing Unity-aware tools (script scaffolding, API lookup, shader patterns, platform info).
76+
77+
## Adding a Skill
78+
79+
1. Add a **kebab-case** directory under `skills/`, e.g. `skills/unity-example-flow/`.
80+
2. Create **`SKILL.md`** with YAML frontmatter including at least `title`, `description`, and `globs` (path-scoped patterns where applicable, e.g. `["**/*.cs"]`, `["**/*.shader", "**/*.hlsl"]`).
81+
3. In the body, include sections (use `##` headings) such as:
82+
- **Overview / Why** - when the skill applies and what problem it solves.
83+
- **Required Inputs** - what the agent or user must provide.
84+
- **Workflow** - step-by-step guidance.
85+
- **Key References** - Unity manual links, package names, or repo paths.
86+
- **Example Interaction** - short example prompt/response pattern.
87+
- **MCP Usage** - when to use the companion MCP server, if relevant.
88+
- **Common Pitfalls** - mistakes to avoid (deprecated APIs, render-pipeline confusion, MonoBehaviour lifecycle traps, etc.).
89+
- **See Also** - links to related skills or rules.
90+
91+
Match tone, formatting, and frontmatter style of existing skills in this repo.
92+
93+
## Adding a Rule
94+
95+
1. Add a **`.mdc`** file under `rules/`, e.g. `rules/unity-example.mdc`.
96+
2. Start with YAML **frontmatter**:
97+
- `title` - one-line summary.
98+
- `description` - longer description for humans and tooling.
99+
- `globs` - glob patterns scoping the rule (e.g. `["**/*.cs"]`, `["**/*.shader", "**/*.hlsl", "**/*.cginc", "**/*.shadergraph"]`).
100+
- `alwaysApply` - `true` or `false` depending on whether the rule should apply globally.
101+
102+
3. Below the frontmatter, write the rule content in Markdown (constraints, patterns, anti-patterns).
103+
104+
Keep rules focused; prefer linking to a skill for long workflows.
105+
106+
## Adding a Snippet or Template
107+
108+
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.
109+
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).
110+
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.
111+
112+
## Pull Request Process
113+
114+
1. **Update docs** if you change behavior, skill lists, snippet counts, or versioning (`README.md`, `CLAUDE.md`, `CHANGELOG.md`, `docs/ROADMAP.md` as appropriate).
115+
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/`.
116+
3. **Open a PR** against `main` with a clear title and summary of changes. Use a conventional commit prefix (`feat:`, `fix:`, `docs:`, `chore:`).
117+
4. **Respond to review** feedback; CI must pass before merge.
118+
119+
## Developer Certificate of Origin and Inbound License Grant
120+
121+
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.
122+
123+
### Required grant
124+
125+
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.
126+
127+
### DCO sign-off
128+
129+
Every commit in a pull request must have a `Signed-off-by:` trailer matching the commit author:
130+
131+
```
132+
Signed-off-by: Jane Developer <jane@example.com>
133+
```
134+
135+
Signing is done at commit time:
136+
137+
```bash
138+
git commit -s -m "feat: add new skill"
139+
```
140+
141+
The GitHub DCO App enforces this on every PR.
142+
143+
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.

0 commit comments

Comments
 (0)