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..9b17c8e 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: call `run_project`, poll `get_debug_output`, and 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..8b54526 100644 --- a/.opencode/docs/skills-reference.md +++ b/.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 | diff --git a/.opencode/skills/automated-smoke-test/SKILL.md b/.opencode/skills/automated-smoke-test/SKILL.md new file mode 100644 index 0000000..3568967 --- /dev/null +++ b/.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. 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 diff --git a/README.md b/README.md index 6d41941..d97d36e 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Agents](https://img.shields.io/badge/agents-49-blueviolet)](.opencode/agents/) -[![Skills](https://img.shields.io/badge/skills-72-brightgreen)](.opencode/skills/) +[![Skills](https://img.shields.io/badge/skills-73-brightgreen)](.opencode/skills/) [![Hooks](https://img.shields.io/badge/hooks-12-orange)](.opencode/plugins/) [![Tests](https://img.shields.io/badge/tests-129-success)](.opencode/plugins/tests/) [![Built for OpenCode](https://img.shields.io/badge/built%20for-OpenCode-5f5f5f)](https://opencode.ai) @@ -43,7 +43,7 @@ are some workarounds for Claude Code to access other models through local proxie this is not the intended use of Claude Code and such setups are fragile at best. This port adapts the complete [CCGS](https://github.com/Donchitos/Claude-Code-Game-Studios) -framework — its 49 agents, 72 skills, 12 hooks, and all rules — to run natively +framework — its 49 agents, 73 skills, 12 hooks, and all rules — to run natively on OpenCode, giving game teams the same structured AI-assisted workflow without the artificial limits. @@ -60,7 +60,7 @@ the artificial limits. | Component | CCGS (Claude Code) | OpenCode | Status | |-----------|-------------------|----------|--------| | 🤖 **Agents** | 49 agents (`.claude/agents/`) | 49 agents (`.opencode/agents/`) | ✅ | -| ⌨️ **Skills** | 72 skills (`.claude/skills/`) | 72 skills (`.opencode/skills/`) | ✅ | +| ⌨️ **Skills** | 72 skills (`.claude/skills/`) | 73 skills (`.opencode/skills/`) | ✅ +1 | | 🔗 **Hooks** | 12 bash hooks (`.claude/hooks/`) | 1 TS plugin (`.opencode/plugins/`) | ✅ **129 tests** | | 📏 **Rules** | 11 rule files (`.claude/rules/`) | 11 rule files (`.opencode/rules/`) | ✅ | | ⚙️ **Config** | `CLAUDE.md` + `.claude/settings.json` | `AGENTS.md` + `opencode.json` | ✅ | @@ -73,7 +73,7 @@ the artificial limits. opencode ``` -Type `/` to browse all 72 skills, or `/start` for onboarding. +Type `/` to browse all 73 skills, or `/start` for onboarding. --- @@ -193,7 +193,7 @@ node utils/assign-models.js --config my-models.json ├── AGENTS.md 📋 Project configuration ├── opencode.json ⚙️ OpenCode config (permissions, plugins) ├── .opencode/ -│ ├── skills/ ⌨️ 72 skills +│ ├── skills/ ⌨️ 73 skills │ ├── agents/ 🤖 49 agent definitions │ ├── plugins/ │ │ ├── ccgs-hooks.ts 🔗 TS plugin (all 12 hooks) diff --git a/UPGRADING.md b/UPGRADING.md index c0ffb54..8d9d76f 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -39,6 +39,45 @@ git cherry-pick Commit SHAs for each version are listed in the version sections below. +## v0.3.0 — Godot MCP Integration + +**New skill count:** 72 → 73 (added `automated-smoke-test`) + +### What changed +- **New skill**: `automated-smoke-test` — runs the Godot project via godot-mcp, captures debug output, and checks for errors/crashes +- **setup-engine skill**: Added optional godot-mcp configuration section (section 7.3) +- **Agent files**: 5 agents (gameplay-programmer, godot-gdscript-specialist, godot-specialist, ui-programmer, qa-tester) updated with godot-mcp capability references +- **.gitattributes**: Added with `* text=auto eol=lf` for consistent line endings +- **Docs**: setup-requirements.md, quick-start.md, skills-reference.md updated + +### For your local clone +A new `.gitattributes` was added. Existing clones should re-normalize: +```shell +git rm --cached -r . && git reset --hard +``` + +### New dependency (optional) +The `automated-smoke-test` skill requires [godot-mcp](https://github.com/Coding-Solo/godot-mcp): +```shell +npx @coding-solo/godot-mcp +``` +Configure via `opencode.json` MCP settings (see `setup-engine` skill section 7.3). + +### Safe to overwrite +- `.opencode/skills/automated-smoke-test/SKILL.md` +- `.gitattributes` + +### Merge carefully +- `.opencode/skills/setup-engine/SKILL.md` — has new section 7.3 +- `.opencode/agents/gameplay-programmer.md` — MCP capability line added +- `.opencode/agents/godot-gdscript-specialist.md` — MCP capability line added +- `.opencode/agents/godot-specialist.md` — MCP capability line added +- `.opencode/agents/ui-programmer.md` — MCP capability line added +- `.opencode/agents/qa-tester.md` — MCP capability line added +- `.opencode/docs/setup-requirements.md` — godot-mcp dependency section added +- `.opencode/docs/quick-start.md` — setup step added, steps renumbered +- `.opencode/docs/skills-reference.md` — automated-smoke-test entry added + ### Strategy C — Manual file copy Best when: you didn't use git to set up the template (just downloaded a zip).