Full web engine implementation: PixiJS and ThreeJS agents and skills

[robertobalestri]

Summary

Introduces a full Web engine agent set (web-specialist plus six sub-specialists for
TypeScript, PixiJS, Three.js, shaders, UI, and platform) and mirrors those additions in
the Skill Testing Framework with new agent specs and catalog entries. Updates core docs,
templates, rules, and multiple skills to support Web (PixiJS/Three.js) workflows,
routing, testing, and setup guidance, while updating agent counts from 49 to 56. Also
adds a complete docs/engine-reference/web/ reference pack (versioning, breaking and
deprecated APIs, best practices, plugins, and subsystem modules) to enforce current
web-stack API usage.

Web is modeled as one engine with three renderer variants (PixiJS / Three.js / Both),
occupying the same structural slot as Godot's language question — not as two peer engines.
PixiJS and Three.js sit on an identical platform (TypeScript, Vite, WebGPU/WebGL2, Web
Audio, DOM), so splitting them would duplicate that stack twice and orphan hybrid projects.

Type of Change

• New agent
• New skill — no new skills; 10 existing skills modified
• New hook or rule — no new rules; 4 existing rules extended
• Documentation improvement
• Other: new engine target (Web) + version-pinned reference pack

Changes

Agents (7 new)

• web-specialist — primary: renderer choice, fixed-timestep game loop, WebGPU vs WebGL2,
  project structure. Holds Task and a Sub-Specialist Orchestration section
• web-typescript-specialist — strict typing, discriminated unions, type-safe event buses,
  Zod at boundaries, module dependency direction
• pixi-specialist — PixiJS v8 containers, batching and draw calls, atlases, ticker, culling
• three-specialist — scene graph, materials, GLTF/DRACO/KTX2, instancing, RenderPipeline
• web-shader-specialist — GLSL ES 3.0, WGSL, TSL/NodeMaterial, Pixi filters, backend parity
• web-ui-specialist — DOM-vs-canvas decision, pointer events, gamepad polling, a11y, safe areas
• web-platform-specialist — Vite/bundling, code splitting, asset streaming, payload budgets,
  deployment

Engine reference pack (13 new docs, docs/engine-reference/web/)

• VERSION.md pins PixiJS 8.19, Three.js r185, TypeScript 7.0, Vite 8.0, Node 24 LTS
• Risk is assessed per library and fixed at permanently HIGH — unlike a single-binary
  engine, Three.js ships roughly monthly and removes deprecated code in most releases, so any
  model cutoff will always sit several releases behind
• breaking-changes.md, deprecated-apis.md, current-best-practices.md, PLUGINS.md
• 8 subsystem modules: rendering, physics, input, audio, ui, animation, navigation, networking
• All version content researched against current releases, not written from model memory

/setup-engine

• Web added to the prior-experience question and platform matrix (Web/Browser now routes to
  Web rather than Godot)
• Honest-tradeoffs block covering the real limitations: no console path, mobile perf ceiling,
  no editor, zero asset protection, audio-gesture requirement, DIY 3D pipeline
• Renderer selection question; TypeScript naming conventions; genre guidance rows
• New Appendix B with all three renderer variants: tech-stack templates, testing config,
  routing blocks, and file-extension routing
• Web is barred from the LOW-RISK path — reference docs are never optional

Skills modified (10)

• test-setup — Vitest + Playwright config and CI workflow; documents that web CI needs no
  engine binary, no license, and no self-hosted runner, plus the SwiftShader caveat
• prototype — path convergence: for Web projects the HTML and Engine paths are the same,
  and the "browser latency lies about feel" warning is explicitly inverted, because that
  latency is the shipping reality
• dev-story — web routing note: routing keys on imports and directory, first-match-wins,
  because nearly every source file is .ts
• test-flakiness — web flake sources (rAF timing, canvas readback, font-load races)
• architecture-review — per-library version agreement, renderer consistency, backend
  assumptions, payload implications
• vertical-slice, localize, test-helpers, brainstorm, plus the coding-standards CI row

Rules extended (4)

• engine-code.md — GC pressure framing, explicit GPU disposal, renderer-independent simulation
• ui-code.md — DOM-vs-canvas, pointer events, 100dvh, safe areas, UI/frame-time coupling
• shader-code.md — web naming, WebGPU/WebGL2 parity, TSL vs raw GLSL
• prototype-code.md — the convergence trap: prototype runs on the shipping stack, so
  "rewrite, don't migrate" loses its natural enforcement

No web-code.md was added — a rule scoped to src/**/*.ts would overlap the existing
path scopes and produce contradictory guidance on the same files.

Skill Testing Framework

• 7 agent specs under agents/engine/web/, each with static assertions, 5 test cases,
  protocol compliance, and coverage notes
• 7 catalog.yaml entries (validated: parses, 56 agents / 72 skills)

Docs and counts (49 → 56)

• README.md (badges, counts, new Supported Engines table), CLAUDE.md, agent-roster.md,
  agent-coordination-map.md, rules-reference.md, quick-start.md,
  engine-reference/README.md, coding-standards.md, game-concept.md,
  pitch-document.md, and both Skill Testing Framework docs

Checklist

• I've tested this in a Claude Code session
• New agents include the Collaboration Protocol section
• New skills use the subdirectory format — N/A, no new skills added
• Reference docs are updated (agent-roster, skills-reference, hooks-reference, rules-reference)
• Hooks use grep -E (POSIX) and fail gracefully without jq/python — N/A, no hooks touched
• No hardcoded paths or platform-specific assumptions

Verification performed

Structural sweep — all passing:

• Agent frontmatter parses, 5/5 required keys on all 7
• Agent count: 56 files = 56 in README badge
• All routing-table agent names resolve to real files (7/7)
• All reference docs cited by agents exist (13/13), each carrying Last verified:
• All catalog.yaml spec paths resolve (7/7); YAML validates
• No absolute or platform-specific paths in any new file

Runtime test — pixi-specialist invoked against a PixiJS Application setup task, the case
where v7 patterns most dominate training data. It avoided every trap: await app.init()
(not the sync constructor), app.canvas (not app.view), named ESM imports (no PIXI.*
global), and Assets.load() before constructing the Sprite (correctly noting BaseTexture
no longer exists). It read the reference docs before drafting and cited them, respected the
Collaboration Protocol by writing no files and asking clarifying questions, and correctly
deferred scaffolding to web-platform-specialist.

Scope note: PLUGINS.md serves as the ecosystem index; no plugins/ subdirectory of
per-package deep-dives was added. Unity and Unreal have one, Godot does not — this matches
Godot.

[Copilot]

Pull request overview

Adds Web (PixiJS / Three.js) as a first-class “engine” option in the CCGS template, including new engine specialists, an engine reference pack, Skill Testing Framework coverage, and updates to existing skills/rules/docs to support Web workflows end-to-end.

Changes:

• Introduces a new Web engine specialist set (primary + 6 sub-specialists) and corresponding Skill Testing Framework agent specs + catalog entries.
• Adds a pinned Web engine reference pack under docs/engine-reference/web/ (versions, breaking/deprecated APIs, best practices, and subsystem modules).
• Updates existing skills, rules, and templates to route/setup/test Web projects and reflect updated agent counts (49 → 56).

Reviewed changes

Copilot reviewed 54 out of 54 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Updates agent counts and documents Web as a supported engine option.
docs/engine-reference/README.md	Explains why Web reference docs are “permanently high risk” and always required.
docs/engine-reference/web/VERSION.md	Defines the pinned Web stack versions and risk framing.
docs/engine-reference/web/breaking-changes.md	Documents major API/toolchain breaking changes for the pinned Web stack.
docs/engine-reference/web/deprecated-apis.md	Quick lookup of stale/removed APIs and replacements.
docs/engine-reference/web/current-best-practices.md	Establishes current architectural/performance/testing recommendations for web games.
docs/engine-reference/web/PLUGINS.md	Curates optional ecosystem packages commonly used in web games.
docs/engine-reference/web/modules/rendering.md	Provides Pixi/Three rendering setup guidance and disposal/DPR recommendations.
docs/engine-reference/web/modules/ui.md	Documents DOM-vs-canvas UI guidance, a11y constraints, and UI performance pitfalls.
docs/engine-reference/web/modules/input.md	Captures recommended input handling patterns (Pointer Events, gamepad polling, blur clear).
docs/engine-reference/web/modules/audio.md	Documents autoplay-gesture constraints and Web Audio best practices.
docs/engine-reference/web/modules/physics.md	Explains physics dependency choices and fixed-timestep stepping guidance.
docs/engine-reference/web/modules/animation.md	Sets expectations for animation systems and fixed-timestep advancement.
docs/engine-reference/web/modules/networking.md	Documents transport choices and the “server authoritative” rule for web games.
docs/engine-reference/web/modules/navigation.md	Documents pathfinding responsibilities and main-thread budgeting advice.
CLAUDE.md	Extends the template’s engine/language choices to include Web + TypeScript.
CCGS Skill Testing Framework/README.md	Updates framework docs to reflect 56 agents in the catalog.
CCGS Skill Testing Framework/CLAUDE.md	Updates catalog description to 56 agents.
CCGS Skill Testing Framework/catalog.yaml	Registers new Web agents in the framework catalog.
CCGS Skill Testing Framework/agents/engine/web/web-specialist.md	Adds behavioral spec for the Web primary engine specialist.
CCGS Skill Testing Framework/agents/engine/web/web-typescript-specialist.md	Adds behavioral spec for the Web TypeScript specialist.
CCGS Skill Testing Framework/agents/engine/web/pixi-specialist.md	Adds behavioral spec for the PixiJS specialist.
CCGS Skill Testing Framework/agents/engine/web/three-specialist.md	Adds behavioral spec for the Three.js specialist.
CCGS Skill Testing Framework/agents/engine/web/web-shader-specialist.md	Adds behavioral spec for the Web shader specialist.
CCGS Skill Testing Framework/agents/engine/web/web-ui-specialist.md	Adds behavioral spec for the Web UI specialist.
CCGS Skill Testing Framework/agents/engine/web/web-platform-specialist.md	Adds behavioral spec for the Web platform specialist.
.claude/agents/web-specialist.md	Adds the Web engine specialist agent definition.
.claude/agents/web-typescript-specialist.md	Adds the Web TypeScript specialist agent definition.
.claude/agents/pixi-specialist.md	Adds the PixiJS specialist agent definition.
.claude/agents/three-specialist.md	Adds the Three.js specialist agent definition.
.claude/agents/web-shader-specialist.md	Adds the Web shader specialist agent definition.
.claude/agents/web-ui-specialist.md	Adds the Web UI specialist agent definition.
.claude/agents/web-platform-specialist.md	Adds the Web platform specialist agent definition.
.claude/skills/setup-engine/SKILL.md	Extends engine selection to include Web, adds renderer-selection flow + Appendix B.
.claude/skills/test-setup/SKILL.md	Adds Web testing/CI setup guidance (Vitest + Playwright) and notes on SwiftShader/WebGPU CI.
.claude/skills/test-flakiness/SKILL.md	Adds web-specific flake sources and mitigation guidance.
.claude/skills/test-helpers/SKILL.md	Documents web test helper usage expectations (renderer-free helpers for Vitest).
.claude/skills/prototype/SKILL.md	Adds Web “path convergence” guidance (HTML path == engine path).
.claude/skills/dev-story/SKILL.md	Adds Web routing notes (import-based routing; first-match-wins).
.claude/skills/vertical-slice/SKILL.md	Adds Web slice guidance (URL distribution; load-time/mobile perf validation).
.claude/skills/localize/SKILL.md	Adds Web localization notes (JSON catalogs, Intl APIs, RTL via dir=rtl, font subsetting).
.claude/skills/brainstorm/SKILL.md	Adds Web as an engine preference option.
.claude/skills/architecture-review/SKILL.md	Adds Web-specific ADR consistency checks (per-library versions, renderer consistency, payload).
.claude/rules/engine-code.md	Adds Web-specific engine rules (GC pressure, explicit disposal, fixed timestep, headless simulation).
.claude/rules/ui-code.md	Adds Web UI rules (DOM-first, 100dvh, safe areas, pointer events, perf constraints).
.claude/rules/shader-code.md	Adds Web shader rules (WGSL+GLSL parity for Pixi filters; TSL for Three WebGPU; RenderPipeline name).
.claude/rules/prototype-code.md	Adds Web-specific warning about prototype/production convergence trap.
.claude/docs/rules-reference.md	Notes which rules have Web engine-specific sections and why there’s no web-code.md.
.claude/docs/quick-start.md	Updates agent count and supported engines list to include Web.
.claude/docs/coding-standards.md	Adds Web testing commands and SwiftShader caveat to CI expectations.
.claude/docs/agent-roster.md	Adds web-specialist + the web sub-specialist roster block.
.claude/docs/agent-coordination-map.md	Adds Web specialist hierarchy to the coordination diagram.
.claude/docs/templates/pitch-document.md	Adds Web as an engine option in the template.
.claude/docs/templates/game-concept.md	Adds Web as an engine option in the template.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.