Add agentic development setup

zbowling · zbowling · commit 6e7bb90d6c75 · 2026-05-27T18:37:00.000-07:00
Adds repository instructions, MCP configuration, VS Code/Cursor extension recommendations, and setup docs for Meta Quest Agentic Tools.
diff --git a/.aider.conf.yml b/.aider.conf.yml
@@ -0,0 +1,2 @@
+read:
+  - AGENTS.md
diff --git a/.claude/settings.json 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
@@ -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
@@ -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
@@ -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 WebXR 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
@@ -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
@@ -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 WebXR — prefer Quest/Horizon OS-specific tooling and terminology over generic WebXR advice.
diff --git a/.github/prompts/debug-on-quest.prompt.md 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
@@ -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
@@ -13,9 +13,13 @@ build/
 dist/
 node_modules/
 
-/.vscode/
+.vscode/*
 
 # blender backups
 *.blend?
 
-.DS_Store
+.DS_Store
+
+# Meta Quest agentic tooling: keep VS Code/Cursor workspace recommendations
+!.vscode/extensions.json
+!.vscode/mcp.json
diff --git a/.mcp.json 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
@@ -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
@@ -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
@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "meta.meta-vr-dev"
+  ]
+}
diff --git a/.vscode/mcp.json 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
@@ -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
@@ -0,0 +1,36 @@
+# Agent Instructions — Reality Accelerator Toolkit (RATK)
+
+TypeScript WebXR utilities library that bridges low-level WebXR mixed-reality APIs (planes, meshes, anchors, hit tests) to three.js `Object3D` instances.
+
+## 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
+- `package.json` — Node / npm dependencies, peer dependencies, build scripts
+- `tsconfig.json` — TypeScript configuration
+- `rollup.config.js` — bundler configuration
+- `LICENSE.md` — license terms
+
+## Quest / Horizon-specific notes
+
+- This is a publishable library (`ratk` on npm), not a runnable Quest APK — there is no `AndroidManifest.xml` and no app to deploy. The Quest target is reached indirectly via Quest Browser running a WebXR page that consumes the library.
+- `three.js` is a **peer dependency**, not bundled — the consuming app must supply it. Do not move it to `dependencies`.
+- The `example/` directory contains a runnable demo (hosted via the GitHub Pages site referenced in the README) that exercises planes, meshes, anchors, and hit-testing — it is the most useful end-to-end reference when changing toolkit behavior.
+- The WebXR session must request the relevant features (`hit-test`, `plane-detection`, `mesh-detection`, `anchors`) at session-init time or the corresponding RATK code paths stay empty.
+
+## 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 WebXR 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 <subcommand>`.
+- **Meta Quest Agentic Tools** — the full skill set, including WebXR-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
@@ -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
@@ -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
@@ -181,3 +181,9 @@ Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribut
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE.md](./LICENSE.md) file for details.
+
+## 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
@@ -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
+    }
+  }
+}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+This is a Meta Quest / Horizon OS sample.`
	`2`	`+`
	`3`	+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.