## Summary Add a **libGDX engine specialist agent set** to the roster, mirroring the existing Godot / Unity / Unreal structure. libGDX is a mature, open-source (Apache 2.0), cross-platform Java game framework with strong desktop, Android, iOS, and web (GWT) support. It currently has no representation in CCGS, leaving a gap for the substantial share of indie / mobile / 2D projects built on it. The proposal: one lead agent (`libgdx-specialist`) plus four sub-specialists covering libGDX's main subsystems, a matching `docs/engine-reference/libgdx/` directory, and `/setup-engine libgdx ` support. ## Type - [x] New agent - [ ] New skill (slash command) - [ ] New hook - [ ] New rule - [ ] New template - [x] Improvement to existing component *(extends the Engine Specialists table in the README + the `/setup-engine` skill)* - [ ] Other: ## Problem / Motivation CCGS currently supports three engines — all full IDE-driven engines with visual editors: | Engine | Style | |---|---| | Godot 4 | Engine + visual editor | | Unity | Engine + visual editor | | Unreal 5 | Engine + visual editor | libGDX occupies a different, well-populated niche: it's a **code-first framework** with no built-in visual editor. That distinction is actually a **strength for AI-assisted development** — every part of a libGDX project (scenes, UI layouts, asset references, build config) lives in source/config files that Claude can read and write directly, with no binary `.scn` / `.prefab` / `.uasset` blobs to work around. That arguably makes it the cleanest fit of any engine for a CCGS-style workflow. Concrete reasons to add it: 1. **Real audience gap.** libGDX is one of the most widely used open-source frameworks for 2D indie and mobile games. CCGS users building with it today fall back to the generic `engine-programmer`, which carries no libGDX-specific guidance (lifecycle, Scene2D, `AssetManager`, Ashley ECS, Gradle backends). 2. **Code-first = agent-friendly.** No editor, no proprietary asset format, no GUI-only steps. The entire project is text. This aligns perfectly with CCGS's "Question → Options → Decision → Draft → Approval → Write" loop. 3. **Cross-platform in one codebase.** Desktop / Android / iOS / web from a single Java/Kotlin codebase via backends — a meaningful capability not fully covered by the current trio (especially mobile-first deployment). 4. **Parallels existing structure.** libGDX's subsystems map cleanly onto CCGS's lead + sub-specialist pattern, so this is an extension of a proven template rather than a new shape. ## Proposed Solution ### 1. Agent roster — one lead + four sub-specialists (mirrors the Unity/Godot pattern) Update the README's **Engine Specialists** table: | Engine | Lead Agent | Sub-Specialists | |---|---|---| | **libGDX** | `libgdx-specialist` | Scene2D/UI, Graphics/Shaders, Ashley ECS + Box2D, Core/Gradle | New agent files in `.claude/agents/`: | Agent | Domain | Model | |---|---|---| | `libgdx-specialist` | Lead — libGDX authority, Java vs Kotlin (`libktx`) decisions, module architecture, cross-platform backends, deployment | sonnet | | `libgdx-scene2d-specialist` | Scene2D scene graph + Scene2D.ui (widgets, `Table`/`Skin`, `Dialog`, `InputMultiplexer`) | sonnet | | `libgdx-graphics-specialist` | OpenGL ES rendering, custom shaders, `SpriteBatch`, 3D API (`ModelBatch`, decals), FBOs, `ParticleEffect` | sonnet | | `libgdx-ashley-specialist` | Ashley ECS (entity/component/system), Box2D physics, collision, `EntitySystem` scheduling | sonnet | | `libgdx-core-specialist` | `ApplicationListener` lifecycle, modules (Graphics/Audio/Files/Input/Net), `AssetManager`, Gradle project setup, backend/platform deployment | sonnet | Each agent follows the existing template: YAML frontmatter (`name`, `description`, `tools: Read, Glob, Grep, Write, Edit, Bash, Task`, `model: sonnet`, `maxTurns: 20`), the standard **Collaboration Protocol**, a libGDX-specific **Best Practices to Enforce** section, a **Delegation Map** (lead delegates to the four subs; subs escalate to the lead; reports up to `technical-director` via `lead-programmer`), the **Version Awareness** block, and a **ripgrep File Filtering** note (see #5). ### 2. libGDX best practices the agents would enforce (selected) - **Lifecycle:** implement `ApplicationListener` (or extend `Game`/`Adapter`); never block the render thread; handle `resume()`/`pause()` for Android lifecycle; `dispose()` every native resource (`Texture`, `Sound`, `SpriteBatch`, `ShaderProgram`) — libGDX does **not** GC native memory. - **Asset pipeline:** load via `AssetManager`, never `new Texture(...)` for shared/long-lived assets; `finishLoading()`/`update()` correctly; group assets by level/screen and dispose on screen change. - **Scene2D UI:** `Table`-based layouts, `Skin` (JSON + atlas) for styling, `InputMultiplexer` for input routing; never manual `draw()` on actors. - **ECS (Ashley):** favor composition; keep `EntitySystem` logic data-oriented; use `PooledEngine` for entity reuse; separate components (data) from systems (logic). - **Performance:** no allocations in `render()`; reuse `Vector2`/`Vector3` temporaries; minimize `SpriteBatch` flushes (atlas + stable texture/blend order); prefer object pooling for projectiles/particles. - **Build/deploy:** Gradle multi-module layout (`core`/`desktop`/`android`/`ios`/`html`); pin libGDX + backend versions consistently; headless LWJGL3 for CI tests. - **Language:** Kotlin via `libktx` where the team chooses it, but keep Java interop idioms (null-guard platform call sites). ### 3. Supporting `engine-reference` docs Create `docs/engine-reference/libgdx/` matching the structure the `godot-specialist` already reads: ``` docs/engine-reference/libgdx/ VERSION.md # pinned version (current stable, 1.12.x as of writing) deprecated-apis.md # removed/changed APIs across releases breaking-changes.md # LWJGL2 → LWJGL3, packaging/instantiation changes, etc. modules/ scene2d.md graphics.md ashley.md asset-manager.md ``` ### 4. `/setup-engine libgdx ` Extend the existing `/setup-engine` skill to recognize `libgdx` (and the Kotlin variant via `libktx`), generating the standard Gradle module layout, the `technical-preferences.md` entries, and the `CLAUDE.md` engine block. ### 5. ripgrep note (mirrors the Godot `*.gd` gotcha) Add to each libGDX agent: > `java` is a built-in ripgrep type, but **Kotlin support varies across ripgrep builds.** Always prefer explicit globs for reliability: `rg --glob "*.java" --glob "*.kt"`. Do not assume `--type kotlin` is registered. ## Alternatives Considered 1. **Do nothing; let users lean on `engine-programmer`.** Rejected — that agent carries no libGDX domain knowledge and misses the framework-specific pitfalls above (native resource disposal, `AssetManager`, Scene2D idioms, Ashley). The whole point of CCGS is domain-specialized agents. 2. **A single `libgdx-specialist` with no subs.** Cheaper, but inconsistent with the Unity/Godot/Unreal pattern and underpowered — libGDX's surface area (Scene2D UI, OpenGL shaders, ECS, Gradle backends) is comparable to Unity's, which already splits four ways. 3. **Fold libGDX into a generic "JVM specialist."** Rejected — too broad; it would dilute the libGDX-specific guidance the same way `engine-programmer` currently does. 4. **Wait for community PRs.** This issue exists to signal demand and sketch the agreed shape, so a contributor (possibly me) can implement against it. ## Additional Context - libGDX official site / docs: https://libgdx.com/ / https://libgdx.com/wiki/ - Source (Apache 2.0): https://github.com/libgdx/libgdx - Kotlin extensions (`libktx`): https://github.com/libktx/ktx - Ashley ECS: https://github.com/libgdx/ashley - The proposed structure is a 1:1 extension of the existing engine block; **no changes to hooks, rules, or the coordination model** are required. - Happy to open a PR implementing this if there's interest — I'd follow `CONTRIBUTING.md` (subdirectory skill format, Collaboration Protocol in each agent, `grep -E` everywhere, Windows/macOS/Linux-compatible).
