If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/MixedRealityToolkit-Unity shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 22+ active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/MixedRealityToolkit-Unity repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/MixedRealityToolkit-Unity.

What it runs against: a local clone of microsoft/MixedRealityToolkit-Unity — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/MixedRealityToolkit-Unity | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/MixedRealityToolkit-Unity. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/MixedRealityToolkit-Unity.git
#   cd MixedRealityToolkit-Unity
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/MixedRealityToolkit-Unity and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/MixedRealityToolkit-Unity(\\.git)?\\b" \\
  && ok "origin remote is microsoft/MixedRealityToolkit-Unity" \\
  || miss "origin remote is not microsoft/MixedRealityToolkit-Unity (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Assets/MRTK/Core/Definitions/BaseMixedRealityProfile.cs" \\
  && ok "Assets/MRTK/Core/Definitions/BaseMixedRealityProfile.cs" \\
  || miss "missing critical file: Assets/MRTK/Core/Definitions/BaseMixedRealityProfile.cs"
test -f "Assets/MRTK/Core/Attributes/MixedRealityServiceProfileAttribute.cs" \\
  && ok "Assets/MRTK/Core/Attributes/MixedRealityServiceProfileAttribute.cs" \\
  || miss "missing critical file: Assets/MRTK/Core/Attributes/MixedRealityServiceProfileAttribute.cs"
test -f "Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerMappingProfile.cs" \\
  && ok "Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerMappingProfile.cs" \\
  || miss "missing critical file: Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerMappingProfile.cs"
test -f "Assets/MRTK/Core/Definitions/CameraSystem/MixedRealityCameraProfile.cs" \\
  && ok "Assets/MRTK/Core/Definitions/CameraSystem/MixedRealityCameraProfile.cs" \\
  || miss "missing critical file: Assets/MRTK/Core/Definitions/CameraSystem/MixedRealityCameraProfile.cs"
test -f "Assets/MRTK/Core/Definitions/Devices/ControllerMappingLibrary.cs" \\
  && ok "Assets/MRTK/Core/Definitions/Devices/ControllerMappingLibrary.cs" \\
  || miss "missing critical file: Assets/MRTK/Core/Definitions/Devices/ControllerMappingLibrary.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/MixedRealityToolkit-Unity"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MRTK v2 is a legacy cross-platform Mixed Reality toolkit for Unity that provides input abstraction, spatial interaction components, and UI building blocks for VR/AR/MR applications. It abstracts away device-specific APIs (HoloLens, WMR, Meta Quest, ARCore, ARKit) through a plugin system and in-editor simulation, letting developers write once for multiple XR platforms. Monolithic Unity asset structure under Assets/MRTK/ with modular subsystems: Core/ contains framework attributes and base infrastructure, organized by feature (Input, UI, Interactions, etc.). Device support plugged via XR SDK abstraction layer (Windows XR Plugin, OpenXR, Oculus, ARCore, ARKit). PowerShell/Python scripts in repo root for build validation and documentation generation.

Unity developers building mixed reality applications for HoloLens 2, Windows Mixed Reality headsets, Meta Quest, or mobile AR devices. Teams that need rapid XR prototyping with device simulation in the editor and want to avoid vendor lock-in through cross-platform abstraction.

Production-ready and actively maintained but legacy: this is MRTK v2, explicitly superseded by MRTK v3+ (new org at github.com/MixedRealityToolkit/). The v2 codebase is mature (10MB+ C# code, extensive CI in .github/workflows/), but Microsoft has committed to v3 as the forward path and will only address critical v2 issues until deprecation. Appropriate for shipping apps but not recommended for new projects.

Maintenance risk is explicit: repo is in 'legacy' mode with the README warning users to migrate to MRTK v3. No apparent single-maintainer risk (Microsoft-backed), but breaking changes between v2 and v3 will require migration effort. The split between two organizational repos (microsoft/ for v2, MixedRealityToolkit/ for v3) may create confusion when seeking issue support or documentation.

Active maintenance of v2 bug fixes and critical issues. CI/CD pipelines visible in .github/workflows/ include validation, documentation generation (docs_mrtk2.yaml), and automated issue labeling. No major feature work expected—focus is supporting existing deployments while directing new projects to v3.

Clone and open in Unity: git clone https://github.com/microsoft/MixedRealityToolkit-Unity.git then open Assets/ folder in Unity (2019 LTS or later, 2020/2021 LTS recommended for OpenXR). The project is not a traditional npm/nuget package—it's consumed as a Unity asset import or installed via the MRTK Hub.

Daily commands: MRTK v2 is not a 'runnable' project—it's a framework library. Open it in Unity Editor, select a target device in XR Plugin Management (Edit > Project Settings > XR Plugin Management), then import example scenes from Assets/MRTK/ subdirectories. For in-editor simulation, configure input simulation settings in the MRTK Configuration Profile.

• Assets/MRTK/Core/Definitions/BaseMixedRealityProfile.cs — Base class for all MRTK configuration profiles; all system configurations inherit from this, making it essential to understand the profile hierarchy
• Assets/MRTK/Core/Attributes/MixedRealityServiceProfileAttribute.cs — Decorator attribute that marks service profile classes; understanding this is critical for implementing new MRTK services and profiles
• Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerMappingProfile.cs — Central controller mapping configuration; essential for input handling and device abstraction across all mixed reality platforms
• Assets/MRTK/Core/Definitions/CameraSystem/MixedRealityCameraProfile.cs — Core camera configuration profile that drives rendering behavior across HoloLens, VR, and mobile platforms
• Assets/MRTK/Core/Definitions/Devices/ControllerMappingLibrary.cs — Centralized registry of controller mappings for all supported input devices; referenced by input system and controller visualization
• Assets/MRTK/Core/Definitions/BoundarySystem/MixedRealityBoundaryVisualizationProfile.cs — Defines spatial boundary visualization configuration; critical for safety and playspace definition in mixed reality experiences

Add a New Input Device Type

1. Add device type enum value to Assets/MRTK/Core/Definitions/Devices/InputSourceType.cs (Assets/MRTK/Core/Definitions/Devices/InputSourceType.cs)
2. Create a new controller definition class extending BaseInputSourceDefinition in Assets/MRTK/Core/Definitions/Devices/ (e.g., MyCustomControllerDefinition.cs) (Assets/MRTK/Core/Definitions/Devices/BaseInputSourceDefinition.cs)
3. Register mapping in Assets/MRTK/Core/Definitions/Devices/ControllerMappingLibrary.cs by adding to the pre-built mappings dictionary (Assets/MRTK/Core/Definitions/Devices/ControllerMappingLibrary.cs)
4. Add input button/axis types to Assets/MRTK/Core/Definitions/Devices/DeviceInputType.cs if new interaction types are needed (Assets/MRTK/Core/Definitions/Devices/DeviceInputType.cs)

Create a New MRTK Service Profile

1. Create a new class extending BaseMixedRealityProfile in Assets/MRTK/Core/Definitions/ (Assets/MRTK/Core/Definitions/BaseMixedRealityProfile.cs)
2. Apply [MixedRealityServiceProfile] attribute to mark it as a service-configurable profile (Assets/MRTK/Core/Attributes/MixedRealityServiceProfileAttribute.cs)
3. Add custom configuration properties to your profile class and use property attributes like [SystemType], [ReadOnly], or [PrefabAttribute] from Assets/MRTK/Core/Attributes/ (Assets/MRTK/Core/Attributes/SystemTypeAttribute.cs)
4. Register profile type in the MRTK Configuration system for service discovery and validation (Assets/MRTK/Core/Definitions/BaseMixedRealityProfile.cs)

Add a New Controller Visualization

1. Create left/right hand controller model prefabs and assign them to Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerVisualizationProfile.cs (Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerVisualizationProfile.cs)
2. Reference or extend MixedRealityControllerModelHelpers.cs to add custom model loading logic if needed (Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerModelHelpers.cs)
3. Ensure your controller definition (from ControllerMappingLibrary) is mapped to visualization settings in the profile (Assets/MRTK/Core/Definitions/Devices/MixedRealityControllerMappingProfile.cs)

Configure Camera Rendering for a New Platform

1. Create a platform-specific camera settings profile extending BaseCameraSettingsProfile in Assets/MRTK/Core/Definitions/CameraSystem/ (Assets/MRTK/Core/Definitions/CameraSystem/BaseCameraSettingsProfile.cs)
2. Set display type in Assets/MRTK/Core/Definitions/CameraSystem/CameraDisplayType.cs or add new enum value (Assets/MRTK/Core/Definitions/CameraSystem/CameraDisplayType.cs)
3. Register configuration in MixedRealityCameraProfile.cs and reference it from the main MRTK configuration (Assets/MRTK/Core/Definitions/CameraSystem/MixedRealityCameraProfile.cs)

• Unity C# scripting framework — MRTK v2 is a Unity plugin; all code must be C# and run within Unity's scripting runtime for cross-platform XR support
• ScriptableObject-based configuration (Profiles) — Allows non-programmer users to configure input mappings, camera settings, and spatial boundaries in the Unity Inspector without code changes
• Attribute-based component registration —

MRTK v2 requires explicit XR Plugin selection in Unity Project Settings (not automatic)—if the wrong plugin is active, device features silently fail. Input simulation only works in Editor (set 'Simulated Hand Pose' in MRTK Configuration). Shader compilation differs per platform (ShaderLab → GLSL on mobile, HLSL on Windows)—platform-specific bugs are hard to reproduce cross-device. Documentation split between old repo (microsoft/) and new v3 repo (MixedRealityToolkit/) may return outdated or mismatched links.

• Mixed Reality Service Provider Pattern — MRTK abstracts device differences (HoloLens vs. Meta vs. ARKit) through swappable IMixedRealityDataProvider implementations—understanding this is essential to add support for new devices or override existing ones

• MixedRealityToolkit/MixedRealityToolkit-Unity — MRTK v3+ (successor) with modernized architecture, UX Toolkit integration, and active development—new projects should start here
• Unity-Technologies/XR-Interaction-Toolkit — Complementary Unity-native XR toolkit offering hand interaction and locomotion; often used alongside MRTK for complex XR interactions
• microsoft/OpenXR-Unity-MixedReality-Plugin — Official MS plugin that bridges MRTK v2 and modern OpenXR standard for HoloLens 2 and WMR; required for certain v2 features
• Ultraleap/UnityPlugin — Hand tracking solution that integrates with MRTK v2 via provider pattern for finger-level interactions beyond controller input

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Core/Attributes serialization and validation

The Assets/MRTK/Core/Attributes directory contains 16 custom attributes (DocLinkAttribute, SystemTypeAttribute, MixedRealityControllerAttribute, etc.) that are critical for the inspector experience and data validation. These attributes likely lack unit tests covering edge cases, serialization correctness, and integration with Unity's serialization system. New contributors can add tests to ensure attributes work correctly across different Unity versions and serialization scenarios.

• [ ] Create Assets/MRTK/Tests/Core/Attributes directory structure
• [ ] Add unit tests for SystemTypeAttribute.cs (type validation, null handling, inheritance chains)
• [ ] Add unit tests for MixedRealityServiceProfileAttribute.cs and MixedRealityDataProviderAttribute.cs (profile resolution)
• [ ] Add unit tests for Vector3RangeAttribute.cs and PhysicsLayerAttribute.cs (value clamping and validation)
• [ ] Add integration tests ensuring attributes work with Unity's PropertyDrawer system

Add validation and unit tests for BaseMixedRealityProfile.cs configuration loading

BaseMixedRealityProfile.cs (Assets/MRTK/Core/Definitions/BaseMixedRealityProfile.cs) is the foundation for all MRTK configuration. Currently there are no visible tests for profile loading, cloning, validation, and inheritance. A new contributor should create comprehensive tests ensuring profiles handle missing references, circular dependencies, and serialization edge cases correctly.

• [ ] Create Assets/MRTK/Tests/Core/Definitions directory for profile tests
• [ ] Add unit tests for BaseMixedRealityProfile cloning and deep copy scenarios
• [ ] Add tests for profile validation (checking required fields, reference integrity)
• [ ] Add tests for profile hierarchy (nested profiles, inheritance validation)
• [ ] Add integration tests with actual profile assets to catch serialization issues

Create missing GitHub Actions workflow for MRTK v2 documentation generation and validation

The repo has docs_mrtk2.yaml and validation_mrtk2.yaml workflows, but lacks a workflow that specifically validates DocLinkAttribute references and generates documentation from XML comments. With 16+ custom attributes and extensive Core definitions, a new contributor should create a workflow that validates all DocLinkAttribute URLs point to valid documentation, parses XML documentation comments, and generates/validates API reference documentation.

• [ ] Create .github/workflows/docs_validation_mrtk2.yaml workflow
• [ ] Add step to scan all .cs files for DocLinkAttribute and validate URLs are not dead links
• [ ] Add step to validate all public APIs in Assets/MRTK/Core have XML documentation comments
• [ ] Add step to generate API reference markdown from XML comments using docfx or similar tool
• [ ] Configure workflow to fail if documentation coverage drops below threshold (e.g., 80%)

• Add missing XML documentation comments to attributes in Assets/MRTK/Core/Attributes/*.cs—many custom attributes lack <summary> tags, blocking IDE tooltips and automatic doc generation.
• Write unit tests for input provider registration and lifecycle in the Core service framework (no test files visible in file structure)—critical for catching breaking changes in v2 maintenance.
• Port or enhance in-editor input simulation for underrepresented controllers (e.g., ARCore Touch input)—simulation is Windows/OpenXR focused, limiting mobile AR prototyping.

The MRTK v2 legacy codebase shows moderate security posture with no immediately critical vulnerabilities evident from the file structure analysis. However, as a legacy project, the primary concerns are: (1) potential unpatched dependencies without active maintenance, (2) lack of visible automated security scanning in CI/CD, and (3) missing dependency lock files. The codebase itself appears well-structured without obvious injection vulnerabilities, hardcoded secrets, or exposed credentials in file names. Users should prioritize migrating to MRTK v3+ if possible, or implement enhanced dependency monitoring and security scanning if remaining on v2.

• Medium · Legacy Repository with Potential Unpatched Dependencies — Repository root - microsoft/MixedRealityToolkit-Unity (v2). This is the MRTK v2 legacy repository. Legacy projects often have unpatched or outdated dependencies that may contain known security vulnerabilities. The repository is no longer actively maintained for new features, increasing the risk of security issues not being addressed. Fix: Consider migrating to MRTK v3+ which is actively maintained. If staying on v2, regularly audit dependencies using tools like OWASP Dependency-Check or npm audit. Keep Unity and all third-party packages updated.
• Low · Missing Dependency Lock File — Repository root. No package lock file (package-lock.json, yarn.lock, Packages/manifest.json, or similar) is visible in the provided file structure. This makes it difficult to ensure reproducible builds and could lead to version drift with indirect dependencies. Fix: Ensure dependency lock files are committed to version control. For Unity projects, ensure 'Packages/manifest.json' and 'Packages/packages-lock.json' are tracked in git.
• Low · No Evidence of Security Scanning in CI/CD — .github/workflows/. While GitHub workflows exist (.github/workflows/), there is no visible evidence of automated security scanning (SAST, dependency scanning, or secrets scanning) in the workflow files provided. Fix: Implement automated security scanning in CI/CD pipelines: Add GitHub's secret scanning, enable Dependabot alerts, integrate SAST tools like SonarQube or CodeQL, and add OWASP dependency checking.
• Low · Potential Information Disclosure via Issue Templates — .github/ISSUE_TEMPLATE/. Issue templates exist in .github/ISSUE_TEMPLATE/ which may encourage users to include sensitive information (API keys, personal data, environment configs) in bug reports. Fix: Ensure issue templates include a section explicitly warning users NOT to include sensitive information such as API keys, credentials, personal data, or internal system details. Add a security.md or SECURITY.md file with responsible disclosure guidelines.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.