feat: Integrate godot-mcp for runtime feedback loop

[striderZA]

Summary

Integrates godot-mcp to provide a runtime feedback loop for agents, enabling automated testing, debugging, and verification of Godot projects.

Changes

• setup-engine skill: Added ## 7.5. Configure godot-mcp section with installation, configuration, and tool reference docs
• 5 agent files: Added godot-mcp capability references to gameplay-programmer, godot-gdscript-specialist, godot-specialist, ui-programmer, and qa-tester
• New automated-smoke-test skill: 7-phase workflow — verify MCP → launch project → capture debug → analyze errors → report pass/fail → cleanup
• Documentation: Updated setup-requirements.md, quick-start.md, and skills-reference.md

Closes #15

[github-actions]

PR Review: feat: Integrate godot-mcp for runtime feedback loop

Overall Assessment

The PR is well-structured and achieves its goal of integrating godot-mcp across the codebase. 270 additions across 10 files. The changes are clean and logically grouped. Below are specific findings.

---

Bugs

1. Missing process cleanup on error paths — automated-smoke-test/SKILL.md Phase 4 & 5

When an error occurs during Phase 4 (get_debug_output fails) or Phase 5 (analysis), the skill skips to Phase 6 (report) but Phase 7 (stop) is never reached. The Godot project continues running, leaking a background process.

Fix: Ensure stop_project is called in a finally-like pattern, or embed it into Phase 6's report logic.

---

Code Quality Issues

2. Inconsistent heading level in two agent files

• godot-gdscript-specialist.md:264 — ### MCP Integration uses ### but all peer sections (## Core Responsibilities, ## GDScript Coding Standards, etc.) use ##. This makes MCP Integration appear as a subsection of "Coordination" instead of a top-level section.
• godot-specialist.md:185 — Same issue: ### MCP Integration sits under ## When Consulted.

All other agent files (gameplay-programmer, qa-tester, ui-programmer) use ### consistently within their own sectioning, so only these two need fixing.

3. Undefined abort/cleanup for hung project — automated-smoke-test/SKILL.md:53

Phase 3 calls run_project but doesn't define what happens if the project hangs indefinitely (no timeout specified). The agent could block waiting for a response that never comes.

4. No version pin on MCP dependency — setup-engine/SKILL.md:411

npx @coding-solo/godot-mcp

No @version pin. Breaking changes in a future MCP release could silently break the smoke test workflow. Recommend pinning (e.g., @coding-solo/godot-mcp@1.0.0) or documenting where the version should be updated.

5. Minimal-output edge case not reflected in verdict — automated-smoke-test/SKILL.md:72-73

Phase 4 says to note "Output appears minimal" but the verdict formula in Phase 6 (line 141-150) doesn't account for this case. A running project with no output could indicate a silent failure but would still pass.

6. Section numbering inconsistency — setup-engine/SKILL.md:387

The heading reads ### 7.5. Configure godot-mcp, but within ## 7. Populate Engine Reference Docs there are only subsections 7.1 (within training data) and 7.2 (beyond training data). There is no 7.3 or 7.4. This should be ### 7.3. to avoid gaps.

7. DEBUG=true not explained — setup-engine/SKILL.md:426

"env": { "DEBUG": "true" }

No explanation of what DEBUG controls. An operator might leave this enabled in production, generating excessive logs. Recommend documenting what it does and when to disable it.

---

Suggestions

#	Suggestion	Location
8	Add polling loop for project readiness instead of blind sleep(X)	automated-smoke-test Phase 4
9	Add a max retry/step limit to the retry in Phase 2 (get_project_info) to prevent infinite loops	automated-smoke-test:41-43
10	Mention that the smoke test duration should scale with project complexity in the duration description	automated-smoke-test:49-51

opencode session  |  github run

[striderZA]

All review items addressed:

• chore(deps): bump actions/setup-node from 4 to 6 #1 (cleanup): Swapped Phase 6 (Report) and Phase 7 (Stop) so stop_project always runs before report. Errors in Phase 3 skip directly to Report (project never started).
• v0.1.2 #3 (hung project): Added 30-second response deadline for run_project.
• Fix: Replace .claude/ path references with .opencode/ in skills and docs #5 (minimal output): Added SILENT-FAIL verdict for zero/near-zero output.
• Polish: Update agent tool references from Write/Edit to write and edit #8 (polling): Replaced blind sleep with 2s polling loop.
• Fix: Replace AskUserQuestion with question tool in skill files #9 (max retry): Phase 2 retry loop capped at 3 attempts.
• Fix: Replace .claude/ path references with .opencode/ in skills and docs #10 (duration): Added note that duration should scale with project complexity.
• chore(deps): bump actions/stale from 9 to 10 #2 (headings): Fixed heading level in godot-gdscript-specialist.md and godot-specialist.md.
• Fix: Replace AskUserQuestion with question tool in skill files #4 (version pin): Added pin to @latest and comment advising production pin.
• Fix: Replace Claude model names with OpenCode model IDs in skill frontmatter #6 (numbering): Corrected 7.5→7.3.
• Fix: Replace WebSearch with webfetch in brainstorm skill #7 (DEBUG): Added explanation of what DEBUG=true controls.

[github-actions]

PR Review: feat: Integrate godot-mcp for runtime feedback loop

Overall

Well-structured PR — 310 additions, logically grouped, clear purpose. The author addressed all 10 items from the initial review. However, one critical issue remains from the fix process itself.

---

🚨 Critical: Unresolved merge conflict — automated-smoke-test/SKILL.md:75-82

<<<<<<< HEAD
If `get_debug_output` returns an error:
- Report: "Could not capture debug output: [error message]"
...
=======
Do not use a fixed sleep. Instead, poll `get_debug_output` in a loop:
>>>>>>> fix/smoke-quality

Git conflict markers were committed. The <<<<<<<, =======, >>>>>>> lines need to be removed. The polling loop approach (lines 84-98) is the correct post-fix version. The HEAD content and conflict lines should be deleted entirely, keeping just the polling intro sentence from the fix/smoke-quality side:

Do not use a fixed sleep. Instead, poll get_debug_output in a loop:

followed by items 1-4.

🟡 Minor: Phase 4 error → Phase 6 skip is ambiguous

Line 95 says Skip to Phase 6 but doesn't explicitly say to continue to Phase 7 (Report). The original HEAD text (in the unresolved conflict) had "Skip to Phase 6 (stop project), then continue to Phase 7 for the report" which is clearer. Recommend updating line 95 to:

Verdict: FAIL
Skip to Phase 6 (stop project), then continue to Phase 7 for the report.

✅ Fixed items verified

#	Issue	Status
1	Process cleanup on error	✅ Phase 6 (stop) is now before Phase 7 (report)
2	Inconsistent heading levels	✅ Both agents use ## MCP Integration
3	Hung project timeout	✅ 30-second deadline on run_project
4	Version pin	✅ @latest with comment advising production pin
5	SILENT-FAIL verdict	✅ Added to report template
6	Section numbering 7.5→7.3	✅ Corrected
7	DEBUG=true documented	✅ Note added explaining what it controls
8	Polling instead of sleep	✅ 2s polling loop implemented (pending conflict cleanup)
9	Max retry on Phase 2	✅ Capped at 3 attempts
10	Duration scaling	✅ Added note about project complexity

One more suggestion

• gameplay-programmer.md:134 and qa-tester.md:245 use ### MCP Integration while godot-specialist.md:185 and godot-gdscript-specialist.md:264 use ## MCP Integration. These agent files have different sectioning hierarchies — gameplay-programmer uses ### for most sections (### Key Responsibilities, ### Engine Version Safety, etc.) while godot-specialist uses ## for its top-level sections. So the inconsistency is within each agent's own structure, not cross-agent. No fix needed — this is correct as-is.

opencode session  |  github run

[github-actions]

PR Review: feat: Integrate godot-mcp for runtime feedback loop

Overall

The merge conflict from the second review has been resolved. 308 additions across 10 files, well-structured. Most prior review items were addressed. I found two remaining issues:

---

🐛 Potential Bug

Line 58 (automated-smoke-test/SKILL.md): Ambiguous skip-on-hang

Skip to Phase 6 (do not attempt stop)

Phase 6 is stop_project. This reads as "go to the stop phase but don't stop." If the intent is to skip stopping (because a hung project's stop_project might also hang), then the target should be Phase 7 (Report), same as line 63's pattern. If the intent is to go to Phase 6 and actually try stop_project despite the hang, the parenthetical should be removed.

Compare the consistent pattern on line 63:

Skip to Phase 7 (Report) — project was never launched, no stop needed

---

🟡 Ambiguity

Line 92-93 (automated-smoke-test/SKILL.md): Missing "then continue to Phase 7"

- After 3 consecutive failures: "Debug output capture failed after 3
  consecutive poll errors."
- Verdict: **FAIL**
- Skip to Phase 6

Every other "Skip to Phase 6" instruction on lines 78 adds "then continue to Phase 7 for the report." Without that continuation, an agent executing this literally would stop at Phase 6 and never generate the report. Missing output from a skipped report.

---

✅ All Prior Issues Verified Resolved

#	Issue	Status
1	Process cleanup on error	✅ Phase 6 before Phase 7
2	Heading inconsistency (gdscript/godot specialist)	✅ Both use ## MCP Integration now
3	Hung project timeout	✅ 30s deadline added
4	Version pin	✅ @latest + comment about production pin
5	SILENT-FAIL verdict	✅ Added
6	Section numbering 7.5→7.3	✅ Fixed
7	DEBUG=true documented	✅ Note added
8	Polling instead of sleep	✅ 2s polling loop
9	Max retry on Phase 2	✅ 3 attempts
10	Duration scaling note	✅ Added
—	Merge conflict markers	✅ Resolved, no conflict artifacts remain

Other files (clean)

• 5 agent files — ##/### heading levels are internally consistent within each file.
• setup-engine/SKILL.md — Section 7.3 well-documented with tool list, install instructions, config example, and DEBUG explanation.
• setup-requirements.md, quick-start.md, skills-reference.md — Appropriate additions, no issues.

---

Verdict: APPROVED with two minor findings (lines 58 and 92-93)

opencode session  |  github run