feat: add engine-sfml3 and engine-raylib modules to OCGS framework

[striderZA]

Summary

• Two new engine modules: engine-sfml3 and engine-raylib, each installable via node .opencode/modules/install.mjs add <name>
• Each ships a single specialist agent (sfml-specialist, raylib-specialist) covering C++ best practices, build system, and library-specific patterns
• /setup-engine now supports SFML 3 and Raylib: engine selection, tradeoff guidance, CLAUDE.md templates, naming conventions, specialist routing, and CMake build scaffolding (Section 4.5)
• engine-code.md updated with C++ hot-path examples alongside existing GDScript ones
• AGENTS.md updated to reflect the new engines, agent/skill counts, and available modules
• All 182 framework validations pass

Files changed

• 6 new files (2 module definitions, 2 agent files, 2 module YAML configs)
• 4 modified files (installed.json, engine-code.md, setup-engine/SKILL.md, AGENTS.md)
• 1145 insertions, 25 deletions across 10 files

[github-actions]

PR Review: feat: add engine-sfml3 and engine-raylib modules

Verdict: APPROVED with minor issues

All 182 framework validations pass. The new specialist agents are thorough and correctly structured. The setup-engine skill additions are comprehensive and accurate. Below are findings:

---

🔴 Bug: AGENTS.md header count not updated

AGENTS.md:3 still says 49 coordinated OpenCode agents. Should be 51. The project structure section at line 25 and the Notes section were correctly updated, but the heading count was missed.

---

🟡 Inconsistency: installed.json path format

New entries use bare paths (agents/sfml-specialist.md), matching the design and audio modules:

"engine-sfml3": { "files": ["agents/sfml-specialist.md"] }

But engine-godot uses .opencode/agents/...:

"engine-godot": { "files": [".opencode/agents/godot-specialist.md"] }

If the install/remove scripts expect one format or the other, this will break. Verify against install.mjs — if it trims path prefixes, both work; if not, the bare paths will fail uninstall.

---

🟢 Quality highlights

• Agent content: Both specialists have all required sections, including Delegation Map and What This Agent Must NOT Do — better than the Unreal/Unity specialists (8 of which are in the exceptions list for missing those sections)
• C++ examples in engine-code.md: Correct zero-alloc reuse patterns with std::vector::clear() + reserve()
• CMake scaffolding: SFML uses find_package with explicit components; Raylib uses find_package with FetchContent fallback — idiomatic for both ecosystems
• Engine tradeoff guidance in setup-engine: Balanced, honest assessments of SFML 3 and Raylib limitations (no visual editor, no physics, desktop focus for SFML)
• Version awareness: Both agents reference docs/engine-reference/ with the same cutoff-awareness pattern as Godot specialists
• SFML main.cpp: Uses C++17 const auto event = window.pollEvent() with std::optional-style pattern — correct for SFML 3
• Raylib main.cpp: Standard init-update-draw pattern with WindowShouldClose() — idiomatic

---

🟢 Clean counts

Metric	Prior	Now	Actual
Agents	49	51	51
Skills	75	77	77
Commands	50	50	54*

*54 command files on disk vs. 50 documented (53 pass validation) — pre-existing discrepancy, unrelated to this PR.

---

Summary

Solid addition. Two engines added with correct module structure, well-researched agent personalities, and thorough setup-engine integration. Fix the count on AGENTS.md line 3 and verify the installed.json path format is compatible with install.mjs.

opencode session  |  github run

[github-actions]

Here is my full review of the PR.

---

PR Review: feat: add engine-sfml3 and engine-raylib modules

Verdict: APPROVED with minor corrections needed

The PR is well-structured and comprehensive. Both engine modules are implemented correctly with thorough documentation, idiomatic code examples, and proper framework integration. Below are specific findings.

---

🔴 Bug: AGENTS.md heading count stale

AGENTS.md:3 — still says 49 coordinated OpenCode agents. Should be 51. The Notes section and project structure diagram were correctly updated, but the opening line was missed.

🔴 Bug: setup-engine Raylib CMake scaffold uses CMAKE_CXX_STANDARD unconditionally

Section 4.5 at line 273–274 sets CMAKE_CXX_STANDARD 17 for Raylib's CMakeLists.txt, but Section 5 at line 351–352 correctly notes that both C and C++ are viable for Raylib. If the user chooses C, the scaffolded CMake should set CMAKE_C_STANDARD 11 not CMAKE_CXX_STANDARD. Compare with Section 7.4 (line 715–716) which correctly provides both. 4.5's template should follow the same conditional pattern or default to C if user picks C.

🟡 Inconsistency: installed.json path format

Existing engine-godot entries use .opencode/agents/... paths, while the new entries use bare agents/... paths matching the design module. Per install.mjs:248, the installer records paths relative to .opencode/ — meaning bare agents/... is correct and the engine-godot entries are the outliers. Not a bug in this PR, but the pre-existing engine-godot/engine-unity/engine-unreal entries should be cleaned up in a follow-up to match the actual installer format, otherwise remove may fail to locate the files.

🟡 Issue: Duplicate agent files at module install time

Agent files exist in both .opencode/agents/ and .opencode/modules/engine-{sfml3,raylib}/agents/ as identical copies (not symlinks). This is the pattern used by the modular install system (copy on install), but it means there are two copies in the repo. When install.mjs add runs, it will overwrite the root copy with an identical one — this is fine functionally, but if the two copies ever drift, the module's copy takes precedence on reinstall. Worth documenting or linking via a CI check.

🟢 Quality highlights

• Agent files complete: Both sfml-specialist.md and raylib-specialist.md include all required sections: Core Responsibilities, Best Practices (broken down by subsystem), Delegation Map, "What This Agent Must NOT Do", Version Awareness, and When Consulted. This is better coverage than several existing engine specialists (e.g., Unity/Unreal specialists flagged in the validation exceptions list).

• C++ examples in engine-code.md: Correct zero-alloc patterns (clear() + reserve()), proper sf::VertexArray reuse, and anti-pattern entries like "Creating/destroying sf::Texture or RenderTexture2D as local variables" — all idiomatic for the respective libraries.

• SFML main.cpp: Uses the correct SFML 3 std::optional-style event polling (const auto event = window.pollEvent() with event->is<sf::Event::Closed>()), matching the SFML 3 API change from SFML 2's window.pollEvent(event).

• Raylib main.cpp: Standard init-update-draw pattern, WindowShouldClose(), BeginDrawing()/EndDrawing() — fully idiomatic.

• CMake scaffolding:

  • SFML: find_package(SFML 3 REQUIRED COMPONENTS ...) with separate target_link_libraries per module — correct.
  • Raylib: find_package(raylib QUIET) with FetchContent fallback — correct and follows community best practices.
  • Both targets set(CMAKE_CXX_STANDARD 17) appropriately (though see bug above re: Raylib).

• Engine tradeoff guidance in setup-engine (Section 2): Honest assessments — SFML3 noted as desktop-only with no editor, Raylib noted as C API with limited 3D — presented alongside genuine strengths. The genre-specific mapping at lines 97-109 is comprehensive and correct.

• Specialist routing tables: Per-engine tables at lines 494-532 are thorough, covering file extension routing and which specialist to spawn for each file type.

• Knowledge gap awareness: Both agents include Version Awareness sections referencing docs/engine-reference/ with the same cutoff logic as Godot specialists. Lines 553-554 in setup-engine correctly estimate training data coverage for both.

• Cross-references in engine-code.md: Lines 81-87 correctly reference the new sfml-specialist and raylib-specialist agents.

🟢 Count verification

Metric	AGENTS.md	Actual on disk
Agents	51	51
Skills	77	77 (75 + 2 new agent skills = 77)
Commands	50	54*

*Pre-existing discrepancy — 54 command files, 50 documented. Unrelated to this PR.

---

Required fixes before merge

1. AGENTS.md:3 — Change 49 to 51
2. setup-engine SKILL.md Section 4.5 — Make the Raylib CMake template conditional on language choice (C vs C++), matching Section 7.4's approach

Recommended follow-ups (not blocking)

3. Normalize installed.json path format across all modules (drop .opencode/ prefix from existing engine entries to match the new entries and the install.mjs output format)
4. Add a CI step to verify that module agent copies in .opencode/modules/*/agents/ match their counterparts in .opencode/agents/

opencode session  |  github run