Skip to content

feat: HTML5 / PixiJS engine family (4th engine support)#79

Open
gentlius wants to merge 1 commit into
Donchitos:mainfrom
gentlius:pr/html5-pixijs-engine-family
Open

feat: HTML5 / PixiJS engine family (4th engine support)#79
gentlius wants to merge 1 commit into
Donchitos:mainfrom
gentlius:pr/html5-pixijs-engine-family

Conversation

@gentlius

Copy link
Copy Markdown

Summary

Adds HTML5 / PixiJS as the 4th engine family supported by the studio template. Brings agent count from 49 → 54 and ships a complete engine-reference doc set for browser game development.

Production-validated in BagelMVP (POP! — a Pang-style HTML5 mobile web game). Stack: PixiJS 8 + TypeScript 5 + Vite 5 + Vitest + Playwright 1.40. Agents authored design docs, reviewed code, and supported the production pipeline before promotion.

Type of Change

  • New agent
  • New skill
  • New hook or rule
  • Bug fix
  • Documentation improvement
  • Other: New engine family (5 agents + engine-reference doc set + setup-engine skill extension)

Changes

5 specialist agents (.claude/agents/):

  • html5-specialist — primary (browser APIs, platform architecture: PWA / SPA / Capacitor, distribution: itch.io / PWA / wrapped native)
  • pixijs-specialist — PixiJS 8 scene graph, Assets, Filters, Ticker, ParticleContainer, Federated events; also owns TypeScript code quality (per paired ADR-0001)
  • web-build-specialist — Vite, bundle budgets, asset pipeline, PWA, CI
  • webgl-shader-specialist — Custom GLSL filters, WebGL2/WebGPU dual-target
  • playwright-e2e-specialist — Browser e2e, mobile device emulation, viewport/touch simulation, screenshot regression

Engine reference doc set (docs/engine-reference/html5/):

  • VERSION.md, PLUGINS.md, breaking-changes.md, deprecated-apis.md, current-best-practices.md
  • 9 module docs: rendering, physics, audio, input, ui, animation, navigation, networking, build
  • Total ~2,900 lines. PixiJS v8 redesign is far beyond model training cutoffs — these docs prevent v7-era anti-patterns (new Application({...}), interactive: true, .beginFill().endFill())

setup-engine skill extension (.claude/skills/setup-engine/SKILL.md):

  • HTML5 added as a 4th option in Question 1 and the engine recommendation matrix
  • Platform/genre rules updated for mobile-web, hypercasual, .io games, playable ads, idle clickers
  • Appendix B: HTML5 Tech Stack templates (TypeScript / Vanilla JS), naming conventions, specialist routing, performance budgets, forbidden patterns

Reference doc updates:

  • .claude/docs/agent-roster.md — adds HTML5 to Engine Leads + new "HTML5 / Web Sub-Specialists" subsection
  • .claude/docs/agent-coordination-map.md — adds HTML5 specialist tree under Engine Specialists block
  • docs/engine-reference/README.md — "Supported Engine Families" table + note that html5/ tracks a combined runtime (browser + Pixi + Vite + Playwright)
  • docs/CLAUDE.md — generalizes engine-ref pointer from godot-only to multi-engine aware

README.md:

  • 49 → 54 agent counts
  • Engine table extended with 4th row
  • Drive-by fix: existing Godot row was missing C# (godot-csharp-specialist exists but wasn't listed)

Architectural decision

This PR absorbs TypeScript code quality into pixijs-specialist rather than adding a separate typescript-specialist agent. The reasoning is formalized in the paired PR (ADR-0001: Engine Specialist Separation Policy). Mechanical application: HTML5 has one language identity per project (TS OR Vanilla JS, picked at setup) — same as Unity's single-language situation → absorb.

If ADR PR is rejected/deferred, the absorption decision stands on its own (single language → single specialist).

Checklist

  • I've tested this in a Claude Code session — production-validated in BagelMVP (POP! game)
  • New agents include the Collaboration Protocol section — verified on all 5 new agents
  • New skills use the subdirectory format (.claude/skills/<name>/SKILL.md) — N/A (no new skill; setup-engine extended)
  • Reference docs are updated (agent-roster, skills-reference, hooks-reference, rules-reference) — agent-roster.md + agent-coordination-map.md updated. skills-reference unchanged (no new skill). hooks/rules N/A.
  • Hooks use grep -E (POSIX) and fail gracefully without jq/python — N/A (no hooks)
  • No hardcoded paths or platform-specific assumptions

Notes

Paired with PR ADR-0001: Engine Specialist Separation Policy (separate PR). Reviewable independently, but ADR provides the rationale for the TypeScript absorption choice.

Production-validated in BagelMVP (POP! — Pang-style HTML5 mobile web game,
PixiJS 8 + TypeScript 5 + Vite 5 + Vitest + Playwright 1.40).

## Adds

**5 specialist agents** (.claude/agents/):
- html5-specialist (primary; browser API, platform architecture)
- pixijs-specialist (PixiJS 8 scene graph + TypeScript quality)
- web-build-specialist (Vite, bundle budgets, PWA, CI)
- webgl-shader-specialist (GLSL filters, WebGL2/WebGPU dual-target)
- playwright-e2e-specialist (browser e2e, mobile emulation, screenshot regression)

**Engine reference doc set** (docs/engine-reference/html5/):
- VERSION.md, PLUGINS.md, breaking-changes.md, deprecated-apis.md,
  current-best-practices.md
- modules/: rendering, physics, audio, input, ui, animation, navigation,
  networking, build

**setup-engine skill extension** (.claude/skills/setup-engine/SKILL.md):
- HTML5 added to Question 1 (prior experience) and engine recommendation matrix
- Genre/platform rules updated (mobile-web, hypercasual, .io, playable ads)
- Appendix B: HTML5 Tech Stack templates (TS / Vanilla JS), naming
  conventions, specialist routing, performance budgets, forbidden patterns

## Modifies

- README.md: 49→54 agent counts, engine table extended (4th row); also
  corrects Godot row (was missing C# sub-specialist).
- docs/engine-reference/README.md: Supported Engine Families table,
  notes that html5/ tracks a combined runtime (browser + Pixi + Vite +
  Playwright) rather than a single product.
- docs/CLAUDE.md: Generalize engine-ref pointer from godot-only to
  multi-engine (collateral improvement enabling 4-engine awareness).

## Policy

TypeScript code quality is absorbed into pixijs-specialist (no separate
typescript-specialist agent) per ADR-0001 (paired PR — Engine Specialist
Separation Policy). Same rationale as Unity (single language) vs Godot
(two co-existing languages need separate specialists).

## Excluded from PR (fork-only)

- tools/verify_html5_extension.py (internal verification script)
- .claude/settings.json cleanup (fork-specific Bash permissions)
- README "Forked from..." slogan

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@gentlius gentlius requested a review from Donchitos as a code owner June 11, 2026 03:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant