diff --git a/.opencode/agents/gameplay-programmer.md b/.opencode/agents/gameplay-programmer.md index b14f71b..4a5b6ec 100644 --- a/.opencode/agents/gameplay-programmer.md +++ b/.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 diff --git a/.opencode/agents/godot-gdscript-specialist.md b/.opencode/agents/godot-gdscript-specialist.md index 9e918a4..d1ac300 100644 --- a/.opencode/agents/godot-gdscript-specialist.md +++ b/.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 diff --git a/.opencode/agents/godot-specialist.md b/.opencode/agents/godot-specialist.md index a8b5457..bd7732d 100644 --- a/.opencode/agents/godot-specialist.md +++ b/.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 diff --git a/.opencode/agents/qa-tester.md b/.opencode/agents/qa-tester.md index cb94bbe..ce76acb 100644 --- a/.opencode/agents/qa-tester.md +++ b/.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: run_project → capture debug output → check for errors + ### Reports to: `qa-lead` diff --git a/.opencode/agents/ui-programmer.md b/.opencode/agents/ui-programmer.md index 310c5d2..b14a8f1 100644 --- a/.opencode/agents/ui-programmer.md +++ b/.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 diff --git a/.opencode/docs/quick-start.md b/.opencode/docs/quick-start.md index ba9c921..05381ea 100644 --- a/.opencode/docs/quick-start.md +++ b/.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" diff --git a/.opencode/docs/setup-requirements.md b/.opencode/docs/setup-requirements.md index 0f9559a..af26058 100644 --- a/.opencode/docs/setup-requirements.md +++ b/.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 diff --git a/.opencode/docs/skills-reference.md b/.opencode/docs/skills-reference.md index 0ff391f..7409482 100644 --- a/.opencode/docs/skills-reference.md +++ b/.opencode/docs/skills-reference.md @@ -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 | diff --git a/.opencode/skills/automated-smoke-test/SKILL.md b/.opencode/skills/automated-smoke-test/SKILL.md new file mode 100644 index 0000000..e36a2c3 --- /dev/null +++ b/.opencode/skills/automated-smoke-test/SKILL.md @@ -0,0 +1,196 @@ +--- +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 6 (do not attempt stop) + +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 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. diff --git a/.opencode/skills/setup-engine/SKILL.md b/.opencode/skills/setup-engine/SKILL.md index 8991c1b..93d785a 100644 --- a/.opencode/skills/setup-engine/SKILL.md +++ b/.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