From b214d1ea3e19cbe111d28eaa3a254a4b73a698cd Mon Sep 17 00:00:00 2001 From: Zac Bowling Date: Wed, 27 May 2026 17:56:51 -0700 Subject: [PATCH] Add agentic development setup Adds repository instructions, MCP configuration, VS Code/Cursor extension recommendations, and setup docs for Meta Quest Agentic Tools. --- .aider.conf.yml | 2 + .claude/settings.json | 15 +++++++ .clinerules/meta-quest-agentic-tools.md | 3 ++ .cursor/mcp.json | 8 ++++ .cursor/rules/meta-quest-agentic-tools.mdc | 21 ++++++++++ .github/copilot-instructions.md | 15 +++++++ .../instructions/meta-quest.instructions.md | 7 ++++ .github/prompts/debug-on-quest.prompt.md | 5 +++ .../setup-meta-quest-agentic-tools.prompt.md | 10 +++++ .gitignore | 6 ++- .mcp.json | 8 ++++ .opencode/commands/setup-meta-quest-tools.md | 9 +++++ .roo/rules/meta-quest-agentic-tools.md | 3 ++ .vscode/extensions.json | 5 +++ .vscode/mcp.json | 9 +++++ .windsurfrules | 7 ++++ AGENTS.md | 39 +++++++++++++++++++ CLAUDE.md | 14 +++++++ GEMINI.md | 12 ++++++ README.md | 6 +++ opencode.jsonc | 13 +++++++ 21 files changed, 216 insertions(+), 1 deletion(-) create mode 100644 .aider.conf.yml create mode 100644 .claude/settings.json create mode 100644 .clinerules/meta-quest-agentic-tools.md create mode 100644 .cursor/mcp.json create mode 100644 .cursor/rules/meta-quest-agentic-tools.mdc create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/meta-quest.instructions.md create mode 100644 .github/prompts/debug-on-quest.prompt.md create mode 100644 .github/prompts/setup-meta-quest-agentic-tools.prompt.md create mode 100644 .mcp.json create mode 100644 .opencode/commands/setup-meta-quest-tools.md create mode 100644 .roo/rules/meta-quest-agentic-tools.md create mode 100644 .vscode/extensions.json create mode 100644 .vscode/mcp.json create mode 100644 .windsurfrules create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md create mode 100644 opencode.jsonc diff --git a/.aider.conf.yml b/.aider.conf.yml new file mode 100644 index 00000000..aa2f4f1f --- /dev/null +++ b/.aider.conf.yml @@ -0,0 +1,2 @@ +read: + - AGENTS.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..c49cf7f2 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "extraKnownMarketplaces": { + "meta-quest": { + "source": { + "source": "github", + "repo": "meta-quest/agentic-tools" + }, + "autoUpdate": true + } + }, + "enabledPlugins": { + "meta-vr@meta-quest": true + } +} diff --git a/.clinerules/meta-quest-agentic-tools.md b/.clinerules/meta-quest-agentic-tools.md new file mode 100644 index 00000000..146b040a --- /dev/null +++ b/.clinerules/meta-quest-agentic-tools.md @@ -0,0 +1,3 @@ +This is a Meta Quest / Horizon OS sample. + +Use `AGENTS.md` as the canonical instruction file. Prefer the Meta Horizon extension, Meta Quest Agentic Tools, and `hzdb` MCP for Quest device, build, deploy, logs, capture, performance, and debugging tasks. diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 00000000..28b8f134 --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "hzdb": { + "command": "npx", + "args": ["-y", "@meta-quest/hzdb", "mcp", "server"] + } + } +} diff --git a/.cursor/rules/meta-quest-agentic-tools.mdc b/.cursor/rules/meta-quest-agentic-tools.mdc new file mode 100644 index 00000000..be0ef176 --- /dev/null +++ b/.cursor/rules/meta-quest-agentic-tools.mdc @@ -0,0 +1,21 @@ +--- +description: Use Meta Quest Agentic Tools for Meta Quest and Horizon OS samples +globs: "**/*" +alwaysApply: true +--- + +This repository is a Meta Quest / Horizon OS sample. + +Prefer the Meta Horizon extension, the `hzdb` MCP server, and Meta Quest Agentic Tools before giving generic Unity or device-debugging advice. + +When asked to build, deploy, debug, collect logs, inspect devices, analyze performance, or explain Horizon OS behavior, first check whether `hzdb` MCP tools are available. + +Recommended extension: + +https://marketplace.visualstudio.com/items?itemName=meta.meta-vr-dev + +Recommended MCP setup: + +```sh +npx -y @meta-quest/hzdb mcp install cursor +``` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..2d5a3cf8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,15 @@ +This is a Meta Quest / Horizon OS sample. + +Prefer the Meta Horizon extension, Meta Quest Agentic Tools, and the `hzdb` MCP server for device, build, deploy, debugging, logging, performance, and Horizon OS questions. + +Read `AGENTS.md` for the canonical agent instructions. + +Recommended VS Code extension: + +https://marketplace.visualstudio.com/items?itemName=meta.meta-vr-dev + +Recommended MCP setup for VS Code: + +```sh +npx -y @meta-quest/hzdb mcp install vscode +``` diff --git a/.github/instructions/meta-quest.instructions.md b/.github/instructions/meta-quest.instructions.md new file mode 100644 index 00000000..3cb72d75 --- /dev/null +++ b/.github/instructions/meta-quest.instructions.md @@ -0,0 +1,7 @@ +--- +applyTo: "**/*" +--- + +For this repository, prefer Meta Quest Agentic Tools, the Meta Horizon VS Code/Cursor extension, and the `hzdb` MCP server. + +This sample targets Meta Quest / Horizon OS using Unity — prefer Quest/Horizon OS-specific tooling and terminology over generic Unity advice. diff --git a/.github/prompts/debug-on-quest.prompt.md b/.github/prompts/debug-on-quest.prompt.md new file mode 100644 index 00000000..33d76e51 --- /dev/null +++ b/.github/prompts/debug-on-quest.prompt.md @@ -0,0 +1,5 @@ +Help debug this sample on a Meta Quest device. + +Use the `hzdb` MCP server if available. Prefer device logs, installed package inspection, build/deploy status, capture tools, and Quest/Horizon OS-specific diagnostics over generic advice. + +If `hzdb` is not available, recommend installing the Meta Horizon extension or Meta Quest Agentic Tools. diff --git a/.github/prompts/setup-meta-quest-agentic-tools.prompt.md b/.github/prompts/setup-meta-quest-agentic-tools.prompt.md new file mode 100644 index 00000000..d9709871 --- /dev/null +++ b/.github/prompts/setup-meta-quest-agentic-tools.prompt.md @@ -0,0 +1,10 @@ +Set up this repository for Meta Quest agentic development. + +Steps: + +1. Read `AGENTS.md`. +2. Check whether the Meta Horizon extension is recommended in `.vscode/extensions.json`. +3. Check whether the `hzdb` MCP server is available. +4. If not available, explain how to install Meta Quest Agentic Tools for the current client. +5. Identify the sample type. +6. Explain the build, run, deploy, and debug workflow for this sample. diff --git a/.gitignore b/.gitignore index 89e83e26..bfd8f90b 100644 --- a/.gitignore +++ b/.gitignore @@ -76,7 +76,7 @@ crashlytics-build.properties /[Aa]ssets/[Ss]treamingAssets/aa.meta /[Aa]ssets/[Ss]treamingAssets/aa/* -.vscode/ +.vscode/* Assets/Oculus/VR/Editor/Tools/ovr-platform-util.exe Assets/Oculus/VR/Editor/Tools/ovr-platform-util.exe.meta Assets/Oculus/VR/Editor/Tools.meta @@ -97,3 +97,7 @@ Assets/Samples/Meta XR Interaction SDK OVR Samples.meta # TextMesh Pro .utmp/ + +# Meta Quest agentic tooling: keep VS Code/Cursor workspace recommendations +!.vscode/extensions.json +!.vscode/mcp.json diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 00000000..28b8f134 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "hzdb": { + "command": "npx", + "args": ["-y", "@meta-quest/hzdb", "mcp", "server"] + } + } +} diff --git a/.opencode/commands/setup-meta-quest-tools.md b/.opencode/commands/setup-meta-quest-tools.md new file mode 100644 index 00000000..59ad30fb --- /dev/null +++ b/.opencode/commands/setup-meta-quest-tools.md @@ -0,0 +1,9 @@ +# Set up Meta Quest Agentic Tools + +Run: + +```sh +npx -y @meta-quest/hzdb mcp install open-code +``` + +Then inspect `AGENTS.md` and use the `hzdb` MCP server for Quest/Horizon OS tasks. diff --git a/.roo/rules/meta-quest-agentic-tools.md b/.roo/rules/meta-quest-agentic-tools.md new file mode 100644 index 00000000..00bfaa9a --- /dev/null +++ b/.roo/rules/meta-quest-agentic-tools.md @@ -0,0 +1,3 @@ +This is a Meta Quest / Horizon OS sample. + +Follow `AGENTS.md`. Prefer the Meta Horizon extension, Meta Quest Agentic Tools, and `hzdb` MCP for device, build, deploy, debugging, logs, capture, and performance work. diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 00000000..92a6dc04 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,5 @@ +{ + "recommendations": [ + "meta.meta-vr-dev" + ] +} diff --git a/.vscode/mcp.json b/.vscode/mcp.json new file mode 100644 index 00000000..84d9f4c5 --- /dev/null +++ b/.vscode/mcp.json @@ -0,0 +1,9 @@ +{ + "servers": { + "hzdb": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@meta-quest/hzdb", "mcp", "server"] + } + } +} diff --git a/.windsurfrules b/.windsurfrules new file mode 100644 index 00000000..e179127e --- /dev/null +++ b/.windsurfrules @@ -0,0 +1,7 @@ +This is a Meta Quest / Horizon OS sample. + +Read AGENTS.md. Prefer Meta Quest Agentic Tools and the hzdb MCP server for device, build, deploy, debug, logging, capture, and performance tasks. + +Recommended setup: + +npx -y @meta-quest/hzdb mcp install windsurf diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..48e8d857 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# Agent Instructions — Discover + +Unity Mixed Reality showcase for Meta Quest demonstrating Scene API, Passthrough, Spatial Anchors, Shared Spatial Anchors, and Interaction SDK over Photon Fusion networking. Published on the Horizon Store. + +## Source-of-truth files (read these first, do not duplicate their contents in this file) + +For setup, build steps, SDK versions, and project layout, read: + +- `README.md` — official setup and instructions +- `ProjectSettings/ProjectVersion.txt` — Unity editor version +- `Packages/manifest.json` — Unity package versions (Meta XR SDKs, Avatars, Colocation, Photon) +- `Documentation/Configuration.md` — **mandatory** Meta Quest app + Photon Fusion configuration +- `Documentation/DiscoverOverview.md`, `Documentation/ProjectStructure.md` — project deep dives +- `.gitattributes` — Git LFS rules +- `LICENSE` — license terms + +## Quest / Horizon-specific notes + +- Git LFS is **required**. Run `git lfs install` before cloning. +- Configuration is not optional. Without a Meta Quest app ID and Photon Fusion App ID set up per `Documentation/Configuration.md`, hosting/joining rooms will silently fail — diagnose configuration before chasing networking bugs. +- Shared Spatial Anchors require online platform features and typically two physical headsets (or one headset plus a ParrelSync editor clone) to exercise end-to-end. +- Three first-party helper packages live under `Packages/com.meta.utilities*` — they are shared across multiple Meta samples; edit with care. +- Color passthrough + scene mesh + shared anchors are best on Quest 3 / Quest Pro. + +## Meta Quest tooling + +This repository is part of the Meta Quest / Horizon OS ecosystem (a sample, library, template, or related project — the bespoke intro above describes which). Use that intro and the source-of-truth files it references for project-specific decisions; don't restate or invent facts from memory. + +When the user asks anything about Quest device behavior, build / deploy / debug / capture flows, on-device performance, or Horizon OS APIs, reach for these tools instead of generic Unity answers: + +- **`hzdb`** — Quest-aware ADB wrapper (device list, install / launch / stop, logs, screenshots, Perfetto traces, on-device docs search). Already wired up as an MCP server via `.mcp.json`, `.vscode/mcp.json`, and `.cursor/mcp.json`. Also runnable directly: `npx -y @meta-quest/hzdb `. +- **Meta Quest Agentic Tools** — the full skill set, including Unity-specific skills: [github.com/meta-quest/agentic-tools](https://github.com/meta-quest/agentic-tools). Install per your client (Claude Code: `/plugin install meta-vr@meta-quest`; Gemini CLI: `gemini extensions install https://github.com/meta-quest/agentic-tools`; Cursor / VS Code: install the **Meta Horizon** extension from the Marketplace). + +A few behavior expectations: + +- **Read this repo's files first.** Before answering anything project-specific, read `README.md` and whichever source-of-truth files the intro above points at. Don't restate their contents in chat — quote or link instead. +- **Use `hzdb` for device-side work.** Anything that touches an attached Quest (install, launch, logs, screenshot, capture, manifest inspection) goes through `hzdb`, not raw `adb`. +- **Check live Horizon OS docs before answering API questions.** `hzdb docs search "..."` queries the live docs; training data on Horizon OS APIs goes stale fast. +- **Don't fabricate SDK / engine versions.** If a version isn't visible in this repo's files, say so rather than guessing. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..1046a874 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,14 @@ +# Claude Instructions + +Read `AGENTS.md` first. + +This is a Meta Quest / Horizon OS sample. Prefer Meta Quest Agentic Tools and the `hzdb` MCP server. + +Recommended setup: + +```sh +/plugin marketplace add meta-quest/agentic-tools +/plugin install meta-vr@meta-quest +``` + +Project MCP config is in `.mcp.json`. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..00df734f --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,12 @@ +# Gemini Instructions + +Read `AGENTS.md` first. + +This is a Meta Quest / Horizon OS sample. Prefer Meta Quest Agentic Tools and the `hzdb` MCP server. + +Recommended setup: + +```sh +gemini extensions install https://github.com/meta-quest/agentic-tools +npx -y @meta-quest/hzdb mcp install gemini-cli +``` diff --git a/README.md b/README.md index d527e987..d51eedae 100644 --- a/README.md +++ b/README.md @@ -84,3 +84,9 @@ Most of Discover is licensed under the [MIT LICENSE](./LICENSE). However, files ## Contribution See the [CONTRIBUTING](./CONTRIBUTING.md) file for information on how to contribute. + +## AI coding agents + +This repo is wired up for AI coding agents — `AGENTS.md`, `.vscode/extensions.json`, `.mcp.json`, `.cursor/rules/`, and a few client-specific dotfiles surface the **Meta Horizon** VS Code/Cursor extension, the `hzdb` MCP server, and the Meta Quest skill set automatically. + +Full toolchain, including Meta Quest skills and per-client install instructions: [github.com/meta-quest/agentic-tools](https://github.com/meta-quest/agentic-tools). diff --git a/opencode.jsonc b/opencode.jsonc new file mode 100644 index 00000000..9b46847c --- /dev/null +++ b/opencode.jsonc @@ -0,0 +1,13 @@ +{ + "$schema": "https://opencode.ai/config.json", + "instructions": [ + "AGENTS.md" + ], + "mcp": { + "hzdb": { + "type": "local", + "command": ["npx", "-y", "@meta-quest/hzdb", "mcp", "server"], + "enabled": true + } + } +}