From ebe3f711b49b8e0ce775e4c8ff7bd6bf6a2bdf21 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 07:35:50 +0200 Subject: [PATCH 01/11] feat: Integrate godot-mcp for runtime feedback loop (#16) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Integrates [godot-mcp](https://github.com/Coding-Solo/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 --------- Co-authored-by: github-actions[bot] Co-authored-by: striderZA --- .opencode/agents/gameplay-programmer.md | 4 + .opencode/agents/godot-gdscript-specialist.md | 4 + .opencode/agents/godot-specialist.md | 4 + .opencode/agents/qa-tester.md | 4 + .opencode/agents/ui-programmer.md | 4 + .opencode/docs/quick-start.md | 22 +- .opencode/docs/setup-requirements.md | 20 ++ .opencode/docs/skills-reference.md | 1 + .../skills/automated-smoke-test/SKILL.md | 196 ++++++++++++++++++ .opencode/skills/setup-engine/SKILL.md | 56 +++++ 10 files changed, 308 insertions(+), 7 deletions(-) create mode 100644 .opencode/skills/automated-smoke-test/SKILL.md 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 From adba83cb93753a36fb31af492b102999586437b2 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 07:39:11 +0200 Subject: [PATCH 02/11] docs: update README and UPGRADING.md for v0.3.0 --- README.md | 10 +++++----- UPGRADING.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 5 deletions(-) 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..90eb6e7 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -39,6 +39,47 @@ 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). From ada255dcbc67a478ac26d03183b45a5467e9463a Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 07:55:05 +0200 Subject: [PATCH 03/11] fix: address PR review comments on v0.3.0 --- .opencode/agents/qa-tester.md | 2 +- .opencode/docs/skills-reference.md | 2 +- .opencode/skills/automated-smoke-test/SKILL.md | 5 +++-- UPGRADING.md | 2 -- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.opencode/agents/qa-tester.md b/.opencode/agents/qa-tester.md index ce76acb..9b17c8e 100644 --- a/.opencode/agents/qa-tester.md +++ b/.opencode/agents/qa-tester.md @@ -244,6 +244,6 @@ After a bug fix or hotfix, produce a **targeted** regression checklist, not a fu ### MCP Integration -- Use the godot-mcp server for automated smoke testing: run_project → capture debug output → check for errors +- 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/docs/skills-reference.md b/.opencode/docs/skills-reference.md index 7409482..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 diff --git a/.opencode/skills/automated-smoke-test/SKILL.md b/.opencode/skills/automated-smoke-test/SKILL.md index e36a2c3..3568967 100644 --- a/.opencode/skills/automated-smoke-test/SKILL.md +++ b/.opencode/skills/automated-smoke-test/SKILL.md @@ -55,7 +55,7 @@ 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) +- 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]" @@ -93,7 +93,8 @@ Do not use a fixed sleep. Instead, poll `get_debug_output` in a loop: - Skip to Phase 6 Once polling ends (duration elapsed or early-stop triggered), use the last -successful output for analysis. +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." diff --git a/UPGRADING.md b/UPGRADING.md index 90eb6e7..8d9d76f 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -78,8 +78,6 @@ Configure via `opencode.json` MCP settings (see `setup-engine` skill section 7.3 - `.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). From c3a517d84f02edc77a623b9cfc5cd4c40e24f885 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 10:13:51 +0200 Subject: [PATCH 04/11] feat: add /init-template skill for first-time repo setup (#23) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Adds `/init-template` skill for first-time repo setup, transforming the cloned OCGS template into a clean, ready-to-use game project. ### Changes - **New `/init-template` skill**: 7-phase interactive workflow — gather project identity → replace README → update AGENTS.md → update opencode.json → remove internal files → optional git reset → completion summary - **Updated docs**: quick-start.md (step 2), skills-reference.md (Onboarding table), setup-requirements.md (callout) Closes #22 --- .opencode/docs/quick-start.md | 21 +++-- .opencode/docs/setup-requirements.md | 2 + .opencode/docs/skills-reference.md | 1 + .opencode/skills/init-template/SKILL.md | 120 ++++++++++++++++++++++++ 4 files changed, 134 insertions(+), 10 deletions(-) create mode 100644 .opencode/skills/init-template/SKILL.md diff --git a/.opencode/docs/quick-start.md b/.opencode/docs/quick-start.md index 05381ea..5a33c5e 100644 --- a/.opencode/docs/quick-start.md +++ b/.opencode/docs/quick-start.md @@ -75,6 +75,7 @@ Ask yourself: "What department would handle this in a real studio?" | Command | What it does | |---------|-------------| +| `/init-template` | First-time repo setup — customizes the cloned template with your game identity, engine, and team preferences | | `/start` | First-time onboarding — asks where you are, guides you to the right workflow | | `/help` | Context-aware "what do I do next?" — reads your current phase and artifacts | | `/project-stage-detect` | Analyze project state, detect stage, identify gaps | @@ -210,27 +211,28 @@ If you already know what you need, jump directly to the relevant path: what excites you, what you've played, your constraints - Generates 3 concepts, helps you pick one, defines core loop and pillars - Produces a game concept document and recommends an engine -2. **Set up the engine** — Run `/setup-engine` (uses the brainstorm recommendation) +2. **Initialize your project** — Run `/init-template` to customize the template with your game name, engine, and clean out example files. +3. **Set up the engine** — Run `/setup-engine` (uses the brainstorm recommendation) - Configures CLAUDE.md, detects knowledge gaps, populates reference docs - Creates `.opencode/docs/technical-preferences.md` with naming conventions, 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. **Enhance with godot-mcp (Godot only)** — Install the optional MCP server +4. **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`) +5. **Validate the concept** — Run `/design-review design/gdd/game-concept.md` +6. **Decompose into systems** — Run `/map-systems` to map all systems and dependencies +7. **Design each system** — Run `/design-system [system-name]` (or `/map-systems next`) to write GDDs in dependency order -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 +8. **Test the core loop** — Run `/prototype [core-mechanic]` +9. **Playtest it** — Run `/playtest-report` to validate the hypothesis +10. **Plan the first sprint** — Run `/sprint-plan new` +11. Start building ### Path B: "I know what I want to build" @@ -290,4 +292,3 @@ AGENTS.md -- Master config (read this first) settings-local-template.md -- Personal settings.local.json guide templates/ -- 37 document templates ``` - diff --git a/.opencode/docs/setup-requirements.md b/.opencode/docs/setup-requirements.md index af26058..ef379a6 100644 --- a/.opencode/docs/setup-requirements.md +++ b/.opencode/docs/setup-requirements.md @@ -4,6 +4,8 @@ This template requires a few tools to be installed for full functionality. All hooks fail gracefully if tools are missing — nothing will break, but you'll lose validation features. +> **New projects:** After cloning this template, run `/init-template` before anything else. It customizes the template with your game name, engine choice, and team preferences, and cleans out example files. + ## Required | Tool | Purpose | Install | diff --git a/.opencode/docs/skills-reference.md b/.opencode/docs/skills-reference.md index 8b54526..8d8bf99 100644 --- a/.opencode/docs/skills-reference.md +++ b/.opencode/docs/skills-reference.md @@ -6,6 +6,7 @@ | Command | Purpose | |---------|---------| +| `/init-template` | First-time repo setup. Customizes the cloned template with your game identity, engine, and team preferences. | | `/start` | First-time onboarding — asks where you are, then guides you to the right workflow | | `/help` | Context-aware "what do I do next?" — reads current stage and surfaces the required next step | | `/project-stage-detect` | Full project audit — detect phase, identify existence gaps, recommend next steps | diff --git a/.opencode/skills/init-template/SKILL.md b/.opencode/skills/init-template/SKILL.md new file mode 100644 index 0000000..49f0d20 --- /dev/null +++ b/.opencode/skills/init-template/SKILL.md @@ -0,0 +1,120 @@ +--- +name: init-template +description: "First-time repo setup for new projects. Transforms the cloned OCGS template into a clean, ready-to-use game project with your own identity." +argument-hint: "[--reset-git] [--name \"My Game\"] [--engine godot|unity|unreal]" +user-invocable: true +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, question, Task +--- + +When this skill is invoked: + +## Phase 1: Parse Arguments + +Check if CLI arguments were passed (from `argument-hint`): + +- `--name "My Game"` → sets game name (skips the name question below) +- `--engine godot|unity|unreal` → sets engine (skips engine question) +- `--reset-git` → automatically offers git reset (skips the prompt) + +If `--name` and `--engine` are both provided, skip the interactive prompt entirely and proceed to Phase 2 using the provided values. + +Otherwise, use `question` to gather missing details: + +### Tab 1: Project Identity +- **What is your game's name?** (e.g., "My Game") +- **What is your game's one-line description?** (e.g., "A 2D platformer about a cat in space") + +### Tab 2: Engine & Genre +- **Which engine are you using?** (godot / unity / unreal) +- **What genre best describes your game?** (e.g., platformer, RPG, puzzle, FPS, strategy) + +### Tab 3: Team +- **Team size** (solo / small 2-5 / medium 6-15 / large 16+) +- **Preferred model tier** (default / workhorse / lightweight) — refer to the README's Model Mapping section for options + +## Phase 2: Replace README.md + +Write a fresh README.md to the project root. Use a template structure like: + +```markdown +# [Game Name] + +> [One-line description] + +Built with [Engine] using [OpenCode Game Studios](https://github.com/striderZA/OpenCodeGameStudios). + +## Quick Start + +```bash +opencode +``` + +Type `/start` for onboarding, or browse all skills with `/`. + +## Project Structure + +``` +/ +├── src/ # Game source code +├── assets/ # Game assets (art, audio, vfx) +├── design/ # Game design documents +├── docs/ # Technical documentation +└── production/ # Sprint plans, session logs +``` + +## License + +[Choose a license] +``` + +Replace `[Game Name]`, `[One-line description]`, and `[Engine]` with the user's answers from Phase 1. + +## Phase 3: Update AGENTS.md + +Read AGENTS.md and update: +- Replace the Model Mapping section at the top with the user's engine and model preference +- Set the engine to the user's choice +- Remove or update any project-specific settings + +## Phase 4: Update opencode.json + +Read opencode.json and clean it up: +- Remove any internal-only plugin paths +- Set project name appropriately +- Keep the ccgs-hooks.ts plugin reference only if the file actually exists: `if [ -f .opencode/plugins/ccgs-hooks.ts ]; then ...` + +## Phase 5: Remove Internal Files + +Remove these files/directories with existence guards (`rm -f` or `[ -f ] && rm`): + +- `rm -f UPGRADING.md CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md` +- Clear `design/` directory contents: `rm -rf design/*` but keep the directory +- Clear `src/` contents: `rm -rf src/*` then `touch src/.gitkeep` +- Clear `production/` contents: `rm -rf production/*` + +## Phase 6: Optional Git Reset + +If the user selected `--reset-git` or agrees when prompted: +- Offer to reset git history to a single commit +- `git checkout --orphan fresh-root` +- `git add -A` +- `git commit -m "Initial commit: scaffolded from OpenCode Game Studios template"` +- Delete all old tags (optional) +- Force push if needed (warn about consequences) + +## Phase 7: Summary + +Print a completion summary: + +``` +✅ Template initialized + + Project: [Game Name] + Engine: [Engine] + Team: [Size] + + What's next: + - Run /setup-engine [engine] to configure your engine docs + - Run /brainstorm to start designing your game concept + - Run /start for guided onboarding +``` From 1c0402a7b4644b6a98a3885ab772ea8c71df6c63 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 19:53:44 +0200 Subject: [PATCH 05/11] Chore: Clean deprecated Claude Code references from .opencode/docs/ (#25) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #24 ### Deleted - CLAUDE-local-template.md (Claude Code specific, no OpenCode equivalent) - settings-local-template.md (Claude Code permission modes) ### Rewritten for OpenCode - setup-requirements.md — OpenCode CLI, Node.js dep, editor setup - hooks-reference.md — TS plugin table replacing bash hooks - context-management.md — OpenCode session terminology ### Fixed references - quick-start.md: Claude Code → OpenCode - coordination-rules.md: Claude Code session → OpenCode session - director-gates.md: AskUserQuestion → question - templates/ (3 files): AskUserQuestion → question, Write/Edit → write and edit --- .opencode/docs/CLAUDE-local-template.md | 37 ----------- .opencode/docs/context-management.md | 2 +- .opencode/docs/coordination-rules.md | 22 ++----- .opencode/docs/director-gates.md | 2 +- .opencode/docs/hooks-reference.md | 53 ++++++++++------ .opencode/docs/quick-start.md | 2 +- .opencode/docs/settings-local-template.md | 63 ------------------- .opencode/docs/setup-requirements.md | 52 +++++++-------- .../design-agent-protocol.md | 18 +++--- .../implementation-agent-protocol.md | 10 +-- .../leadership-agent-protocol.md | 10 +-- 11 files changed, 85 insertions(+), 186 deletions(-) delete mode 100644 .opencode/docs/CLAUDE-local-template.md delete mode 100644 .opencode/docs/settings-local-template.md diff --git a/.opencode/docs/CLAUDE-local-template.md b/.opencode/docs/CLAUDE-local-template.md deleted file mode 100644 index 5c858f3..0000000 --- a/.opencode/docs/CLAUDE-local-template.md +++ /dev/null @@ -1,37 +0,0 @@ -# CLAUDE.local.md Template - -Copy this file to the project root as `CLAUDE.local.md` for personal overrides. -This file is gitignored and will not be committed. - -```markdown -# Personal Preferences - -## Model Preferences -- Prefer Opus for complex design tasks -- Use Haiku for quick lookups and simple edits - -## Workflow Preferences -- Always run tests after code changes -- Compact context proactively at 60% usage -- Use /clear between unrelated tasks - -## Local Environment -- Python command: python (or py / python3) -- Shell: Git Bash on Windows -- IDE: VS Code with Claude Code extension - -## Communication Style -- Keep responses concise -- Show file paths in all code references -- Explain architectural decisions briefly - -## Personal Shortcuts -- When I say "review", run /code-review on the last changed files -- When I say "status", show git status + sprint progress -``` - -## Setup - -1. Copy this template to your project root: `cp .opencode/docs/CLAUDE-local-template.md CLAUDE.local.md` -2. Edit to match your preferences -3. Verify `CLAUDE.local.md` is in `.gitignore` (Claude Code reads it from the project root) diff --git a/.opencode/docs/context-management.md b/.opencode/docs/context-management.md index 2734f3b..c23998a 100644 --- a/.opencode/docs/context-management.md +++ b/.opencode/docs/context-management.md @@ -1,6 +1,6 @@ # Context Management -Context is the most critical resource in a Claude Code session. Manage it actively. +Context is the most critical resource in an OpenCode session. Manage it actively. ## File-Backed State (Primary Strategy) diff --git a/.opencode/docs/coordination-rules.md b/.opencode/docs/coordination-rules.md index e9f2a41..9525da1 100644 --- a/.opencode/docs/coordination-rules.md +++ b/.opencode/docs/coordination-rules.md @@ -36,7 +36,7 @@ high-stakes output; otherwise leave unset (Sonnet). This project uses two distinct multi-agent patterns: ### Subagents (current, always active) -Spawned via `Task` within a single Claude Code session. Used by all `team-*` skills +Spawned via `Task` within a single OpenCode session. Used by all `team-*` skills and orchestration skills. Subagents share the session's permission context, run sequentially or in parallel within the session, and return results to the parent. @@ -45,23 +45,13 @@ needs the other's output to begin), spawn both Task calls simultaneously rather than waiting. Example: `/review-all-gdds` Phase 1 (consistency) and Phase 2 (design theory) are independent — spawn both at the same time. -### Agent Teams (experimental — opt-in) -Multiple independent Claude Code *sessions* running simultaneously, coordinated +### Agent Teams (future) +Multiple independent OpenCode *sessions* running simultaneously, coordinated via a shared task list. Each session has its own context window and token budget. -Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable. +OpenCode does not currently support this pattern. -**Use agent teams when**: -- Work spans multiple subsystems that will not touch the same files -- Each workstream would take >30 minutes and benefits from true parallelism -- A senior agent (technical-director, producer) needs to coordinate 3+ specialist - sessions working on different epics simultaneously - -**Do not use agent teams when**: -- One session's output is required as input for another (use sequential subagents) -- The task fits in a single session's context (use subagents instead) -- Cost is a concern — each team member burns tokens independently - -**Current status**: Not yet used in this project. Document usage here when first adopted. +**Use subagents instead** — the `Task` tool spawns agents within a single session +and supports both sequential and parallel execution. See the Subagents section above. ## Parallel Task Protocol diff --git a/.opencode/docs/director-gates.md b/.opencode/docs/director-gates.md index 21e04eb..f643a12 100644 --- a/.opencode/docs/director-gates.md +++ b/.opencode/docs/director-gates.md @@ -101,7 +101,7 @@ All gates return one of three verdicts. Skills must handle all three: | Verdict | Meaning | Default action | |---------|---------|----------------| | **APPROVE / READY** | No issues. Proceed. | Continue the workflow | -| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via `AskUserQuestion` — options: `Revise flagged items` / `Accept and proceed` / `Discuss further` | +| **CONCERNS [list]** | Issues present but not blocking. | Surface to user via `question` — options: `Revise flagged items` / `Accept and proceed` / `Discuss further` | | **REJECT / NOT READY [blockers]** | Blocking issues. Do not proceed. | Surface blockers to user. Do not write files or advance stage until resolved. | **Escalation rule**: When multiple directors are spawned in parallel, apply the diff --git a/.opencode/docs/hooks-reference.md b/.opencode/docs/hooks-reference.md index fd169d5..05bfc7a 100644 --- a/.opencode/docs/hooks-reference.md +++ b/.opencode/docs/hooks-reference.md @@ -1,21 +1,36 @@ # Active Hooks -Hooks are configured in `.opencode/settings.json` and fire automatically: - -| Hook | Event | Trigger | Action | -| ---- | ----- | ------- | ------ | -| `validate-commit.sh` | PreToolUse (Bash) | `git commit` commands | Validates design doc sections, JSON data files, hardcoded values, TODO format | -| `validate-push.sh` | PreToolUse (Bash) | `git push` commands | Warns on pushes to protected branches (develop/main) | -| `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks naming conventions and JSON validity for files in `assets/` | -| `session-start.sh` | SessionStart | Session begins | Loads sprint context, milestone, git activity; detects and previews active session state file for recovery | -| `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect | -| `pre-compact.sh` | PreCompact | Context compression | Dumps session state (active.md, modified files, WIP design docs) into conversation before compaction so it survives summarization | -| `post-compact.sh` | PostCompact | After compaction | Reminds Claude to restore session state from `active.md` checkpoint | -| `notify.sh` | Notification | Notification event | Shows Windows toast notification via PowerShell | -| `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log | -| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail start — logs subagent invocation with timestamp | -| `log-agent-stop.sh` | SubagentStop | Agent stops | Audit trail stop — completes subagent record | -| `validate-skill-change.sh` | PostToolUse (Write/Edit) | Skill file changes | Advises running `/skill-test` after any `.opencode/skills/` file is written or edited | - -Hook reference documentation: `.opencode/docs/hooks-reference/` -Hook input schema documentation: `.opencode/docs/hooks-reference/hook-input-schemas.md` +All 12 bash hooks from CCGS are ported to a single TypeScript plugin +at **`.opencode/plugins/ccgs-hooks.ts`**. Hooks fire automatically +via OpenCode's plugin event system: + +| # | Original Hook | 🔌 OpenCode Event | 🧪 Tests | +|---|-----------|-------------------|:--------:| +| 1 | `session-start.sh` | `session.created` | **18** | +| 2 | `session-stop.sh` | `session.idle` / `server.instance.disposed` | **10** | +| 3 | `detect-gaps.sh` | `session.created` | **15** | +| 4 | `log-agent.sh` | `tool.execute.before` (task) | **5** | +| 5 | `log-agent-stop.sh` | `tool.execute.after` (task) | **4** | +| 6 | `validate-assets.sh` | `tool.execute.after` | **16** | +| 7 | `validate-commit.sh` | `tool.execute.before` (git commit) | **17** | +| 8 | `validate-push.sh` | `tool.execute.before` (git push) | **13** | +| 9 | `validate-skill-change.sh` | `tool.execute.after` | **12** | +| 10 | `pre-compact.sh` | `experimental.session.compacting` | **14** | +| 11 | `post-compact.sh` | `experimental.compaction.autocontinue` | **5** | +| 12 | `notify.sh` | Utility (`showNotification`) | — | + +## Running Tests + +Run a test suite against the hooks plugin: + +```bash +node .opencode/plugins/tests/test-.mjs +``` + +For example, to run the commit validation tests: + +```bash +node .opencode/plugins/tests/test-validate-commit.mjs +``` + +For a complete list of test suites, see the [README](/README.md#-hooks-plugin) Hooks Plugin section. diff --git a/.opencode/docs/quick-start.md b/.opencode/docs/quick-start.md index 5a33c5e..0b4dcdd 100644 --- a/.opencode/docs/quick-start.md +++ b/.opencode/docs/quick-start.md @@ -2,7 +2,7 @@ ## What Is This? -This is a complete Claude Code agent architecture for game development. It +This is a complete OpenCode agent architecture for game development. It organizes 48 specialized AI agents into a studio hierarchy that mirrors real game development teams, with defined responsibilities, delegation rules, and coordination protocols. It includes engine-specialist agents diff --git a/.opencode/docs/settings-local-template.md b/.opencode/docs/settings-local-template.md deleted file mode 100644 index 05f9f89..0000000 --- a/.opencode/docs/settings-local-template.md +++ /dev/null @@ -1,63 +0,0 @@ -# settings.local.json Template - -Create `.opencode/settings.local.json` for personal overrides that should NOT -be committed to version control. Add it to `.gitignore`. - -## Example settings.local.json - -```json -{ - "permissions": { - "allow": [ - "Bash(git *)", - "Bash(npm *)", - "Read", - "Glob", - "Grep" - ], - "deny": [ - "Bash(rm -rf *)", - "Bash(git push --force *)" - ] - } -} -``` - -## Permission Modes - -Claude Code supports different permission modes. Recommended for game dev: - -### During Development (Default) -Use **normal mode** — Claude asks before running most commands. This is safest -for production code. - -### During Prototyping -Use **auto-accept mode** with limited scope — faster iteration on throwaway code. -Only use this when working in `prototypes/` directory. - -### During Code Review -Use **read-only** permissions — Claude can read and search but not modify files. - -## Customizing Hooks Locally - -You can add personal hooks in `settings.local.json` that extend (not override) -the project hooks. For example, adding a notification when builds complete: - -```json -{ - "hooks": { - "Stop": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "bash -c 'echo Session ended at $(date)'", - "timeout": 5 - } - ] - } - ] - } -} -``` diff --git a/.opencode/docs/setup-requirements.md b/.opencode/docs/setup-requirements.md index ef379a6..60499af 100644 --- a/.opencode/docs/setup-requirements.md +++ b/.opencode/docs/setup-requirements.md @@ -4,56 +4,52 @@ This template requires a few tools to be installed for full functionality. All hooks fail gracefully if tools are missing — nothing will break, but you'll lose validation features. -> **New projects:** After cloning this template, run `/init-template` before anything else. It customizes the template with your game name, engine choice, and team preferences, and cleans out example files. +> **New projects:** After cloning this template, run `/start` before anything else. It customizes the template with your game name, engine choice, and team preferences, and cleans out example files. ## Required | Tool | Purpose | Install | | ---- | ---- | ---- | | **Git** | Version control, branch management | [git-scm.com](https://git-scm.com/) | -| **Claude Code** | AI agent CLI | `npm install -g @anthropic-ai/claude-code` | +| **OpenCode** | AI agent CLI | `npm install -g opencode` | ## Recommended | Tool | Used By | Purpose | Install | | ---- | ---- | ---- | ---- | -| **jq** | Hooks (4 of 8) | JSON parsing in commit/push/asset/agent hooks | See below | -| **Python 3** | Hooks (2 of 8) | JSON validation for data files | [python.org](https://www.python.org/) | -| **Bash** | All hooks | Shell script execution | Included with Git for Windows | +| **Node.js 18+** | Hooks plugin | Runtime for the CCGS TypeScript hooks plugin | [nodejs.org](https://nodejs.org/) | -### Installing jq +### Installing Node.js **Windows** (any of these): ``` -winget install jqlang.jq -choco install jq -scoop install jq +winget install OpenJS.NodeJS.LTS +choco install nodejs-lts +scoop install nodejs ``` **macOS**: ``` -brew install jq +brew install node ``` **Linux**: ``` -sudo apt install jq # Debian/Ubuntu -sudo dnf install jq # Fedora -sudo pacman -S jq # Arch +sudo apt install nodejs npm # Debian/Ubuntu +sudo dnf install nodejs # Fedora +sudo pacman -S nodejs npm # Arch ``` ## Platform Notes ### Windows -- Git for Windows includes **Git Bash**, which provides the `bash` command - used by all hooks in `settings.json` +- Git for Windows includes **Git Bash**, which provides `bash` - Ensure Git Bash is on your PATH (default if installed via the Git installer) -- Hooks use `bash .opencode/hooks/[name].sh` — this works on Windows because - Claude Code invokes commands through a shell that can find `bash.exe` +- OpenCode runs natively in PowerShell, CMD, Git Bash, and Windows Terminal ### macOS / Linux -- Bash is available natively -- Install `jq` via your package manager for full hook support +- Node.js and npm are available via your package manager +- OpenCode works in any standard terminal ## Verifying Your Setup @@ -61,25 +57,23 @@ Run these commands to check prerequisites: ```bash git --version # Should show git version -bash --version # Should show bash version -jq --version # Should show jq version (optional) -python3 --version # Should show python version (optional) +node --version # Should show Node.js 18+ +npx opencode --version # Should show OpenCode version ``` ## What Happens Without Optional Tools | Missing Tool | Effect | | ---- | ---- | -| **jq** | Commit validation, push protection, asset validation, and agent audit hooks silently skip their checks. Commits and pushes still work. | -| **Python 3** | JSON data file validation in commit and asset hooks is skipped. Invalid JSON can be committed without warning. | -| **Both** | All hooks still execute without error (exit 0) but provide no validation. You're flying without safety nets. | +| **Node.js** | The hooks plugin (`ccgs-hooks.ts`) cannot execute. All hook events silently pass through. Commits, pushes, and all other operations still work. | ## Recommended IDE -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 +OpenCode works with any editor: +- **VS Code** with the OpenCode CLI +- **Cursor** (OpenCode compatible) +- **Terminal** — `opencode` CLI directly in any shell +- **JetBrains IDEs** — via the terminal ## Optional Engine Dependencies diff --git a/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md b/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md index c9d7460..6ac2d4c 100644 --- a/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md +++ b/.opencode/docs/templates/collaborative-protocols/design-agent-protocol.md @@ -16,14 +16,14 @@ Before proposing any design: - What are the constraints (scope, complexity, existing systems)? - Any reference games or mechanics the user loves/hates? - How does this connect to the game's pillars? - - *Use `AskUserQuestion` to batch up to 4 constrained questions at once* + - *Use `question` to batch up to 4 constrained questions at once* 2. **Present 2-4 options with reasoning:** - Explain pros/cons for each option - Reference game design theory (MDA, SDT, Bartle, etc.) - Align each option with the user's stated goals - Make a recommendation, but explicitly defer the final decision to the user - - *After the full explanation, use `AskUserQuestion` to capture the decision* + - *After the full explanation, use `question` to capture the decision* 3. **Draft based on user's choice:** - Create sections iteratively (show one section, get feedback, refine) @@ -33,7 +33,7 @@ Before proposing any design: 4. **Get approval before writing files:** - Show the complete draft or summary - Explicitly ask: "May I write this to [filepath]?" - - Wait for "yes" before using Write/Edit tools + - Wait for "yes" before using write and edit tools - If user says "no" or "change X", iterate and return to step 3 #### Example Interaction Pattern @@ -107,27 +107,27 @@ You: [uses Write tool] #### Structured Decision UI -Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of +Use the `question` tool to present decisions as a selectable UI instead of plain text. Follow the **Explain → Capture** pattern: 1. **Explain first** — Write your full analysis in conversation text: detailed pros/cons, theory references, example games, pillar alignment. This is where the expert reasoning lives — don't try to fit it into the tool. -2. **Capture the decision** — Call `AskUserQuestion` with concise option labels +2. **Capture the decision** — Call `question` with concise option labels and short descriptions. The user picks from the UI or types a custom answer. **When to use it:** - Every decision point where you present 2-4 options (step 2) - Initial clarifying questions that have constrained answers (step 1) -- Batch up to 4 independent questions in a single `AskUserQuestion` call +- Batch up to 4 independent questions in a single `question` call - Next-step choices ("Draft formulas section or refine rules first?") **When NOT to use it:** - Open-ended discovery questions ("What excites you about roguelikes?") - Single yes/no confirmations ("May I write to file?") - When running as a Task subagent (tool may not be available) — structure your - text output so the orchestrator can present options via AskUserQuestion + text output so the orchestrator can present options via question **Format guidelines:** - Labels: 1-5 words (e.g., "Hybrid Discovery", "Full Randomized") @@ -137,7 +137,7 @@ plain text. Follow the **Explain → Capture** pattern: **Example — multi-question batch for clarifying questions:** - AskUserQuestion with questions: + question with questions: 1. question: "Should crafting recipes be discovered or learned?" header: "Discovery" options: "Experimentation", "NPC/Book Learning", "Tiered Hybrid" @@ -147,7 +147,7 @@ plain text. Follow the **Explain → Capture** pattern: **Example — capturing a design decision (after full analysis in conversation):** - AskUserQuestion with questions: + question with questions: 1. question: "Which crafting approach fits your vision?" header: "Approach" options: diff --git a/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md b/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md index 3ea80e7..e3bebad 100644 --- a/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md +++ b/.opencode/docs/templates/collaborative-protocols/implementation-agent-protocol.md @@ -21,7 +21,7 @@ Before writing any code: - "Where should [data] live? (CharacterStats? Equipment class? Config file?)" - "The design doc doesn't specify [edge case]. What should happen when...?" - "This will require changes to [other system]. Should I coordinate with that first?" - - *Use `AskUserQuestion` to batch constrained architecture questions* + - *Use `question` to batch constrained architecture questions* 3. **Propose architecture before implementing:** - Show class structure, file organization, data flow @@ -38,7 +38,7 @@ Before writing any code: - Show the code or a detailed summary - Explicitly ask: "May I write this to [filepath(s)]?" - For multi-file changes, list all affected files - - Wait for "yes" before using Write/Edit tools + - Wait for "yes" before using write and edit tools 6. **Complete the story with `/story-done`:** - When implementation (and tests, if written) is complete, invoke `/story-done [story-file-path]` @@ -129,12 +129,12 @@ You: [creates tests/combat/test_damage_calculator.gd] #### Structured Decision UI -Use the `AskUserQuestion` tool for architecture decisions and next-step choices. +Use the `question` tool for architecture decisions and next-step choices. Follow the **Explain → Capture** pattern: 1. **Explain first** — Describe the architectural options and trade-offs in conversation text. -2. **Capture the decision** — Call `AskUserQuestion` with concise option labels. +2. **Capture the decision** — Call `question` with concise option labels. **When to use it:** - Architecture questions with constrained answers (step 2) @@ -148,7 +148,7 @@ Follow the **Explain → Capture** pattern: **Example — architecture questions (batch):** - AskUserQuestion with questions: + question with questions: 1. question: "Where should DamageCalculator live?" header: "Architecture" options: "Static Utility (Recommended)", "Autoload Singleton", "Scene Node" diff --git a/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md b/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md index 72e36c8..3b7b6e0 100644 --- a/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md +++ b/.opencode/docs/templates/collaborative-protocols/leadership-agent-protocol.md @@ -15,7 +15,7 @@ When the user asks you to make a decision or resolve a conflict: - Ask questions to understand all perspectives - Review relevant docs (pillars, constraints, prior decisions) - Identify what's truly at stake (often deeper than the surface question) - - *Use `AskUserQuestion` to batch up to 4 constrained questions at once* + - *Use `question` to batch up to 4 constrained questions at once* 2. **Frame the decision:** - State the core question clearly @@ -29,7 +29,7 @@ When the user asks you to make a decision or resolve a conflict: - Downstream consequences (technical, creative, schedule, scope) - Risks and mitigation strategies - Real-world examples (how other games handled similar decisions) - - *After the full analysis, use `AskUserQuestion` to capture the decision* + - *After the full analysis, use `question` to capture the decision* 4. **Make a clear recommendation:** - "I recommend Option [X] because..." @@ -146,13 +146,13 @@ You: [Creates ADR, updates docs, notifies relevant agents] #### Structured Decision UI -Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI. +Use the `question` tool to present strategic decisions as a selectable UI. Follow the **Explain → Capture** pattern: 1. **Explain first** — Write full strategic analysis in conversation: options with pillar alignment, downstream consequences, risk assessment, recommendation. -2. **Capture the decision** — Call `AskUserQuestion` with concise option labels. +2. **Capture the decision** — Call `question` with concise option labels. **When to use it:** - Every strategic decision point (options in step 3, context questions in step 1) @@ -171,7 +171,7 @@ Follow the **Explain → Capture** pattern: **Example — strategic decision (after full analysis in conversation):** - AskUserQuestion with questions: + question with questions: 1. question: "How should we handle crafting scope for Alpha?" header: "Scope" options: From c658f58effd12d23574b3716ff634a12862f4250 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 21:05:50 +0200 Subject: [PATCH 06/11] fix: address PR review - destructive rm, stale refs, vague instructions --- .opencode/docs/quick-start.md | 7 +++---- .opencode/docs/setup-requirements.md | 2 +- .opencode/skills/init-template/SKILL.md | 19 +++++++++++-------- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/.opencode/docs/quick-start.md b/.opencode/docs/quick-start.md index 0b4dcdd..56d3950 100644 --- a/.opencode/docs/quick-start.md +++ b/.opencode/docs/quick-start.md @@ -275,10 +275,10 @@ If you have design docs, prototypes, or code already: ``` AGENTS.md -- Master config (read this first) .opencode/ - config.json -- OpenCode settings and plugin configuration + (opencode.json at root) -- OpenCode settings and plugin configuration agents/ -- Agent definitions (YAML frontmatter) skills/ -- Skill definitions (YAML frontmatter) - hooks/ -- Hook scripts wired by config + plugins/ -- TypeScript hooks plugin (ccgs-hooks.ts) rules/ -- Path-specific rule files docs/ quick-start.md -- This file @@ -288,7 +288,6 @@ AGENTS.md -- Master config (read this first) context-management.md -- Context budgets and compaction instructions directory-structure.md -- Project directory layout workflow-catalog.yaml -- 7-phase pipeline definition (read by /help) - setup-requirements.md -- System prerequisites (Git Bash, jq, Python) - settings-local-template.md -- Personal settings.local.json guide + setup-requirements.md -- System prerequisites (Git, Node.js, OpenCode CLI) templates/ -- 37 document templates ``` diff --git a/.opencode/docs/setup-requirements.md b/.opencode/docs/setup-requirements.md index 60499af..ef3a3ee 100644 --- a/.opencode/docs/setup-requirements.md +++ b/.opencode/docs/setup-requirements.md @@ -4,7 +4,7 @@ This template requires a few tools to be installed for full functionality. All hooks fail gracefully if tools are missing — nothing will break, but you'll lose validation features. -> **New projects:** After cloning this template, run `/start` before anything else. It customizes the template with your game name, engine choice, and team preferences, and cleans out example files. +> **New projects:** After cloning this template, run `/init-template` before anything else. It customizes the template with your game name, engine choice, and team preferences, and cleans out example files. ## Required diff --git a/.opencode/skills/init-template/SKILL.md b/.opencode/skills/init-template/SKILL.md index 49f0d20..3b5e0ed 100644 --- a/.opencode/skills/init-template/SKILL.md +++ b/.opencode/skills/init-template/SKILL.md @@ -72,9 +72,10 @@ Replace `[Game Name]`, `[One-line description]`, and `[Engine]` with the user's ## Phase 3: Update AGENTS.md Read AGENTS.md and update: -- Replace the Model Mapping section at the top with the user's engine and model preference -- Set the engine to the user's choice +- Set the engine to the user's choice by changing the `## Technology Stack` section +- Update the model assignment: replace the model table with the user's preference (default/workhorse/lightweight), mapping to their engine's specialist agents - Remove or update any project-specific settings +- If AGENTS.md is missing or malformed, warn and skip this phase ## Phase 4: Update opencode.json @@ -82,15 +83,17 @@ Read opencode.json and clean it up: - Remove any internal-only plugin paths - Set project name appropriately - Keep the ccgs-hooks.ts plugin reference only if the file actually exists: `if [ -f .opencode/plugins/ccgs-hooks.ts ]; then ...` +- If opencode.json is missing or malformed, warn and skip this phase ## Phase 5: Remove Internal Files -Remove these files/directories with existence guards (`rm -f` or `[ -f ] && rm`): +For each file/directory below, check existence first before deleting. If the directory already has user-created content, warn and skip rather than destroying it: - `rm -f UPGRADING.md CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md` -- Clear `design/` directory contents: `rm -rf design/*` but keep the directory -- Clear `src/` contents: `rm -rf src/*` then `touch src/.gitkeep` -- Clear `production/` contents: `rm -rf production/*` +- Clear `design/` contents only if empty of user files: `if ls design/*.md >/dev/null 2>&1; then echo "WARNING: design/ has content, skipping"; else rm -rf design/*; fi` +- Clear `src/` contents only if empty of user files: `if ls src/*.gd src/*.cs src/*.cpp src/*.ts >/dev/null 2>&1; then echo "WARNING: src/ has code files, skipping"; else rm -rf src/* && touch src/.gitkeep; fi` +- Clear `production/` contents only if empty of user files: similar guard +- On any error (file locked, permission denied), warn and continue to next item ## Phase 6: Optional Git Reset @@ -99,8 +102,8 @@ If the user selected `--reset-git` or agrees when prompted: - `git checkout --orphan fresh-root` - `git add -A` - `git commit -m "Initial commit: scaffolded from OpenCode Game Studios template"` -- Delete all old tags (optional) -- Force push if needed (warn about consequences) +- Delete all old tags (optional) — warn: if tags were previously pushed to remote, deletion requires `git push origin --delete ` for each one +- Force push if needed (warn: this rewrites remote history for anyone who has cloned this repo) ## Phase 7: Summary From 7f94dac05b0f6647c5622e3792a45069d39ddb8f Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 22:25:28 +0200 Subject: [PATCH 07/11] fix: Complete hybrid workflow documentation gaps (#30) Closes #30 --- .opencode/docs/skills-reference.md | 1 + .opencode/skills/hybrid-prototype/SKILL.md | 148 +++++++++++++++++ docs/hybrid-workflow.md | 179 +++++++++++++++++++++ opencode.json | 7 + prototypes/.gitkeep | 0 5 files changed, 335 insertions(+) create mode 100644 .opencode/skills/hybrid-prototype/SKILL.md create mode 100644 docs/hybrid-workflow.md create mode 100644 prototypes/.gitkeep diff --git a/.opencode/docs/skills-reference.md b/.opencode/docs/skills-reference.md index 8d8bf99..2d3ab60 100644 --- a/.opencode/docs/skills-reference.md +++ b/.opencode/docs/skills-reference.md @@ -21,6 +21,7 @@ | `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order | | `/design-system` | Guided, section-by-section GDD authoring for a single game system | | `/quick-design` | Lightweight design spec for small changes — tuning, tweaks, minor additions | +| `/hybrid-prototype` | Fast-lane prototype for hybrid workflow — build, playtest, and decide in 2-3 days | | `/review-all-gdds` | Cross-GDD consistency and game design holism review across all design docs | | `/propagate-design-change` | When a GDD is revised, find affected ADRs and produce an impact report | diff --git a/.opencode/skills/hybrid-prototype/SKILL.md b/.opencode/skills/hybrid-prototype/SKILL.md new file mode 100644 index 0000000..53c5dd5 --- /dev/null +++ b/.opencode/skills/hybrid-prototype/SKILL.md @@ -0,0 +1,148 @@ +--- +name: hybrid-prototype +description: "Fast-lane prototype skill for the hybrid workflow. Builds a playable prototype in 2-3 days with minimal process overhead. Designed for discovery phase." +argument-hint: "[concept-description]" +user-invocable: true +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task +agent: prototyper +isolation: worktree +--- + +## Overview + +This skill implements the **Discovery Phase fast lane** from `docs/hybrid-workflow.md`. It is intentionally lightweight: no formal GDD, no architecture, no epic breakdown. Just build it, play it, decide. + +**Time budget**: 1-3 days. +**Agents involved**: `creative-director`, `game-designer`, `prototyper`, `godot-specialist` (or engine equivalent). + +--- + +## Phase 1: Concept & Question (5 minutes) + +Read the concept description from the argument. State the **one core question** this prototype must answer. If the concept is vague, ask the user to clarify before proceeding. + +Examples of good questions: +- "Does the combat feel responsive with 200ms input lag?" +- "Is resource scarcity actually fun, or just frustrating?" +- "Does the movement mechanic support the intended platforming challenges?" + +Bad question: "Is this game fun?" (Too broad. Narrow it down.) + +**Ask the user**: "The core question for this prototype is: [question]. Proceed?" + +--- + +## Phase 2: Plan (15 minutes) + +Define the minimum viable prototype in 3-5 bullet points: + +- What is the absolute minimum code to answer the question? +- What can be hardcoded / placeholder / skipped? +- What is the success criteria? (e.g., "Player can complete 3 jumps in a row without dying") + +**Present the plan to the user and ask for confirmation.** + +--- + +## Phase 3: Build (1-2 days) + +**Ask**: "May I create the prototype directory at `prototypes/[concept-name]/` and begin implementation?" + +If yes, create the directory. Every file must begin with: + +``` +// PROTOTYPE - NOT FOR PRODUCTION +// Question: [Core question being tested] +// Date: [Current date] +``` + +**Rules for prototype code**: +- Hardcode values freely +- Use placeholder assets (colored squares, simple shapes) +- Skip error handling +- Use the simplest approach that works +- Copy code rather than importing from production +- NEVER import from `src/` — prototypes are isolated + +**Run the prototype** as you build. Test continuously. Fix blockers, but don't polish. + +--- + +## Phase 4: Playtest (2-4 hours) + +Play the prototype yourself. Then ask the user to play it. Collect observations: + +- What worked? +- What felt bad? +- Did it answer the core question? +- Any surprising discoveries? + +**Document findings informally** — a bulleted list is fine. + +--- + +## Phase 5: Decide (30 minutes) + +Collaborate with `creative-director` and `game-designer` (via Task or conversation) to make a decision: + +| Verdict | Meaning | Next Step | +|---------|---------|-----------| +| **ITERATE** | Core is promising, but needs adjustment | Run `/hybrid-prototype [revised-concept]` | +| **PIVOT** | The concept doesn't work, but a related one might | Run `/brainstorm` or `/hybrid-prototype [new-direction]` | +| **PRODUCTIONIZE** | It's fun and proven — move to production | Begin GDD in `/design-system`, architecture in `/create-architecture` | +| **KILL** | It's not fun and no clear fix | Stop. The prototype report is the deliverable. | + +**Update `prototypes/[concept-name]/DECISION.md`** with: + +```markdown +# Prototype Decision: [Concept Name] + +## Question +[Core question] + +## Result +[What happened] + +## Verdict +[ITERATE / PIVOT / PRODUCTIONIZE / KILL] + +## Reasoning +[Why] + +## Next Steps +[What to do next] +``` + +**Ask**: "May I write the decision to `prototypes/[concept-name]/DECISION.md`?" + +--- + +## Phase 6: Done + +Output a summary to the user: the core question, the verdict, and the next step. + +If **PRODUCTIONIZE**: remind them to switch to the Production phase workflow (`/design-system`, `/create-architecture`, etc.) + +If **ITERATE / PIVOT / KILL**: no further action needed. + +--- + +## Constraints + +- Prototype code must NEVER import from production source files +- Production code must NEVER import from prototype directories +- If productionizing, rewrite from scratch — do not refactor prototype code +- Timebox strictly: if it's not working after 3 days, kill or pivot +- Keep the question narrow — one prototype, one question +- **Workflow isolation**: This skill explicitly bypasses `production/review-mode.txt`. If the session previously ran the full OCGS workflow, any stale review-mode state is ignored — the hybrid fast lane always runs without formal gates. + +## Differences from Full `/prototype` Skill + +| Aspect | `/prototype` (Full OCGS) | `/hybrid-prototype` (Fast Lane) | +|--------|--------------------------|----------------------------------| +| Review mode gates | Solo / Lean / Full | None (always fast) | +| Creative Director review | Formal gate spawn | Informal chat/Task | +| Report format | Formal `REPORT.md` | Lightweight `DECISION.md` | +| Agents involved | All tiers | 4 core roles only | +| Time to verdict | 1-3 days + review overhead | 1-3 days total | +| Next step on PROCEED | Formal GDD + ADR | Start GDD when ready | diff --git a/docs/hybrid-workflow.md b/docs/hybrid-workflow.md new file mode 100644 index 0000000..cd08497 --- /dev/null +++ b/docs/hybrid-workflow.md @@ -0,0 +1,179 @@ +# Hybrid Discovery-Production Workflow + +## Overview + +This document defines a pragmatic hybrid workflow that balances **creative agility** during pre-production with **production discipline** once the game's direction is proven. It is designed for indie teams (1–5 people) who need to iterate quickly to find the fun, but still want professional-grade coordination when building the real thing. + +**When to use this workflow**: Small teams, unknown designs, short timelines (weeks to a few months), prototypes that may be pivoted or killed. + +**When to use the full OCGS workflow**: Large teams (5–15+), known designs, long timelines (6+ months), funded projects with publisher requirements. + +--- + +## Two-Phase Model + +The project lifecycle is split into two modes with **different rules**: + +| Dimension | Discovery | Production | +|-----------|-----------|------------| +| **Goal** | Find the fun | Ship a polished game | +| **Process overhead** | Low | High (full OCGS) | +| **Time to playable** | 2–4 days | 2–4 weeks planning first | +| **GDDs** | Quick-design / bullet points | Formal GDDs | +| **Architecture** | None | ADRs required | +| **Code location** | `prototypes/` | `src/` | +| **Tests** | Manual playtest only | Unit + integration + QA | +| **Sprint planning** | Weekly goals (informal) | Formal sprint plan | +| **Agents** | 4 core roles | 10 core roles | + +--- + +## Phase 1: Discovery (Pre-Production) + +### Goal +Answer one question per prototype: *Is this mechanic/system/fun?* + +### Rules +- **No formal GDDs.** Use `/quick-design` for lightweight specs, or bullet points in a markdown file. +- **No architecture.** Build throwaway scenes in `prototypes/`. +- **Minimal agents.** Only `creative-director`, `game-designer`, `prototyper`, and `godot-specialist` (or engine equivalent). +- **Time-boxed.** 2–4 weeks maximum per prototype. +- **Kill cheaply.** If it's not fun, pivot or scrap. No sunk-cost fallacy. + +### What NOT to do in Discovery +- Architecture Decision Records (ADRs) +- Epic/story breakdowns +- QA plans +- Asset pipeline setup +- Unit tests (prototypes are throwaway) +- Formal sprint plans + +### Deliverable +A working prototype that answers one core design question. + +--- + +## Phase 2: Production (Post-Prototype) + +### Goal +Build, polish, and ship the game with full quality gates. + +### Rules +- Use the existing OCGS framework, but with a **consolidated agent hierarchy** (see below). +- All changes require design review, architecture review, and QA sign-off. +- Code lives in `src/` with full coding standards. +- Every system has an ADR in `docs/architecture/`. +- Tests first for gameplay systems (TDD). + +### Slimmed Agent Hierarchy (49 → 10) + +| Tier | Role | Responsibilities | +|------|------|------------------| +| 1 | `creative-director` | Vision, final say on design | +| 1 | `technical-director` | Architecture, tech choices, code quality | +| 2 | `game-designer` | Core mechanics, balance, progression | +| 2 | `art-director` | Visual identity, asset specs | +| 2 | `lead-programmer` | Code review, task breakdown | +| 3 | `gameplay-programmer` | Player systems, combat, UI | +| 3 | `technical-artist` | Shaders, VFX, rendering pipeline | +| 3 | `qa-lead` | Test strategy, bug triage | +| 3 | `sound-designer` | Audio direction | +| 3 | `writer` | Narrative, lore, dialogue | + +> **Note**: The `producer` role is merged into `technical-director`. Cross-domain coordination falls to `technical-director` (sprint planning, milestone reviews, scope management). Gate checks and release coordination are shared with `creative-director`. Design conflicts escalate to `creative-director`. + +### Merged / Deferred Roles +The following roles from the full 49-agent roster are either merged into the 10 above, or deferred until late production: + +- `engine-programmer`, `tools-programmer` → `lead-programmer` +- `ai-programmer`, `network-programmer` → `gameplay-programmer` (until needed) +- `level-designer`, `world-builder` → `game-designer` +- `ui-programmer`, `ux-designer` → `gameplay-programmer` +- `economy-designer`, `systems-designer` → `game-designer` +- `performance-analyst` → `technical-artist` / `lead-programmer` +- `security-engineer`, `accessibility-specialist`, `live-ops-designer` → deferred until late production +- `community-manager`, `analytics-engineer`, `localization-lead` → post-launch only + +--- + +## Decision Gates + +| Gate | Trigger | Checks | +|------|---------|--------| +| **Prototype Gate** | 2–4 weeks or prototype complete | Is it fun? Is scope realistic? | +| **Production Gate** | Prototype approved | Is there a GDD? Is architecture defined? Is team staffed? | +| **Alpha Gate** | Core loop complete | Balance, performance, major bugs | +| **Ship Gate** | Content complete | QA sign-off, no critical bugs | + +**Removed gates** (vs. full OCGS): +- Full architecture review (lightweight ADR is enough) +- Complete epic/story breakdown before implementation +- Pre-commit architecture for every feature + +--- + +## The `/hybrid-prototype` Fast Lane + +A new skill/command that shortcuts the path to a playable prototype: + +1. `creative-director` approves concept (informal/chat). +2. `prototyper` + `godot-specialist` build it. +3. Manual playtest. +4. `creative-director` + `game-designer` decide: **iterate**, **pivot**, or **productionize**. + +**Average time to playable**: 2–3 days instead of 2–3 weeks of planning. + +--- + +## Artifact Comparison + +| Artifact | Discovery | Production | +|----------|-----------|------------| +| Game concept doc | Informal (`design/concept.md`) | Formal GDDs | +| Architecture | None | ADRs required | +| Code | `prototypes/` | `src/` with standards | +| Tests | Manual playtest only | Unit + integration | +| Sprint plans | Weekly goals in chat | Formal sprint plan | +| QA | "Does it crash?" | Full QA plan | + +--- + +## When to Switch to Full OCGS + +Switch back to the **full 49-agent framework** if any of these become true: +- Team grows beyond 5 people +- Project timeline exceeds 6 months +- Multiple features need parallel development +- You need live ops, analytics, or multiplayer +- Funding/publisher requires formal process + +--- + +## Comparison + +| Aspect | Full OCGS | Hybrid | +|--------|-----------|--------| +| Time to first prototype | 2–4 weeks | 2–4 days | +| Process overhead (early) | High | Low | +| Coordination (late) | Excellent | Good | +| Team size | 5–15 | 1–5 | +| Best for | Known game, funded, long timeline | Unknown game, indie, iterating | + +--- + +## Migration Path + +If a project starts with the hybrid workflow and later needs the full OCGS framework: + +1. **Archive prototypes** to `prototypes/archive/`. +2. **Promote surviving designs** to formal GDDs in `design/`. +3. **Write ADRs** for the architecture of systems proven in prototypes. +4. **Recruit additional agents** from the full roster as needed. +5. **Switch to `src/`** with full coding standards. +6. **Enable all quality gates** from the full framework. + +--- + +## Notes + +This workflow is a **first-class citizen** of the OCGS framework, not a hack. All existing OCGS skills, gates, and documentation remain valid and are simply deferred to the Production phase. The `/hybrid-prototype` skill is designed to integrate cleanly with the existing command structure. diff --git a/opencode.json b/opencode.json index 5dad018..d10ae6a 100644 --- a/opencode.json +++ b/opencode.json @@ -1,6 +1,13 @@ { "$schema": "https://opencode.ai/config.json", "plugin": ["./.opencode/plugins/ccgs-hooks.ts"], + "command": { + "hybrid-prototype": { + "template": "Run the hybrid-prototype skill: load .opencode/skills/hybrid-prototype/SKILL.md and follow the fast-lane prototype workflow. Concept: $ARGUMENTS", + "description": "Fast-lane prototype for discovery phase — build a playable prototype in 2-3 days with minimal process overhead.", + "agent": "prototyper" + } + }, "permission": { "bash": { "git status*": "allow", diff --git a/prototypes/.gitkeep b/prototypes/.gitkeep new file mode 100644 index 0000000..e69de29 From 681011c10728bcb8c09ed0d9d1e8315f183b3893 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 22:35:52 +0200 Subject: [PATCH 08/11] fix: Correct /prototype and /hybrid-prototype command docs (#29) Closes #29 --- .opencode/docs/hybrid-workflow.md | 179 +++++++++++++++++++++ .opencode/docs/skills-reference.md | 2 +- .opencode/skills/hybrid-prototype/SKILL.md | 6 +- AGENTS.md | 5 +- 4 files changed, 188 insertions(+), 4 deletions(-) create mode 100644 .opencode/docs/hybrid-workflow.md diff --git a/.opencode/docs/hybrid-workflow.md b/.opencode/docs/hybrid-workflow.md new file mode 100644 index 0000000..9f005a4 --- /dev/null +++ b/.opencode/docs/hybrid-workflow.md @@ -0,0 +1,179 @@ +# Hybrid Discovery-Production Workflow + +## Overview + +This document defines a pragmatic hybrid workflow that balances **creative agility** during pre-production with **production discipline** once the game's direction is proven. It is designed for indie teams (1–5 people) who need to iterate quickly to find the fun, but still want professional-grade coordination when building the real thing. + +**When to use this workflow**: Small teams, unknown designs, short timelines (weeks to a few months), prototypes that may be pivoted or killed. + +**When to use the full OCGS workflow**: Large teams (5–15+), known designs, long timelines (6+ months), funded projects with publisher requirements. + +--- + +## Two-Phase Model + +The project lifecycle is split into two modes with **different rules**: + +| Dimension | Discovery | Production | +|-----------|-----------|------------| +| **Goal** | Find the fun | Ship a polished game | +| **Process overhead** | Low | High (full OCGS) | +| **Time to playable** | 2–4 days | 2–4 weeks planning first | +| **GDDs** | Quick-design / bullet points | Formal GDDs | +| **Architecture** | None | ADRs required | +| **Code location** | `prototypes/` | `src/` | +| **Tests** | Manual playtest only | Unit + integration + QA | +| **Sprint planning** | Weekly goals (informal) | Formal sprint plan | +| **Agents** | 4 core roles | 10 core roles | + +--- + +## Phase 1: Discovery (Pre-Production) + +### Goal +Answer one question per prototype: *Is this mechanic/system/fun?* + +### Rules +- **No formal GDDs.** Use `/quick-design` for lightweight specs, or bullet points in a markdown file. +- **No architecture.** Build throwaway scenes in `prototypes/`. +- **Minimal agents.** Only `creative-director`, `game-designer`, `prototyper`, and `godot-specialist` (or engine equivalent). +- **Time-boxed.** 2–4 weeks maximum per prototype. +- **Kill cheaply.** If it's not fun, pivot or scrap. No sunk-cost fallacy. + +### What NOT to do in Discovery +- Architecture Decision Records (ADRs) +- Epic/story breakdowns +- QA plans +- Asset pipeline setup +- Unit tests (prototypes are throwaway) +- Formal sprint plans + +### Deliverable +A working prototype that answers one core design question. + +--- + +## Phase 2: Production (Post-Prototype) + +### Goal +Build, polish, and ship the game with full quality gates. + +### Rules +- Use the existing OCGS framework, but with a **consolidated agent hierarchy** (see below). +- All changes require design review, architecture review, and QA sign-off. +- Code lives in `src/` with full coding standards. +- Every system has an ADR in `docs/architecture/`. +- Tests first for gameplay systems (TDD). + +### Slimmed Agent Hierarchy (49 → 10) + +| Tier | Role | Responsibilities | +|------|------|------------------| +| 1 | `creative-director` | Vision, final say on design | +| 1 | `technical-director` | Architecture, tech choices, code quality | +| 2 | `game-designer` | Core mechanics, balance, progression | +| 2 | `art-director` | Visual identity, asset specs | +| 2 | `lead-programmer` | Code review, task breakdown | +| 3 | `gameplay-programmer` | Player systems, combat, UI | +| 3 | `technical-artist` | Shaders, VFX, rendering pipeline | +| 3 | `qa-lead` | Test strategy, bug triage | +| 3 | `sound-designer` | Audio direction | +| 3 | `writer` | Narrative, lore, dialogue | + +> **Note**: The `producer` role is merged into `technical-director`. Cross-domain coordination falls to `technical-director` (sprint planning, milestone reviews, scope management). Gate checks and release coordination are shared with `creative-director`. Design conflicts escalate to `creative-director`. + +### Merged / Deferred Roles +The following roles from the full 49-agent roster are either merged into the 10 above, or deferred until late production: + +- `engine-programmer`, `tools-programmer` → `lead-programmer` +- `ai-programmer`, `network-programmer` → `gameplay-programmer` (until needed) +- `level-designer`, `world-builder` → `game-designer` +- `ui-programmer`, `ux-designer` → `gameplay-programmer` +- `economy-designer`, `systems-designer` → `game-designer` +- `performance-analyst` → `technical-artist` / `lead-programmer` +- `security-engineer`, `accessibility-specialist`, `live-ops-designer` → deferred until late production +- `community-manager`, `analytics-engineer`, `localization-lead` → post-launch only + +--- + +## Decision Gates + +| Gate | Trigger | Checks | +|------|---------|--------| +| **Prototype Gate** | 2–4 weeks or prototype complete | Is it fun? Is scope realistic? | +| **Production Gate** | Prototype approved | Is there a GDD? Is architecture defined? Is team staffed? | +| **Alpha Gate** | Core loop complete | Balance, performance, major bugs | +| **Ship Gate** | Content complete | QA sign-off, no critical bugs | + +**Removed gates** (vs. full OCGS): +- Full architecture review (lightweight ADR is enough) +- Complete epic/story breakdown before implementation +- Pre-commit architecture for every feature + +--- + +## The `/prototype` Fast Lane + +A new skill/command that shortcuts the path to a playable prototype: + +1. `creative-director` approves concept (informal/chat). +2. `prototyper` + `godot-specialist` build it. +3. Manual playtest. +4. `creative-director` + `game-designer` decide: **iterate**, **pivot**, or **productionize**. + +**Average time to playable**: 2–3 days instead of 2–3 weeks of planning. + +--- + +## Artifact Comparison + +| Artifact | Discovery | Production | +|----------|-----------|------------| +| Game concept doc | Informal (`design/concept.md`) | Formal GDDs | +| Architecture | None | ADRs required | +| Code | `prototypes/` | `src/` with standards | +| Tests | Manual playtest only | Unit + integration | +| Sprint plans | Weekly goals in chat | Formal sprint plan | +| QA | "Does it crash?" | Full QA plan | + +--- + +## When to Switch to Full OCGS + +Switch back to the **full 49-agent framework** if any of these become true: +- Team grows beyond 5 people +- Project timeline exceeds 6 months +- Multiple features need parallel development +- You need live ops, analytics, or multiplayer +- Funding/publisher requires formal process + +--- + +## Comparison + +| Aspect | Full OCGS | Hybrid | +|--------|-----------|--------| +| Time to first prototype | 2–4 weeks | 2–4 days | +| Process overhead (early) | High | Low | +| Coordination (late) | Excellent | Good | +| Team size | 5–15 | 1–5 | +| Best for | Known game, funded, long timeline | Unknown game, indie, iterating | + +--- + +## Migration Path + +If a project starts with the hybrid workflow and later needs the full OCGS framework: + +1. **Archive prototypes** to `prototypes/archive/`. +2. **Promote surviving designs** to formal GDDs in `design/`. +3. **Write ADRs** for the architecture of systems proven in prototypes. +4. **Recruit additional agents** from the full roster as needed. +5. **Switch to `src/`** with full coding standards. +6. **Enable all quality gates** from the full framework. + +--- + +## Notes + +This workflow is a **first-class citizen** of the OCGS framework, not a hack. All existing OCGS skills, gates, and documentation remain valid and are simply deferred to the Production phase. The `/prototype` skill is designed to integrate cleanly with the existing command structure. diff --git a/.opencode/docs/skills-reference.md b/.opencode/docs/skills-reference.md index 2d3ab60..0a8c8db 100644 --- a/.opencode/docs/skills-reference.md +++ b/.opencode/docs/skills-reference.md @@ -21,7 +21,6 @@ | `/map-systems` | Decompose game concept into systems, map dependencies, prioritize design order | | `/design-system` | Guided, section-by-section GDD authoring for a single game system | | `/quick-design` | Lightweight design spec for small changes — tuning, tweaks, minor additions | -| `/hybrid-prototype` | Fast-lane prototype for hybrid workflow — build, playtest, and decide in 2-3 days | | `/review-all-gdds` | Cross-GDD consistency and game design holism review across all design docs | | `/propagate-design-change` | When a GDD is revised, find affected ADRs and produce an impact report | @@ -110,6 +109,7 @@ | Command | Purpose | |---------|---------| | `/prototype` | Rapid throwaway prototype to validate a mechanic (relaxed standards, isolated worktree) | +| `/hybrid-prototype` | Fast-lane prototype for discovery phase — 2-3 day build, no formal gates, lightweight DECISION.md | | `/onboard` | Generate contextual onboarding document for a new contributor or agent | | `/localize` | Localization workflow: string extraction, validation, translation readiness | diff --git a/.opencode/skills/hybrid-prototype/SKILL.md b/.opencode/skills/hybrid-prototype/SKILL.md index 53c5dd5..83f8ad0 100644 --- a/.opencode/skills/hybrid-prototype/SKILL.md +++ b/.opencode/skills/hybrid-prototype/SKILL.md @@ -10,7 +10,7 @@ isolation: worktree ## Overview -This skill implements the **Discovery Phase fast lane** from `docs/hybrid-workflow.md`. It is intentionally lightweight: no formal GDD, no architecture, no epic breakdown. Just build it, play it, decide. +This skill implements the **Discovery Phase fast lane** as described in `.opencode/docs/hybrid-workflow.md`. It is intentionally lightweight: no formal GDD, no architecture, no epic breakdown. Just build it, play it, decide. **Time budget**: 1-3 days. **Agents involved**: `creative-director`, `game-designer`, `prototyper`, `godot-specialist` (or engine equivalent). @@ -134,7 +134,9 @@ If **ITERATE / PIVOT / KILL**: no further action needed. - If productionizing, rewrite from scratch — do not refactor prototype code - Timebox strictly: if it's not working after 3 days, kill or pivot - Keep the question narrow — one prototype, one question -- **Workflow isolation**: This skill explicitly bypasses `production/review-mode.txt`. If the session previously ran the full OCGS workflow, any stale review-mode state is ignored — the hybrid fast lane always runs without formal gates. +- **Workflow isolation**: This skill explicitly bypasses `production/review-mode.txt`. Any stale review-mode state from a previous full OCGS session is ignored — the hybrid fast lane always runs without formal gates. + +--- ## Differences from Full `/prototype` Skill diff --git a/AGENTS.md b/AGENTS.md index e033c38..1c4a6ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,10 +97,12 @@ Or jump directly to: - `/brainstorm` — explore game ideas from scratch - `/setup-engine godot 4.6` — configure your engine - `/project-stage-detect` — analyze an existing project +- `/prototype` — rapid prototype a concept +- `/hybrid-prototype` — fast-lane prototype for discovery phase ## Available Commands -Type `/` in OpenCode to see all 72 commands. Key categories: +Type `/` in OpenCode to see all available commands. Key categories: - **Onboarding**: `/start`, `/help`, `/project-stage-detect`, `/setup-engine` - **Design**: `/brainstorm`, `/map-systems`, `/design-system`, `/quick-design` @@ -108,6 +110,7 @@ Type `/` in OpenCode to see all 72 commands. Key categories: - **Stories**: `/create-epics`, `/create-stories`, `/dev-story`, `/sprint-plan` - **Reviews**: `/design-review`, `/code-review`, `/balance-check`, `/gate-check` - **QA**: `/qa-plan`, `/smoke-check`, `/soak-test`, `/regression-suite` +- **Prototyping**: `/prototype`, `/hybrid-prototype` - **Team**: `/team-combat`, `/team-narrative`, `/team-ui`, `/team-release` ## Studio Hierarchy From 95cbaa79b0a56395a704a7fd6c074b857b4cfb2d Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 22:39:01 +0200 Subject: [PATCH 09/11] feat: Hybrid Discovery-Production Workflow (#27) Closes #27 --- AGENTS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1c4a6ba..6dc3faa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,6 +90,23 @@ after each significant milestone: The state file should contain: current task, progress checklist, key decisions made, files being worked on, and open questions. +## Workflow Modes + +This project supports two workflow modes. Choose the one that fits your team size and project maturity: + +### Hybrid Workflow (Recommended for Indie Teams) + +- **Discovery Phase**: Rapid prototyping to find the fun. Low process overhead, minimal agents, throwaway code in `prototypes/`. +- **Production Phase**: Full OCGS discipline once the design is proven. Formal GDDs, ADRs, tests, and quality gates. +- **Best for**: Teams of 1–5, unknown designs, iterating to find the fun. +- **See**: `docs/hybrid-workflow.md` for full details. + +### Full OCGS Workflow + +- **All phases formal**: Every feature goes through design → architecture → stories → code → tests → review. +- **Best for**: Teams of 5–15, known designs, long timelines, publisher requirements. +- **See**: Full documentation in `docs/` and `.opencode/skills/`. + ## Getting Started Run `/start` in OpenCode to begin the guided onboarding flow. From 3572f3d1390471f5a246da4b1b22446198711ac3 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 22:53:24 +0200 Subject: [PATCH 10/11] fix: Pin opencode action to @v1 instead of @latest to avoid GitHub API rate limiting --- .github/workflows/opencode-review.yml | 2 +- .github/workflows/opencode.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/opencode-review.yml b/.github/workflows/opencode-review.yml index e7641e1..f44d6da 100644 --- a/.github/workflows/opencode-review.yml +++ b/.github/workflows/opencode-review.yml @@ -24,7 +24,7 @@ jobs: git config --global user.email "github-actions[bot]@users.noreply.github.com" git config --global user.name "github-actions[bot]" - - uses: anomalyco/opencode/github@latest + - uses: anomalyco/opencode/github@v1 env: OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/opencode.yml b/.github/workflows/opencode.yml index c3c798a..bef8712 100644 --- a/.github/workflows/opencode.yml +++ b/.github/workflows/opencode.yml @@ -27,7 +27,7 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} - name: Run opencode - uses: anomalyco/opencode/github@latest + uses: anomalyco/opencode/github@v1 env: OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 438c85147fbc44532db5de2486041c377c0128e0 Mon Sep 17 00:00:00 2001 From: Jaco du Preez Date: Sat, 2 May 2026 22:58:07 +0200 Subject: [PATCH 11/11] revert: Restore @latest tag for opencode action --- .github/workflows/opencode-review.yml | 2 +- .github/workflows/opencode.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/opencode-review.yml b/.github/workflows/opencode-review.yml index f44d6da..e7641e1 100644 --- a/.github/workflows/opencode-review.yml +++ b/.github/workflows/opencode-review.yml @@ -24,7 +24,7 @@ jobs: git config --global user.email "github-actions[bot]@users.noreply.github.com" git config --global user.name "github-actions[bot]" - - uses: anomalyco/opencode/github@v1 + - uses: anomalyco/opencode/github@latest env: OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/opencode.yml b/.github/workflows/opencode.yml index bef8712..c3c798a 100644 --- a/.github/workflows/opencode.yml +++ b/.github/workflows/opencode.yml @@ -27,7 +27,7 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} - name: Run opencode - uses: anomalyco/opencode/github@v1 + uses: anomalyco/opencode/github@latest env: OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}