v0.3.0 — Godot MCP Integration

.opencode/agents/gameplay-programmer.md

@@ -130,3 +130,7 @@ If an ADR exists for this system:
 **Conflict resolution**: If a design spec conflicts with technical constraints,
 document the conflict and escalate to `lead-programmer` and `game-designer`
 jointly. Do not unilaterally change the design or the architecture.
+
+### MCP Integration
+
+- Use the godot-mcp server to run the project and capture debug output for iterative debugging

.opencode/agents/godot-gdscript-specialist.md

@@ -260,3 +260,7 @@ When in doubt, prefer the API documented in the reference files over your traini
 - Work with **godot-gdextension-specialist** for GDScript/C++ boundary decisions
 - Work with **systems-designer** for data-driven design patterns
 - Work with **performance-analyst** for profiling GDScript bottlenecks
+
+## MCP Integration
+
+- Use the godot-mcp server (create_scene, add_node, save_scene) for rapid scene prototyping and verification

.opencode/agents/godot-specialist.md

@@ -181,3 +181,7 @@ Always involve this agent when:
 - Setting up input mapping or UI with Godot's Control nodes
 - Configuring export presets for any platform
 - Optimizing rendering, physics, or memory in Godot
+
+## MCP Integration
+
+- Use the godot-mcp server (get_project_info, list_projects) to audit project structure and configuration

.opencode/agents/qa-tester.md

@@ -242,4 +242,8 @@ After a bug fix or hotfix, produce a **targeted** regression checklist, not a fu
 - Skip test steps for speed (every step must be executed)
 - Approve releases (defer to qa-lead)
 
+### MCP Integration
+
+- Use the godot-mcp server for automated smoke testing: call `run_project`, poll `get_debug_output`, and check for errors
+
 ### Reports to: `qa-lead`

.opencode/agents/ui-programmer.md

@@ -99,3 +99,7 @@ Before writing any code:
 
 ### Reports to: `lead-programmer`
 ### Implements specs from: `art-director`, `ux-designer`
+
+### MCP Integration
+
+- Use the godot-mcp server (run_project, get_debug_output) to test UI scenes in-game

.opencode/docs/quick-start.md

@@ -135,6 +135,7 @@ Ask yourself: "What department would handle this in a real studio?"
 | `/qa-plan` | Generate a QA test plan for a sprint or feature |
 | `/bug-triage` | Re-prioritize open bugs, assign to sprints, surface systemic trends |
 | `/smoke-check` | Run critical path smoke test gate before QA hand-off (PASS/FAIL) |
+| `/automated-smoke-test` | Launch the project via godot-mcp and check for startup errors |
 | `/soak-test` | Generate a soak test protocol for extended play sessions |
 | `/regression-suite` | Map coverage to GDD critical paths, flag gaps, maintain regression suite |
 | `/test-setup` | Scaffold test framework + CI pipeline for the project's engine (run once) |
@@ -215,14 +216,21 @@ If you already know what you need, jump directly to the relevant path:
      performance budgets, and engine-specific defaults
    - If the engine version is newer than the LLM's training data, it fetches
      current docs from the web so agents suggest correct APIs
-3. **Validate the concept** — Run `/design-review design/gdd/game-concept.md`
-4. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies
-5. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`)
+3. **Enhance with godot-mcp (Godot only)** — Install the optional MCP server
+   for automated editor control and smoke testing:
+   ```bash
+   npx @coding-solo/godot-mcp
+   ```
+   Once configured, run `/automated-smoke-test` to verify the project launches
+   without errors.
+4. **Validate the concept** — Run `/design-review design/gdd/game-concept.md`
+5. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies
+6. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`)
    to write GDDs in dependency order
-6. **Test the core loop** — Run `/prototype [core-mechanic]`
-7. **Playtest it** — Run `/playtest-report` to validate the hypothesis
-8. **Plan the first sprint** — Run `/sprint-plan new`
-9. Start building
+7. **Test the core loop** — Run `/prototype [core-mechanic]`
+8. **Playtest it** — Run `/playtest-report` to validate the hypothesis
+9. **Plan the first sprint** — Run `/sprint-plan new`
+10. Start building
 
 ### Path B: "I know what I want to build"
 

.opencode/docs/setup-requirements.md

@@ -78,3 +78,23 @@ Claude Code works with any editor, but the template is optimized for:
 - **VS Code** with the Claude Code extension
 - **Cursor** (Claude Code compatible)
 - Terminal-based Claude Code CLI
+
+## Optional Engine Dependencies
+
+### Godot-MCP (Optional — Godot Only)
+
+The [godot-mcp](https://github.com/Coding-Solo/godot-mcp) server provides runtime tools for AI-driven testing and debugging of Godot projects. It enables agents to launch the editor, run projects, and capture debug output automatically.
+
+**Installation:**
+```bash
+npx @coding-solo/godot-mcp
+```
+
+**Configuration:**
+The MCP server is configured via `opencode.json` or editor MCP settings. See `/setup-engine` for full setup guidance.
+
+**Tools provided:**
+- `launch_editor`, `run_project`, `stop_project` — runtime control
+- `get_debug_output` — live debug feedback
+- `create_scene`, `add_node`, `save_scene` — scene manipulation
+- `get_godot_version`, `get_project_info`, `list_projects` — project introspection

.opencode/docs/skills-reference.md

@@ -1,6 +1,6 @@
 # Available Skills (Slash Commands)
 
-68 slash commands organized by phase. Type `/` in Claude Code to access any of them.
+73 slash commands organized by phase. Type `/` in OpenCode to access any of them.
 
 ## Onboarding & Navigation
 
@@ -71,6 +71,7 @@
 
 | Command | Purpose |
 |---------|---------|
+| `/automated-smoke-test` | Run an automated smoke test using the godot-mcp server. Launches the project, captures debug output, and checks for errors or crashes. |
 | `/qa-plan` | Generate a QA test plan for a sprint or feature |
 | `/smoke-check` | Run critical path smoke test gate before QA hand-off |
 | `/soak-test` | Generate a soak test protocol for extended play sessions |

.opencode/skills/automated-smoke-test/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: automated-smoke-test
+description: "Run an automated smoke test using the godot-mcp server. Launches the project, captures debug output, and checks for errors or crashes."
+argument-hint: "[duration-seconds]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Bash, Task, question
+---
+
+# Automated Smoke Test
+
+This skill runs a fully automated smoke test against the Godot project using
+the godot-mcp server. It launches the project headlessly, captures debug output
+for a configurable duration, and analyzes the output for errors, warnings, and
+assertions — producing a structured pass/fail report.
+
+No manual verification required. The entire check is automated through MCP.
+
+---
+
+## Phase 1: Verify godot-mcp Availability
+
+Call `get_godot_version` via the godot-mcp server. If the call succeeds, note
+the version string. If it fails, inform the user:
+
+> "godot-mcp server is not available. Install it with:
+> `npx @coding-solo/godot-mcp`
+> Then configure the MCP server in `opencode.json`."
+
+Stop if the server is unavailable.
+
+---
+
+## Phase 2: Read Project Info
+
+Call `get_project_info` via godot-mcp. Record:
+
+- **Project title** — from the project info response
+- **Main scene** — the configured main scene path
+- **Render mode** — e.g. Forward+, Mobile, GL Compatible
+
+If `get_project_info` fails, retry up to 3 times with a 2-second delay between
+attempts. If all retries fail: "Could not read project info after 3 attempts. Is
+the godot-mcp server running against the correct project?" Then stop.
+
+---
+
+## Phase 3: Run the Project
+
+Parse the optional argument for duration. If no argument is provided, default
+to 10 seconds. The argument is in seconds: `/automated-smoke-test 15` means
+capture output for 15 seconds.
+
+Call `run_project` via godot-mcp. The project must respond (start or error)
+within 30 seconds. If no response within the timeout, treat as a failure:
+- Report: "Project failed to respond within 30 seconds — the project may be hung
+  or the engine may have frozen during launch."
+- Verdict: **FAIL**
+- Skip to Phase 7 (Report) — the project is unresponsive, stop would also hang
+
+If `run_project` returns an error or the project fails to start:
+- Report: "Project failed to start with error: [error message]"
+- Verdict: **FAIL**
+- Skip to Phase 7 (Report) — project was never launched, no stop needed
+
+---
+
+## Phase 4: Capture Debug Output
+
+> **Duration scaling:** The capture duration should reflect project complexity.
+> A minimal 2D project may produce output in 5 seconds; a large 3D project with
+> many scenes may need 30+ seconds. Default to 10 seconds but consider the
+> project's scope (from Phase 2's project info) and scale up for complex titles.
+> For headless CI runs, prefer longer durations to account for slower hardware.
+
+If `get_debug_output` returns an error:
+- Report: "Could not capture debug output: [error message]"
+- Verdict: **FAIL**
+- Skip to Phase 6 (stop project), then continue to Phase 7 for the report
+
+Do not use a fixed sleep. Instead, poll `get_debug_output` in a loop:
+
+1. Every 2 seconds, call `get_debug_output`.
+2. If the output contains any ERROR, crash, or assertion pattern (see Phase 5),
+   stop polling early — the test has already found failures.
+3. If no errors appear, continue polling until the configured duration elapses
+   (default: 10 seconds, configurable via argument).
+4. If `get_debug_output` returns an error on any poll tick:
+   - Report: "Could not capture debug output on poll attempt [N]: [error message]"
+   - Continue polling (do not abort) unless 3 consecutive polls fail.
+   - After 3 consecutive failures: "Debug output capture failed after 3
+     consecutive poll errors."
+   - Verdict: **FAIL**
+   - Skip to Phase 6
+
+Once polling ends (duration elapsed or early-stop triggered), use the last
+successful output for analysis. If all polls failed (3 consecutive errors),
+there is no output to analyze — skip directly to the FAIL verdict.
+
+If the final output is empty or trivially short, note: "Output appears minimal
+— the project may not have rendered any frames."
+
+---
+
+## Phase 5: Analyze Output
+
+Scan the debug output for:
+
+| Pattern | Severity | Flags |
+|---------|----------|-------|
+| `ERROR` | Error | Catch-all for Godot error messages |
+| `error:` | Error | Lower-case variant in scripts |
+| `crash` | Critical | Game crashed during runtime |
+| `NullReferenceException` | Error | Null access in C# script (.NET) |
+| `segfault` | Critical | Memory access violation |
+| `segmentation fault` | Critical | Full-form segfault message |
+| `WARNING` | Warning | Non-fatal warnings |
+| `warning:` | Warning | Lower-case variant |
+| `Assertion failed` | Error | GDScript or C# assertion failure |
+
+Count the occurrences of each pattern. Record the actual matching lines (up to
+10 per pattern for the report).
+
+---
+
+## Phase 6: Stop the Project
+
+Call `stop_project` via godot-mcp to clean up. If it fails, note:
+"Could not stop the project cleanly — you may need to close the Godot
+editor or kill the process manually."
+
+---
+
+## Phase 7: Report Results
+
+Format the report:
+
+```markdown
+## Automated Smoke Test Report
+
+**Date**: [date]
+**Project**: [project title]
+**Main Scene**: [main scene path]
+**Godot Version**: [version from Phase 1]
+**Duration**: [X seconds]
+
+---
+
+### Results
+
+| Check | Result |
+|-------|--------|
+| Project launched | ✅ / ❌ |
+| No runtime errors | ✅ / ❌ (N errors found) |
+| No critical crashes | ✅ / ❌ (N crashes detected) |
+| No warnings | ✅ / ⚠️ (N warnings) |
+| No assertion failures | ✅ / ❌ (N assertions failed) |
+
+---
+
+### Error Details
+
+[If errors/crashes found, include the matching lines in a code block.
+Otherwise: "No errors detected."]
+
+---
+
+### Warning Details
+
+[If warnings found, include the matching lines in a code block.
+Otherwise: "No warnings detected."]
+
+---
+
+### Verdict: [PASS | FAIL | SILENT-FAIL]
+
+**FAIL** if ANY of:
+- Project failed to start
+- Runtime errors or crashes detected
+- Assertion failures found
+- Debug output could not be captured after retries
+
+**SILENT-FAIL** if:
+- Project launched successfully AND no errors/crashes detected BUT
+  debug output was empty or trivially short (zero or near-zero lines).
+  This means the project may have started but produced no frames or
+  lifecycle output — a configuration problem or silent hang. The user
+  should verify manually.
+
+**PASS** if ALL of:
+- Project launched successfully
+- Debug output contains substantive content (not SILENT-FAIL threshold)
+- No runtime errors or crashes
+- No assertion failures
+- Warnings are acceptable (advisory only — do not cause FAIL)
+```
+
+Present the report to the user. Do not write it to a file unless asked.

.opencode/skills/setup-engine/SKILL.md

@@ -384,6 +384,62 @@ Wait for confirmation before writing any files.
 5. **For module files**: Only create modules for subsystems where significant
    changes occurred. Don't create empty or minimal module files.
 
+### 7.3. Configure godot-mcp (Optional — Godot Only)
+
+If Godot was chosen as the engine, the AI can work more effectively with the
+[godot-mcp](https://github.com/Coding-Solo/godot-mcp) server, which provides
+runtime tools for interacting with the Godot editor and running project:
+
+**Available MCP tools:**
+- `launch_editor` — launch the Godot editor
+- `run_project` — run the current project
+- `get_debug_output` — capture live debug output from the running project
+- `stop_project` — stop the running project
+- `get_godot_version` — check the installed Godot version
+- `list_projects` — list all Godot projects
+- `get_project_info` — get metadata about the project
+- `create_scene` — create a new scene file
+- `add_node` — add nodes to a scene
+- `load_sprite` — load a sprite resource
+- `save_scene` — save a scene file
+- `export_mesh_library` — export a mesh library
+- `get_uid` — get a resource UID
+- `update_project_uids` — update project resource UIDs
+
+**Installation:**
+```bash
+# Install via npx (no global install needed)
+# Pin to a specific version in production (e.g., @coding-solo/godot-mcp@1.0.0)
+npx @coding-solo/godot-mcp@latest
+```
+
+**OpenCode MCP configuration:**
+Add to `opencode.json` or the appropriate MCP config file:
+```json
+{
+  "mcpServers": {
+    "godot": {
+      "command": "npx",
+      "args": ["@coding-solo/godot-mcp"],
+      "env": {
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+> **Note:** `DEBUG=true` enables verbose logging of all MCP communication (requests, responses, and debug info). Use it when troubleshooting MCP tool issues or during initial setup. Disable (`"DEBUG": "false"` or remove the variable) in normal use to reduce log noise.
+
+**Environment setup:**
+Optionally set `GODOT_PATH` if the Godot binary is not in PATH:
+```json
+"env": {
+  "GODOT_PATH": "/path/to/godot",
+  "DEBUG": "true"
+}
+```
+
 ---
 
 ## 8. Update CLAUDE.md Import