roblox-opencode 1.0.0 → 1.0.1

package/README.md

@@ -1,122 +1,112 @@
-<p align="center">
-  <img src="https://img.shields.io/badge/Roblox-OpenCode-blue?style=for-the-badge&logo=roblox&logoColor=white" alt="roblox-opencode" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/npm/v/roblox-opencode?style=flat-square&color=blue" alt="npm version" />
-  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license" />
-  <img src="https://img.shields.io/badge/Luau-100%25-purple?style=flat-square" alt="Luau" />
-  <img src="https://img.shields.io/badge/Fusion-0.3-orange?style=flat-square" alt="Fusion 0.3" />
-</p>
-
-<p align="center">
-  An OpenCode plugin that gives AI assistants deep knowledge of Roblox development.<br/>
-  17 skills, production-ready vendor libraries, and complete UI references. The AI writes code that actually works in Studio.
-</p>
-
-<br/>
-
-## Install
-
-```bash
-npm install roblox-opencode@git+https://github.com/TabooHarmony/roblox-opencode.git --prefix ~/.config/opencode
-```
-
-Then add to your `opencode.json` (global or project):
-
-```json
-{
-  "plugin": ["~/.config/opencode/node_modules/roblox-opencode"]
-}
-```
-
-Restart OpenCode, then run `/setup-game` in your project.
-
-> npm publish is coming soon. Once live, install with `opencode plugin roblox-opencode`.
-
-## What it does
-
-Without this plugin, AI assistants treat Roblox like a generic Lua environment. They miss session locking, write exploitable remotes, ignore mobile players, and produce UI that breaks on phones.
-
-With it, the AI knows:
-
-- How to structure a game (services, lifecycle, module patterns)
-- How to persist data safely (ProfileStore, session locking, migrations)
-- How to build reactive UI (Fusion 0.3, with complete shop/inventory/settings references)
-- How to secure remotes (validation, rate limiting, type checking)
-- How to ship (analytics, monetization, TOS compliance, publish checklist)
-- What NOT to do (13 documented production footguns ranked by severity)
-
-## Skills
-
-Loaded on-demand based on what you're working on. The AI picks the right ones automatically.
-
-| Domain | Skill | Covers |
-|--------|-------|--------|
-| Language | `roblox-luau-mastery` | Syntax, idioms, type system, strict mode |
-| UI | `roblox-gui` | Layout fundamentals, mobile-first, responsive patterns |
-| UI | `roblox-gui-fusion` | Fusion 0.3 reactive UI with full screen references |
-| VFX | `roblox-animation-vfx` | Tweens, particles, trails, highlights, camera shake |
-| Networking | `roblox-networking` | Security hardening, validation, rate limiting |
-| Data | `roblox-data` | ProfileStore, schema design, migrations, BindToClose |
-| Testing | `roblox-testing` | TestEZ, BDD patterns, test strategy |
-| Tooling | `roblox-tooling` | Studio MCP, luau-lsp, diagnostics |
-| Architecture | `roblox-architecture` | Service hierarchy, 7 foundational patterns |
-| Runtime | `roblox-runtime` | RunService, StreamingEnabled, memory |
-| Gotchas | `roblox-sharp-edges` | 13 production footguns by severity |
-| Money | `roblox-monetization` | GamePasses, DevProducts, subscriptions, TOS |
-| Sync | `roblox-sync` | Script Sync setup and troubleshooting |
-| Analytics | `roblox-analytics` | Events, economy tracking, funnels |
-| Review | `roblox-code-review` | Security, performance, networking, data lenses |
-| Debug | `roblox-debug` | Iterative debug loop for Luau issues |
-| Ship | `roblox-publish-checklist` | Pre-ship verification gauntlet |
-
-## Vendor libraries
-
-Copied to your project on setup. No Wally required.
-
-| Library | Purpose |
-|---------|---------|
-| **Fusion** | Reactive UI framework (dphfox, 0.3) |
-| **ProfileStore** | Data persistence with session locking |
-| **Promise** | Async flow control (evaera) |
-| **Signal** | Typed custom signals (Sleitnick) |
-| **Trove** | Cleanup/lifecycle management |
-| **Comm** | Typed client-server remotes |
-| **Component** | CollectionService tag binding |
-| **t** | Runtime type checking |
-| **TestEZ** | BDD testing framework |
-| + RbxUtil | 25 additional utility packages available on demand |
-
-## Commands
-
-| Command | What it does |
-|---------|--------------|
-| `/setup-game` | One-time project config: skills, vendor, LSP, AGENTS.md |
-| `/sync-check` | Verify Script Sync is working correctly |
-
-## How it works
-
-1. Plugin installs via npm on OpenCode startup
-2. You run `/setup-game` once per project
-3. Setup copies skills + vendor libs to `.opencode/`, writes LSP config, generates `.luaurc` aliases, injects a core block into `AGENTS.md`
-4. After that, the plugin is dormant. The skills do all the work.
-
-The AI loads relevant skills on-demand based on your prompt. Ask it to build a shop and it pulls in `roblox-gui-fusion`. Ask it to review security and it loads `roblox-code-review` with the networking lens.
-
-## Prerequisites
-
-- [OpenCode](https://opencode.ai)
-- [Roblox Studio](https://www.roblox.com/create) with Script Sync and MCP server enabled
-
-## Update
-
-Update the version in `opencode.json`, restart OpenCode, and run `/setup-game` again to refresh skills and vendor libs. Content outside managed markers in `AGENTS.md` is preserved.
-
-## Contributors
-
-- [MrFearTick](https://github.com/MrFearTick): Highlight reference, parent destruction patterns, networking lens, monetization expansion
-
-## License
-
-MIT
+<p align="center">
+  <img src="https://img.shields.io/badge/Roblox-OpenCode-blue?style=for-the-badge&logo=roblox&logoColor=white" alt="roblox-opencode" />
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/roblox-opencode?style=flat-square&color=blue" alt="npm version" />
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT license" />
+  <img src="https://img.shields.io/badge/Luau-100%25-purple?style=flat-square" alt="Luau" />
+  <img src="https://img.shields.io/badge/Fusion-0.3-orange?style=flat-square" alt="Fusion 0.3" />
+</p>
+
+<p align="center">
+  An OpenCode plugin that gives AI assistants deep knowledge of Roblox development.<br/>
+  17 skills, production-ready vendor libraries, and complete UI references. The AI writes code that actually works in Studio.
+</p>
+
+<br/>
+
+## Install
+
+```bash
+opencode plugin roblox-opencode
+```
+
+Then run `/setup-game` in your project.
+
+## What it does
+
+Without this plugin, AI assistants treat Roblox like a generic Lua environment. They miss session locking, write exploitable remotes, ignore mobile players, and produce UI that breaks on phones.
+
+With it, the AI knows:
+
+- How to structure a game (services, lifecycle, module patterns)
+- How to persist data safely (ProfileStore, session locking, migrations)
+- How to build reactive UI (Fusion 0.3, with complete shop/inventory/settings references)
+- How to secure remotes (validation, rate limiting, type checking)
+- How to ship (analytics, monetization, TOS compliance, publish checklist)
+- What NOT to do (13 documented production footguns ranked by severity)
+
+## Skills
+
+Loaded on-demand based on what you're working on. The AI picks the right ones automatically.
+
+| Domain | Skill | Covers |
+|--------|-------|--------|
+| Language | `roblox-luau-mastery` | Syntax, idioms, type system, strict mode |
+| UI | `roblox-gui` | Layout fundamentals, mobile-first, responsive patterns |
+| UI | `roblox-gui-fusion` | Fusion 0.3 reactive UI with full screen references |
+| VFX | `roblox-animation-vfx` | Tweens, particles, trails, highlights, camera shake |
+| Networking | `roblox-networking` | Security hardening, validation, rate limiting |
+| Data | `roblox-data` | ProfileStore, schema design, migrations, BindToClose |
+| Testing | `roblox-testing` | TestEZ, BDD patterns, test strategy |
+| Tooling | `roblox-tooling` | Studio MCP, luau-lsp, diagnostics |
+| Architecture | `roblox-architecture` | Service hierarchy, 7 foundational patterns |
+| Runtime | `roblox-runtime` | RunService, StreamingEnabled, memory |
+| Gotchas | `roblox-sharp-edges` | 13 production footguns by severity |
+| Money | `roblox-monetization` | GamePasses, DevProducts, subscriptions, TOS |
+| Sync | `roblox-sync` | Script Sync setup and troubleshooting |
+| Analytics | `roblox-analytics` | Events, economy tracking, funnels |
+| Review | `roblox-code-review` | Security, performance, networking, data lenses |
+| Debug | `roblox-debug` | Iterative debug loop for Luau issues |
+| Ship | `roblox-publish-checklist` | Pre-ship verification gauntlet |
+
+## Vendor libraries
+
+Copied to your project on setup. No Wally required.
+
+| Library | Purpose |
+|---------|---------|
+| **Fusion** | Reactive UI framework (dphfox, 0.3) |
+| **ProfileStore** | Data persistence with session locking |
+| **Promise** | Async flow control (evaera) |
+| **Signal** | Typed custom signals (Sleitnick) |
+| **Trove** | Cleanup/lifecycle management |
+| **Comm** | Typed client-server remotes |
+| **Component** | CollectionService tag binding |
+| **t** | Runtime type checking |
+| **TestEZ** | BDD testing framework |
+| + RbxUtil | 25 additional utility packages available on demand |
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/setup-game` | One-time project config: skills, vendor, LSP, AGENTS.md |
+| `/sync-check` | Verify Script Sync is working correctly |
+
+## How it works
+
+1. Plugin installs via npm on OpenCode startup
+2. You run `/setup-game` once per project
+3. Setup copies skills + vendor libs to `.opencode/`, writes LSP config, generates `.luaurc` aliases, injects a core block into `AGENTS.md`
+4. After that, the plugin is dormant. The skills do all the work.
+
+The AI loads relevant skills on-demand based on your prompt. Ask it to build a shop and it pulls in `roblox-gui-fusion`. Ask it to review security and it loads `roblox-code-review` with the networking lens.
+
+## Prerequisites
+
+- [OpenCode](https://opencode.ai)
+- [Roblox Studio](https://www.roblox.com/create) with Script Sync and MCP server enabled
+
+## Update
+
+Update the version in `opencode.json`, restart OpenCode, and run `/setup-game` again to refresh skills and vendor libs. Content outside managed markers in `AGENTS.md` is preserved.
+
+## Contributors
+
+- [MrFearTick](https://github.com/MrFearTick): Highlight reference, parent destruction patterns, networking lens, monetization expansion
+
+## License
+
+MIT

package/commands/setup-game.md

@@ -1,108 +1,108 @@
----
-description: "First-time Roblox project setup: skills, vendor libs, LSP, sync"
-agent: build
----
-
-# /setup-game
-
-One-time project configuration for roblox-opencode. Run this when you first open a Roblox project.
-
-Commands (`/setup-game`, `/sync-check`) are already available globally. Skills (`roblox-code-review`, `roblox-debug`, `roblox-publish-checklist`) are loaded on demand. This command sets up the *project*.
-
----
-
-## Step 1: Run the setup tool
-
-Call the `roblox_setup` tool. It handles:
-- Copying 17 skills to `.opencode/skills/`
-- Copying vendor libraries (rbxutil, profilestore, promise, testez, t, fusion) to `.opencode/vendor/`
-- Writing luau-lsp config to `opencode.json`
-- Writing the core Roblox agent instructions to `AGENTS.md`
-
-Report the results to the user. If any step failed, explain what went wrong and how to fix it.
-
-## Step 2: Check prerequisites
-
-Run these checks (cross-platform):
-
-```bash
-command -v luau-lsp   # needed for Luau diagnostics
-```
-
-If luau-lsp is missing: point user to https://github.com/JohnnyMorganz/luau-lsp/releases and guide install. If declined, note: "Reduced safety net. Install luau-lsp later and re-run /setup-game."
-
-## Step 3: Download globalTypes.d.luau
-
-If luau-lsp is installed, download the Roblox type definitions:
-
-```bash
-curl -fsSL https://luau-lsp.pages.dev/type-definitions/globalTypes.RobloxScriptSecurity.d.luau -o globalTypes.d.luau
-```
-
-This file provides Roblox API types to luau-lsp. The `--definitions` flag in the LSP config (from Step 1) points to it.
-
-## Step 4: Enable Studio MCP
-
-The Roblox Studio MCP server is built into Studio. To enable it:
-
-1. Open Roblox Studio
-2. Open Assistant (View → Assistant)
-3. Click `…` → Manage MCP Servers
-4. Turn on **Enable Studio as MCP server**
-
-For opencode to connect, add this to your project's `opencode.json`:
-
-**Windows:**
-```json
-{
-  "mcp": {
-    "studio": {
-      "type": "local",
-      "command": ["cmd.exe", "/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"],
-      "enabled": true
-    }
-  }
-}
-```
-
-**macOS:**
-```json
-{
-  "mcp": {
-    "studio": {
-      "type": "local",
-      "command": ["/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"],
-      "enabled": true
-    }
-  }
-}
-```
-
-After adding the config, restart opencode to connect.
-
-## Step 5: Sync setup
-
-Hand off Script Sync setup to the user with these instructions:
-
-"Enable Script Sync in Roblox Studio:
-1. File → Beta Features → Script Sync → toggle on → restart Studio
-2. In Explorer, right-click each top-level container with scripts (ServerScriptService, ReplicatedStorage, etc.) → Start Sync → pick a folder
-
-Suggested folder layout: ~/projects/<game-name>/src/<container-name>/"
-
-"You should now see your scripts in Studio's Explorer matching the files on disk. If you do, sync is working. If the container looks empty, double-check you picked the right folder and that Studio is focused (sync pauses when minimized). Run /sync-check if you need to verify later."
-
-## Step 6: Print the command tour
-
-"roblox-opencode is ready. Here's what you can do:
-
-**Commands** (type `/` to use):
-- /setup-game - re-run this setup (after plugin updates)
-- /sync-check - check if Script Sync is working properly
-
-**Skills** (AI suggests when relevant):
-- roblox-code-review - review code with security/performance/monetization lenses
-- roblox-debug - iterative debug loop for Luau/Roblox issues
-- roblox-publish-checklist - pre-ship gauntlet before publishing
-
-The harness is loaded. Prompt normally - the AI will suggest skills when relevant."
+---
+description: "First-time Roblox project setup: skills, vendor libs, LSP, sync"
+agent: build
+---
+
+# /setup-game
+
+One-time project configuration for roblox-opencode. Run this when you first open a Roblox project.
+
+Commands (`/setup-game`, `/sync-check`) are already available globally. Skills (`roblox-code-review`, `roblox-debug`, `roblox-publish-checklist`) are loaded on demand. This command sets up the *project*.
+
+---
+
+## Step 1: Run the setup tool
+
+Call the `roblox_setup` tool. It handles:
+- Copying 17 skills to `.opencode/skills/`
+- Copying vendor libraries (rbxutil, profilestore, promise, testez, t, fusion) to `.opencode/vendor/`
+- Writing luau-lsp config to `opencode.json`
+- Writing the core Roblox agent instructions to `AGENTS.md`
+
+Report the results to the user. If any step failed, explain what went wrong and how to fix it.
+
+## Step 2: Check prerequisites
+
+Run these checks (cross-platform):
+
+```bash
+command -v luau-lsp   # needed for Luau diagnostics
+```
+
+If luau-lsp is missing: point user to https://github.com/JohnnyMorganz/luau-lsp/releases and guide install. If declined, note: "Reduced safety net. Install luau-lsp later and re-run /setup-game."
+
+## Step 3: Download globalTypes.d.luau
+
+If luau-lsp is installed, download the Roblox type definitions:
+
+```bash
+curl -fsSL https://luau-lsp.pages.dev/type-definitions/globalTypes.RobloxScriptSecurity.d.luau -o globalTypes.d.luau
+```
+
+This file provides Roblox API types to luau-lsp. The `--definitions` flag in the LSP config (from Step 1) points to it.
+
+## Step 4: Enable Studio MCP
+
+The Roblox Studio MCP server is built into Studio. To enable it:
+
+1. Open Roblox Studio
+2. Open Assistant (View → Assistant)
+3. Click `…` → Manage MCP Servers
+4. Turn on **Enable Studio as MCP server**
+
+For opencode to connect, add this to your project's `opencode.json`:
+
+**Windows:**
+```json
+{
+  "mcp": {
+    "studio": {
+      "type": "local",
+      "command": ["cmd.exe", "/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**macOS:**
+```json
+{
+  "mcp": {
+    "studio": {
+      "type": "local",
+      "command": ["/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"],
+      "enabled": true
+    }
+  }
+}
+```
+
+After adding the config, restart opencode to connect.
+
+## Step 5: Sync setup
+
+Hand off Script Sync setup to the user with these instructions:
+
+"Enable Script Sync in Roblox Studio:
+1. File → Beta Features → Script Sync → toggle on → restart Studio
+2. In Explorer, right-click each top-level container with scripts (ServerScriptService, ReplicatedStorage, etc.) → Start Sync → pick a folder
+
+Suggested folder layout: ~/projects/<game-name>/src/<container-name>/"
+
+"You should now see your scripts in Studio's Explorer matching the files on disk. If you do, sync is working. If the container looks empty, double-check you picked the right folder and that Studio is focused (sync pauses when minimized). Run /sync-check if you need to verify later."
+
+## Step 6: Print the command tour
+
+"roblox-opencode is ready. Here's what you can do:
+
+**Commands** (type `/` to use):
+- /setup-game - re-run this setup (after plugin updates)
+- /sync-check - check if Script Sync is working properly
+
+**Skills** (AI suggests when relevant):
+- roblox-code-review - review code with security/performance/monetization lenses
+- roblox-debug - iterative debug loop for Luau/Roblox issues
+- roblox-publish-checklist - pre-ship gauntlet before publishing
+
+The harness is loaded. Prompt normally - the AI will suggest skills when relevant."

package/commands/sync-check.md

@@ -1,53 +1,53 @@
----
-description: "Sync sanity check - diagnose when files aren't appearing in Studio"
-agent: build
----
-
-# /sync-check
-
-On-demand sync sanity check. Run when files aren't appearing in Studio or edits aren't landing on disk.
-
----
-
-## Step 1: Check mode detection
-
-Try to read any `.luau` file from the project's synced folder. If files exist on disk, you're in Sync Mode. If not, you're in MCP-Only Mode.
-
-Report which mode is active.
-
-## Step 2: Sentinel round-trip (Sync Mode only)
-
-1. Write `_sync_check.luau` to the synced folder with content: `-- roblox-opencode sync verification sentinel`
-2. Ask user: "Did `_sync_check.luau` appear in Studio's Explorer?"
-3. If yes: clean up the sentinel file. Report: "Sync is healthy."
-4. If no: proceed to Step 3.
-
-## Step 3: Troubleshooting (if sentinel failed)
-
-Walk through these in order:
-
-1. "Is Script Sync still enabled? Check File → Beta Features → Script Sync."
-2. "Did you right-click the container and Start Sync to the correct folder?"
-3. "Is Studio focused? Script Sync pauses when Studio is minimized or in the background."
-4. "Try: stop sync on the container, re-start sync, pick the same folder."
-
-If none of these resolve it:
-
-- "Script Sync may have silently disconnected. Restart Studio and re-run /sync-check."
-- Do NOT suggest switching to MCP as a fix. Sync is the canonical path.
-
-## Step 4: MCP-Only Mode check
-
-If in MCP-Only Mode (no files on disk):
-
-1. Check if Studio MCP is registered in opencode.json.
-2. Try a simple MCP call (e.g., list scripts in ServerScriptService).
-3. If MCP responds: "MCP-Only mode is working, but sync is recommended for heavy sessions. Run /setup-game to enable sync."
-4. If MCP fails: "Neither sync nor MCP is working. Run /setup-game to configure the environment."
-
-## Behavior rules
-
-- One diagnostic pass. Don't loop.
-- If sync works, say so and stop. No upselling.
-- If sync is broken, help fix it. Don't suggest MCP as a replacement.
-- Clean up the sentinel file whether the check passes or fails.
+---
+description: "Sync sanity check - diagnose when files aren't appearing in Studio"
+agent: build
+---
+
+# /sync-check
+
+On-demand sync sanity check. Run when files aren't appearing in Studio or edits aren't landing on disk.
+
+---
+
+## Step 1: Check mode detection
+
+Try to read any `.luau` file from the project's synced folder. If files exist on disk, you're in Sync Mode. If not, you're in MCP-Only Mode.
+
+Report which mode is active.
+
+## Step 2: Sentinel round-trip (Sync Mode only)
+
+1. Write `_sync_check.luau` to the synced folder with content: `-- roblox-opencode sync verification sentinel`
+2. Ask user: "Did `_sync_check.luau` appear in Studio's Explorer?"
+3. If yes: clean up the sentinel file. Report: "Sync is healthy."
+4. If no: proceed to Step 3.
+
+## Step 3: Troubleshooting (if sentinel failed)
+
+Walk through these in order:
+
+1. "Is Script Sync still enabled? Check File → Beta Features → Script Sync."
+2. "Did you right-click the container and Start Sync to the correct folder?"
+3. "Is Studio focused? Script Sync pauses when Studio is minimized or in the background."
+4. "Try: stop sync on the container, re-start sync, pick the same folder."
+
+If none of these resolve it:
+
+- "Script Sync may have silently disconnected. Restart Studio and re-run /sync-check."
+- Do NOT suggest switching to MCP as a fix. Sync is the canonical path.
+
+## Step 4: MCP-Only Mode check
+
+If in MCP-Only Mode (no files on disk):
+
+1. Check if Studio MCP is registered in opencode.json.
+2. Try a simple MCP call (e.g., list scripts in ServerScriptService).
+3. If MCP responds: "MCP-Only mode is working, but sync is recommended for heavy sessions. Run /setup-game to enable sync."
+4. If MCP fails: "Neither sync nor MCP is working. Run /setup-game to configure the environment."
+
+## Behavior rules
+
+- One diagnostic pass. Don't loop.
+- If sync works, say so and stop. No upselling.
+- If sync is broken, help fix it. Don't suggest MCP as a replacement.
+- Clean up the sentinel file whether the check passes or fails.