Unsure? Proceed here. If we need a specialist, we'll delegate mid-workflow.
Core Workflow
1. Understand the Request
What problem are we solving? (user pain, crash, balance, performance)
What's the affected game system? (economy, progression, audio, UI, state)
What's the success metric? (no crashes, +X DPS, faster load time, clarity)
2. Research & Map Dependencies
State: Which reducers, actions, selectors are involved?
UI: Which components render the feature? Do they need updates?
Data: Which data files (upgrades.js, hqItems.js, events) are affected?
Audio: Does this touch AudioContext or Tone.js?
Pixi: Any scene rendering, animations, or dynamic assets?
Localization: User-facing text? Add i18n keys.
Tests: What should pass/fail after this change?
Use references/improvement-patterns.md to find a similar change.
3. Plan Implementation
Define:
Files to modify: List top 3-5 files.
Changes: Brief 1–2 sentence summary per file.
State mutations: Any new ActionTypes or reducer cases?
Tests to add/update: Which tests validate the fix?
Localization: New i18n keys needed?
4. Implement
State changes: Use ActionTypes, reducers, action creators (together, not separately).
UI changes: Follow Tailwind v4 syntax (@import "tailwindcss", color tokens with --color- prefix).
Localization: All user text via t('key'). Namespaced keys (ui:, events:, etc.). Both en and de.
Performance: Memoize expensive calcs, watch for per-frame allocations, destroy Pixi on unmount.
Pixi cleanup: Always use app.destroy({ removeView: true }, { children: true, texture: true, textureSource: true }).
See references/state-mutations.md, references/improvement-patterns.md, references/performance-guardrails.md.
5. Verify & Test
Run full test suite (takes ~3-5 min):
pnpm run test:all # lint + test + test:ui in sequence
Run targeted tests (faster, for iteration):
# node:test single-file logic tests
node --test --import tsx --experimental-test-module-mocks --import ./tests/setup.mjs tests/path/to/file.test.js
# Vitest/UI single-file tests
pnpm run test:ui:file -- tests/path/to/file.test.jsx
# Fast local suite
pnpm run test
pnpm run lint && pnpm run test && pnpm run test:ui && pnpm run build
See references/verification-checklist.md for detailed criteria.
Core Constraints
Stack: React 19.2.6, Vite 8.0.10, Tailwind 4.2.4, Framer Motion 12.38.0, Tone.js 15.5.11. Node 22.13+.
State Limits: player.money >= 0, band.harmony ∈ [1, 100], van.fuel ∈ [0, 100]. Clamp via gameStateUtils.js.
Audio: Use audioEngine.getGigTimeMs() as single clock. Don't access Tone.js directly. Handle suspended AudioContext.
Pixi: Destroy on unmount. No memory leaks. Pre-compute, don't allocate per-frame.
I18n: ALL user text via t('key'). Namespaced (ui:, events:, etc.). Both en and de.
Commits: Conventional Commits (feat:, fix:, refactor:, etc.).
