From 2d4ba0d742857276df62e470f36ee5accc76e449 Mon Sep 17 00:00:00 2001 From: gentlius Date: Thu, 11 Jun 2026 12:23:15 +0900 Subject: [PATCH] =?UTF-8?q?docs(adr):=20ADR-0001=20=E2=80=94=20Engine=20Sp?= =?UTF-8?q?ecialist=20Separation=20Policy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codifies when an engine family adds a separate language-quality specialist agent vs absorbs language quality into the framework primary. Policy: separate only when multiple distinct languages co-exist within the same project; absorb when a single language is the de-facto framework requirement. Retroactively explains the existing Godot (separate GDScript + C#) vs Unity (C# absorbed) vs Unreal (Blueprint separate, C++ absorbed) asymmetry, and provides a mechanical rule for future engine family additions. Originating fork accepted this as policy when adding the HTML5 engine family (TypeScript absorbed into pixijs-specialist). Submitted upstream as Proposed for adoption — independent value even without the HTML5 family PR. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...001-engine-specialist-separation-policy.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/architecture/001-engine-specialist-separation-policy.md diff --git a/docs/architecture/001-engine-specialist-separation-policy.md b/docs/architecture/001-engine-specialist-separation-policy.md new file mode 100644 index 0000000000..81bd3c9860 --- /dev/null +++ b/docs/architecture/001-engine-specialist-separation-policy.md @@ -0,0 +1,161 @@ +# ADR-0001: Engine Specialist Separation Policy + +## Status + +Proposed (submitted upstream; accepted in originating fork) + +## Date + +2026-06-11 + +## Last Verified + +2026-06-11 + +## Decision Makers + +- technical-director (recommended) +- Originating fork maintainer — approved during HTML5/PixiJS engine family addition session + +## Summary + +Defines when an engine family adds a separate language-quality specialist agent vs absorbs language quality into the framework primary. Policy: separate specialist only when **multiple distinct languages co-exist within the same project**; absorb when **a single language is the de-facto framework requirement**. This codifies the choice made when adding the HTML5 engine family (TypeScript absorbed into `pixijs-specialist`) and retroactively explains the Godot vs Unity/Unreal asymmetry. + +## Engine Compatibility + +| Field | Value | +|-------|-------| +| **Engine** | All (cross-engine framework policy) | +| **Domain** | Core (agent architecture) | +| **Knowledge Risk** | LOW — this is a framework policy, not engine API | +| **References Consulted** | Existing agent files under `.claude/agents/` (godot-*, unity-*, ue-*, html5-*) | +| **Post-Cutoff APIs Used** | None | +| **Verification Required** | None — policy adherence verified by agent file inventory | + +## ADR Dependencies + +| Field | Value | +|-------|-------| +| **Depends On** | None | +| **Enables** | Future engine family additions can apply this policy mechanically | +| **Blocks** | None | +| **Ordering Note** | First ADR in CCGS framework; sets precedent for agent architecture decisions | + +## Context + +### Problem Statement + +When adding a new engine family to the CCGS framework, framework maintainers face a recurring decision: should language code quality (e.g., TypeScript review, GDScript style enforcement, C# idiom checks) get its own specialist agent, or be absorbed into the framework primary's responsibilities? Without a written policy, the choice has been made ad hoc — Godot has separate `godot-gdscript-specialist` and `godot-csharp-specialist`, while Unity has no `unity-csharp-specialist` and Unreal has no `unreal-cpp-specialist`. The asymmetry looks arbitrary to outside observers and provides no guidance for the next engine family. + +### Current State + +Existing CCGS agent composition (as of 2026-06-11): + +| Engine | Primary | Language Specialist(s) | Reasoning (implicit) | +|--------|---------|------------------------|----------------------| +| Godot | `godot-specialist` | `godot-gdscript-specialist` + `godot-csharp-specialist` (separate) | Two distinct languages can co-exist in one Godot project | +| Unity | `unity-specialist` | None (C# absorbed into primary) | C# is the only Unity language; no alternative | +| Unreal | `unreal-specialist` | `ue-blueprint-specialist` (Blueprint only) | Blueprint is a distinct authoring surface (visual graphs) vs C++ text | +| HTML5 (proposed) | `html5-specialist` | `pixijs-specialist` (absorbs TS quality) | **Decision needed** — proposed below | + +The HTML5 family addition forced an explicit decision: separate `typescript-game-specialist` (6 agents) vs absorb TS into `pixijs-specialist` (5 agents). + +### Constraints + +- Adding agents has marginal cost: ~150 lines per agent file, routing table maintenance, user mental load remembering which specialist owns which file extension +- Agent overlap creates ownership ambiguity (two specialists fighting over the same `.ts` file) +- Framework precedent should be self-consistent — outside contributors expect future engine additions to follow a predictable rule + +### Requirements + +- A single, technically-grounded rule that determines specialist separation for any future engine family +- Rule must retroactively explain existing Godot/Unity/Unreal asymmetry +- Rule must mechanically resolve the HTML5 TS specialist question +- Rule must not produce absurd outcomes for hypothetical future engines (e.g., a hypothetical Bevy/Rust addition) + +## Decision + +**Engine Specialist Separation Rule**: + +> A language-quality specialist agent is created **only when** an engine family routinely supports **two or more distinct, structurally different languages within the same project**. Otherwise, language quality is absorbed into the framework primary specialist. + +### Mechanical Application + +| Engine | Languages | Co-existence in one project? | Verdict | +|--------|-----------|------------------------------|---------| +| Godot | GDScript + C# | Yes (`.gd` + `.cs` in same project, ~normal) | **Separate** specialists per language | +| Unity | C# | No (single language) | **Absorbed** into `unity-specialist` | +| Unreal | C++ + Blueprint | Yes (text + visual graphs are structurally different) | **Separate** `ue-blueprint-specialist` for Blueprint; C++ absorbed into `unreal-specialist` | +| HTML5 | TypeScript (or JS) | No (one language identity per project) | **Absorbed** into `pixijs-specialist` | + +### Definition of "Structurally Different" + +Two languages are structurally different if: +1. They have **different file extensions** AND +2. They have **different authoring surfaces** (text vs visual graph vs DSL) OR **different runtime targets** (managed vs native vs DOM) + +C++ and C# both being "text-based imperative typed" languages does NOT, by itself, force separation. What matters is whether a *single project* uses both for non-overlapping reasons. + +### Boundary Cases Resolved + +- **HTML5 with TypeScript vs Vanilla JS**: These are NOT considered co-existing — a project picks one language identity (per Appendix B1 guardrail in setup-engine SKILL.md). Therefore single language → absorbed. +- **Future Bevy/Rust engine**: Single language (Rust) → absorbed. Primary `bevy-specialist` covers Rust idiom. +- **Future engine with native + scripting (e.g., Lua + C++ in Solar2D)**: Two structurally different languages → separate specialists. + +## Consequences + +### Positive + +- New engine family additions become mechanical decisions, not committee debates +- Asymmetry between existing engines is now justified by a written rule rather than apparent arbitrariness +- Agent count grows linearly with genuine complexity, not with engine count +- Outside contributors can predict the agent composition before reading individual agent files + +### Negative + +- A future case may emerge where the rule produces a result that "feels wrong" — the rule is heuristic, not algorithmic. In that case: write a new ADR superseding this one, don't quietly violate. +- The rule does not cover non-language specialist separation (shader specialist, build specialist, etc.) — those decisions remain per-engine. + +### Neutral + +- This ADR is meta: it governs the framework's own architecture, not any game's runtime architecture. It will be referenced by future engine-addition PRs. + +## Alternatives Considered + +### Alternative 1: Always Separate (Strict Decomposition) + +Every engine family gets a separate language specialist regardless of co-existence. + +- **Pro**: Maximum consistency. +- **Con**: Inflates agent count for no benefit; unity-csharp-specialist would be functionally identical to unity-specialist; user confusion about which to invoke. +- **Verdict**: Rejected — adds cost without benefit. + +### Alternative 2: Always Absorb (Minimum Decomposition) + +Every engine family has only a primary specialist; language quality always absorbed. + +- **Pro**: Smallest framework. +- **Con**: Cannot route `.gd` vs `.cs` files in a Godot project that uses both — primary can't be specialized for both at once. +- **Verdict**: Rejected — breaks the Godot dual-language case which is a legitimate real-world configuration. + +### Alternative 3: Case-by-Case (No Rule) + +Continue making the decision per engine family with no written policy. + +- **Pro**: Maximum flexibility. +- **Con**: This is the current state and is what created the asymmetry concern in the first place. +- **Verdict**: Rejected — rule must exist to prevent ad hoc accumulation. + +## Implementation + +This ADR is implemented by the existing agent inventory at the time of writing. No code changes required. Future engine family additions must: + +1. Apply the rule mechanically in their setup-engine extension +2. Document the language co-existence assessment in the engine's `VERSION.md` or `current-best-practices.md` +3. Reference this ADR in the new engine's setup-engine appendix + +## References + +- HTML5 engine family addition session (2026-06-11) — origin of this ADR +- Existing agent files under `.claude/agents/` — empirical inputs +- `.claude/skills/setup-engine/SKILL.md` Appendix A (Godot variants) and Appendix B (HTML5 variants) — applied examples