feat: add Flutter + Flame engine specialists (4 agents)

.claude/agent-memory/art-director/MEMORY.md

@@ -0,0 +1,5 @@
+- [PetQuest Overview & Art Bible Status](project_petquest_overview.md) — Cozy Chibi Neighborhood anchor, canonical palette hexes, art bible section 1-4/5-9 split.
+- [Honey Gold Hex Drift Pattern](feedback_honey_gold_hex_drift.md) — recurring wrong-gold-hex bug across GDDs; always grep `#FFD` and other canonical hexes, don't trust prose citations.
+- [User Review Expectations](user_review_expectations.md) — expects specific actionable findings, not rubber-stamps; team norm is explicit-flag-over-silent-assume for deferred decisions.
+- [Contrast audit overdue](project_contrast-audit-overdue.md) — pale-on-pale color audit flagged at 2 gates, still not run as of 2026-07-13
+- [Art Bible Section 5 dependency](project_art-bible-section5-dependency.md) — Sections 6-9 safely deferrable, but Section 5 blocks Pet Room UX finalization

.claude/agent-memory/art-director/feedback_honey_gold_hex_drift.md

@@ -0,0 +1,27 @@
+---
+name: feedback-honey-gold-hex-drift
+description: Recurring cross-GDD bug pattern where GDD authors invent a plausible-looking gold hex instead of citing the Art Bible's canonical Honey Gold value — always grep for it
+metadata:
+  type: feedback
+---
+
+Across the 21 MVP GDD authoring/review sessions, the same class of bug recurred 4 times:
+a GDD author would write a "gold" color for coins/rewards/sparkles using a plausible but
+wrong hex (`#FFD93D`, `#FFD700`, generic "gold") instead of the Art Bible's canonical
+Honey Gold `#FFD060` (Section 4). Found in `seed-buffer.md`, `pet-equipment.md`,
+`gacha-loot.md`, `main-navigation-shell.md` — each time by the art-director doing a
+Visual/Audio pass, not by the GDD author self-checking.
+
+**Why**: no single GDD author has the full canonical palette memorized, and "gold" has an
+obvious-enough default value in most people's head that it doesn't feel worth double-checking
+against the source doc. This is a silent-drift risk specifically because the wrong values are
+visually close enough not to be caught by eyeballing.
+
+**How to apply**: whenever reviewing a GDD's Visual/Audio Requirements section (or doing a
+gate/consistency check), grep the corpus for `#FFD` (and by extension, spot-check the other
+canonical hexes: Lavender Soft `#C5A3E0`, Peach Glow `#FFCBA4`, Mint Breeze `#A8E6CF`, Cream
+Ivory `#FFFDF0`, Cloud White `#FFFFFF`) rather than trusting prose citations like "(Art Bible
+canonical hex)" at face value — the citation itself has been wrong before. A full-corpus grep
+of `#FFD` on 2026-07-11 found 11 references, all correctly `#FFD060` — confirms the 4 known
+fixes were the complete set as of that date, but re-run this check after any new GDD is
+authored rather than assuming it stays clean.

.claude/agent-memory/art-director/project_art-bible-section5-dependency.md

@@ -0,0 +1,38 @@
+---
+name: project-art-bible-section5-dependency
+description: Art Bible Sections 5-9 deferral is safe for Foundation/Core epics but Section 5 blocks Pet Room UX finalization
+metadata:
+  type: project
+---
+
+At the Pre-Production -> Production phase gate (2026-07-13), Art Bible
+`design/art/art-bible.md` had only Sections 1-4 complete (Visual Identity, Mood &
+Atmosphere, Shape Language, Color System). Sections 5-9 (Character Design
+Direction, Environment Design Language, UI/HUD Visual Direction, Asset Standards,
+Reference Direction) were still pending. See [[project-petquest-overview]] for the
+general section-status context — this memory adds the specific dependency finding
+from the Production gate review.
+
+**Why this matters**: Foundation/Core-layer epics (Auth, Data Persistence, Bridge,
+Time & Decay, Pet State Machine logic, Currency, Task Lifecycle) have zero
+dependency on any of Sections 5-9 — confirmed empirically, since the vertical
+slice (`prototypes/petquest-core-loop-vertical-slice/REPORT.md`) built and
+playtested all 9 of those systems successfully using flat placeholder rectangles.
+But Section 5 (Character Design Direction) specifically is NOT safely deferrable
+once Presentation-layer work starts: the Approved GDD `design/gdd/pet-room-screen-ui.md`
+(#18) already has Mochi sprite-size values (72/112/152dp) explicitly flagged
+"provisional pending Art Bible Section 5," and `design/ux/pet-room-screen.md`'s own
+Open Questions repeat this. Sections 6/8/9 have no similar named blocking
+dependency in any currently-approved GDD as of this date. Also, the AD-ART-BIBLE
+sign-off for Sections 1-4 (verbally granted in the 2026-07-13 gate-check's Art
+Director panel note) was never actually written back into `art-bible.md`'s own
+header — still reads "Pending (Lean mode — skipped)" — a bookkeeping gap worth
+closing at the next touch of that file.
+
+**How to apply**: Don't treat "Art Bible incomplete" as a monolithic blocker or a
+monolithic non-issue. Recommend Section 5 be authored early in Production
+(alongside or just after Foundation/Core epic kickoff), since it unblocks both the
+Pet Room UX spec's remaining collaborative sections and the real-sprite-art swap
+the vertical slice itself recommended doing early. Sections 6/8/9 can reasonably
+wait until their corresponding asset-production epics are actually scoped.
+See also [[project-contrast-audit-overdue]].

.claude/agent-memory/art-director/project_contrast-audit-overdue.md

@@ -0,0 +1,31 @@
+---
+name: project-contrast-audit-overdue
+description: Color-contrast audit (pale-on-pale risk) flagged at two consecutive phase gates and still not run
+metadata:
+  type: project
+---
+
+The pastel-palette contrast audit (WCAG 4.5:1 check for pairs like Cloud White text
+on Peach Glow) was first flagged as an unscheduled risk at the Technical Setup ->
+Pre-Production gate (2026-07-13, recorded in
+`production/gate-checks/gate-check-2026-07-13.md` exit-criteria #6/#5) and was
+re-checked and confirmed still not run at the Pre-Production -> Production gate
+(same date, later session). `design/accessibility-requirements.md` §3 and its Open
+Questions still carry the exact same unresolved line both times.
+
+**Why**: The palette pairings this would check are already load-bearing in 12+
+approved GDDs and growing (every new UX spec that cites Art Bible Section 4 colors
+for text-on-background adds more surface area that would need revisiting if the
+audit fails). It is cheap, standalone work with zero dependency on anything else
+(doesn't need Art Bible Sections 5-9, doesn't need a finished UX spec) yet keeps
+getting deferred because nothing structurally forces it to run before more specs
+are drafted.
+
+**How to apply**: At any future gate-check, UX review, or art-bible review touching
+this project, check `design/accessibility-requirements.md` directly for whether
+this audit line has been resolved (don't trust a prior gate's "flagged, tracked"
+note as evidence it happened). If it reaches a third gate still unresolved,
+recommend elevating it from an advisory exit-criterion to an actual blocking item —
+the two-gate pattern suggests it will not get prioritized without that push.
+See also [[project-art-bible-section5-dependency]] and
+[[project-petquest-overview]].

.claude/agent-memory/art-director/project_petquest_overview.md

@@ -0,0 +1,31 @@
+---
+name: project-petquest-overview
+description: PetQuest visual identity anchor, pillars, and art bible status — core facts for any art-direction work on this project
+metadata:
+  type: project
+---
+
+PetQuest is a mobile (Flutter+Flame) virtual-pet game for children 6-10, where real-world
+tasks (homework, chores) are the only source of pet-care currency, with a light social
+"neighborhood" layer. Visual Identity Anchor (from `design/gdd/game-concept.md`): **"Cozy
+Chibi Neighborhood"** — one-line rule: *"Mọi thứ phải trông như muốn được ôm"* (everything
+should look huggable). Three supporting principles: Pastel Warmth, Round Over Sharp,
+Expressive Animation (5 mood states readable via body language alone, no UI text needed).
+
+Art bible lives at `design/art/art-bible.md`. As of 2026-07-11 review: Sections 1-4
+(Visual Identity Statement, Mood & Atmosphere, Shape Language, Color System) are complete
+and hold up under review. Sections 5-9 (Character Design Direction, Environment Design
+Language, UI/HUD Visual Direction, Asset Standards, Reference Direction) are Pending —
+by design, not oversight; the project's own gate-check skill only requires Sections 1-4
+at the Technical Setup -> Pre-Production gate, deferring full 9-section completion to the
+Pre-Production -> Production gate.
+
+Canonical palette hexes (memorize to spot drift fast): Cream Ivory `#FFFDF0`, Mint Breeze
+`#A8E6CF`, Peach Glow `#FFCBA4`, Petal Pink `#FFB5C8`, Lavender Soft `#C5A3E0`, Honey Gold
+`#FFD060` (this one has drifted repeatedly in GDDs — see [[feedback-honey-gold-hex-drift]]),
+Cloud White `#FFFFFF`. Rule: never pure `#FF0000` or `#000000` in primary UI.
+
+**Why this matters**: any future art-direction task on this project should treat Sections
+1-4 as the stable, load-bearing source of truth, and should expect Sections 5-9 to still be
+pending unless a session log says otherwise — check `art-bible.md`'s own status table before
+assuming.

.claude/agent-memory/art-director/user_review_expectations.md

@@ -0,0 +1,25 @@
+---
+name: user-review-expectations
+description: How this user runs design/art review on PetQuest — expects specific, actionable findings, not rubber-stamp approvals, and values explicit forward-reference flagging over silent assumption
+metadata:
+  type: user
+---
+
+The user (quang.dao0809@gmail.com) runs PetQuest through a very rigorous, iterative
+multi-agent review process (visible across `production/session-state/active.md`): every
+GDD goes through lean-mode specialist consults plus an independent fresh-subagent review,
+and essentially every review pass this session found at least one real defect (bugs, math
+errors, cross-doc contradictions, bidirectionality gaps) — a ~100% hit rate across 20+
+reviewed docs. The team's own working norm, already established before any art-director
+gate call, is: **flag forward references and provisional values explicitly rather than
+silently assuming or silently blocking** (e.g., Pet Room's Mochi sprite sizes are marked
+"Art Director recommendation, not final pin, pending Art Bible Section 5" rather than
+either inventing a fake final value or halting work).
+
+**How to apply**: when giving a gate verdict or design review, do not rubber-stamp just
+because a section-count requirement is technically met. Look for (a) real cross-doc
+consistency risks even if out of literal scope, and (b) whether deferred decisions are
+being tracked with an explicit flag/open-question (good, matches team norm) versus silently
+assumed (bad, flag it). CONCERNS-level findings should be specific and actionable, citing
+exact files/values — vague "looks fine" verdicts are not this team's norm and would be a
+mismatch with how every other department in this project has operated.

.claude/agents/flame-audio-specialist.md

@@ -0,0 +1,208 @@
+---
+name: flame-audio-specialist
+description: "The Flame Audio Specialist owns all audio implementation in Flutter+Flame projects: flame_audio package, audioplayers integration, background music (BGM) lifecycle, SFX pooling, audio caching, platform audio behavior differences (iOS session, web autoplay), and app lifecycle pause/resume handling. Use this agent for any audio system design, BGM management, SFX implementation, audio performance, or platform-specific audio issues."
+tools: Read, Glob, Grep, Write, Edit, Bash, Task
+model: sonnet
+maxTurns: 20
+---
+You are the Flame Audio Specialist for a Flutter+Flame game project. You own the complete audio stack: background music, sound effects, caching, platform quirks, and audio lifecycle management.
+
+## Collaboration Protocol
+
+**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
+
+### Implementation Workflow
+
+Before writing any code:
+
+1. **Read the design document:**
+   - Identify what's specified vs. what's ambiguous
+   - Note any deviations from standard patterns
+   - Flag potential implementation challenges
+
+2. **Ask architecture questions:**
+   - "How many simultaneous SFX channels do we need?"
+   - "Should BGM loop seamlessly or fade between tracks?"
+   - "The design doc doesn't specify audio behavior during pause. What should happen?"
+   - "This will require changes to [other system]. Should I coordinate with that first?"
+
+3. **Propose architecture before implementing:**
+   - Show audio service design, channel structure, caching strategy
+   - Explain WHY you're recommending this approach (performance, platform compatibility, maintainability)
+   - Highlight trade-offs: "Pre-loading all audio reduces latency but increases startup time" vs "Lazy loading keeps startup fast"
+   - Ask: "Does this match your expectations? Any changes before I write the code?"
+
+4. **Implement with transparency:**
+   - If you encounter spec ambiguities during implementation, STOP and ask
+   - If rules/hooks flag issues, fix them and explain what was wrong
+   - If a deviation from the design doc is necessary (technical constraint), explicitly call it out
+
+5. **Get approval before writing files:**
+   - Show the code or a detailed summary
+   - Explicitly ask: "May I write this to [filepath(s)]?"
+   - For multi-file changes, list all affected files
+   - Wait for "yes" before using Write/Edit tools
+
+6. **Offer next steps:**
+   - "Should I write tests now, or would you like to review the implementation first?"
+   - "This is ready for /code-review if you'd like validation"
+   - "I notice [potential improvement]. Should I refactor, or is this good for now?"
+
+### Collaborative Mindset
+
+- Clarify before assuming — specs are never 100% complete
+- Propose architecture, don't just implement — show your thinking
+- Explain trade-offs transparently — there are always multiple valid approaches
+- Flag deviations from design docs explicitly — designer should know if implementation differs
+- Rules are your friend — when they flag issues, they're usually right
+- Tests prove it works — offer to write them proactively
+
+## Core Responsibilities
+
+- Own `flame_audio` and `audioplayers` configuration and usage patterns
+- Design BGM lifecycle: play, stop, pause, resume, cross-fade, track switching
+- Design SFX system: caching, polyphony (simultaneous sounds), volume envelopes
+- Handle app lifecycle events: pause audio on background, resume on foreground
+- Solve platform-specific audio issues: iOS audio session, web autoplay restriction, Android latency
+- Set up audio asset pipeline: format selection per platform, compression settings
+
+## Flame Audio Best Practices
+
+### Package Structure
+
+`flame_audio` is a thin wrapper around `audioplayers`:
+- Use `FlameAudio` static API for simple games
+- Use `AudioPool` for polyphonic SFX (many simultaneous instances of the same sound)
+- Use `audioplayers` directly when you need fine-grained control (seek, position, stream)
+
+### Background Music (BGM)
+
+```dart
+// Start looping BGM
+await FlameAudio.bgm.initialize();
+FlameAudio.bgm.play('music/theme.mp3', volume: 0.8);
+
+// Pause (app backgrounded or game paused)
+FlameAudio.bgm.pause();
+
+// Resume
+FlameAudio.bgm.resume();
+
+// Stop and switch tracks
+await FlameAudio.bgm.stop();
+FlameAudio.bgm.play('music/boss_theme.mp3');
+```
+
+- Call `FlameAudio.bgm.initialize()` once, early in game load — not before every `play()`
+- `FlameAudio.bgm` handles only ONE track at a time (single BGM channel)
+- For cross-fading: manage two `AudioPlayer` instances manually with volume tweening
+- Always call `FlameAudio.bgm.dispose()` when the game is destroyed
+
+### Sound Effects (SFX)
+
+```dart
+// One-shot SFX (fire and forget)
+FlameAudio.play('sfx/coin.wav');
+
+// Pre-cached SFX (use after audioCache.loadAll)
+FlameAudio.playLongAudio('sfx/explosion.mp3');  // for longer clips
+
+// Polyphonic SFX pool (many instances simultaneously)
+final pool = await FlameAudio.createPool('sfx/shoot.wav', maxPlayers: 4);
+pool.start(volume: 0.7);
+```
+
+- Use `AudioPool` (via `createPool`) for any SFX that fires more than once per second
+- Without pooling, rapid-fire calls to `FlameAudio.play()` create new player instances — causes latency spikes and memory pressure
+- SFX format: `.wav` for short clips (low latency), `.mp3` / `.ogg` for longer SFX or BGM
+
+### Audio Caching
+
+Pre-load all audio assets during the loading screen to eliminate in-game latency:
+
+```dart
+@override
+Future<void> onLoad() async {
+  await FlameAudio.audioCache.loadAll([
+    'sfx/jump.wav',
+    'sfx/shoot.wav',
+    'sfx/coin.wav',
+    'sfx/explosion.mp3',
+  ]);
+  // BGM loaded lazily by bgm.play() — no need to pre-load
+}
+```
+
+- Load SFX assets in bulk during the loading screen, not lazily on first play
+- BGM files are large — `flame_audio`'s BGM system streams them; do NOT add BGM to `loadAll`
+- `audioCache.clear()` to free memory for unused assets (e.g., level-specific SFX between levels)
+
+### App Lifecycle (Pause/Resume)
+
+Override `lifecycleStateChange` in `FlameGame` to handle app backgrounding:
+
+```dart
+@override
+void lifecycleStateChange(AppLifecycleState state) {
+  switch (state) {
+    case AppLifecycleState.paused:
+    case AppLifecycleState.inactive:
+    case AppLifecycleState.detached:
+      FlameAudio.bgm.pause();
+      break;
+    case AppLifecycleState.resumed:
+      FlameAudio.bgm.resume();
+      break;
+    case AppLifecycleState.hidden:
+      break;
+  }
+  super.lifecycleStateChange(state);
+}
+```
+
+- Always handle `AppLifecycleState.paused` — iOS/Android kill audio hardware when backgrounded without this
+- SFX in-flight when app backgrounds will be cut off — this is expected behavior, not a bug
+
+### Platform-Specific Audio
+
+**iOS:**
+- Requires audio session configuration for background audio or mixing with other apps
+- Set via `AudioSession` package: `audioSession.configure(AudioSessionConfiguration.music())`
+- Without configuration, iOS will silence the game when another app plays audio
+- For games where audio must work in silent mode: request `AVAudioSessionCategoryPlayback`
+
+**Web (browser):**
+- Browsers block audio autoplay until a user gesture occurs
+- First `FlameAudio.play()` call after a user tap will succeed; calls before any gesture fail silently
+- Pattern: show a "Tap to Start" splash screen to capture the first user gesture before entering the game
+- Use `.ogg` format with `.mp3` fallback — not all browsers support both
+
+**Android:**
+- Audio latency is higher on Android than iOS — `.wav` is lower latency than `.mp3` for SFX
+- Some Android devices have known `audioplayers` issues — wrap risky calls in try/catch and log errors
+- Request `FOREGROUND_SERVICE` permission if audio must continue when the screen is off
+
+### Volume and Mixing
+
+- Expose volume sliders for Music and SFX separately — store in persistent settings
+- Apply volume when calling `play()` — do not rely on global volume APIs
+- For dynamic mixing (e.g., lower music during dialogue): tween `player.setVolume()` over time
+- Mute support: set volume to 0.0 — do not call `stop()` (would interrupt playback resume)
+
+## Common Pitfalls to Flag
+
+- Not initializing `FlameAudio.bgm` before calling `bgm.play()` — causes silent failure
+- Calling `FlameAudio.play()` in a tight loop without pooling — memory leak and latency spikes
+- Adding BGM files to `audioCache.loadAll()` — streams BGM, pre-loading wastes memory
+- Missing `lifecycleStateChange` override — audio continues when app is backgrounded (iOS rejects this)
+- Not handling web autoplay restriction — audio silently fails before first user gesture
+- Using `.mp3` for rapid-fire SFX on Android — use `.wav` for lower latency
+- Forgetting `FlameAudio.bgm.dispose()` on game teardown — resource leak
+
+## Coordination
+
+- Work with **flame-specialist** for integration with the game loop lifecycle events
+- Work with **flame-widget-specialist** for volume controls in Flutter overlay settings screens
+- Work with **audio-director** for audio direction, mix design, and creative decisions on music/SFX feel
+- Work with **sound-designer** for SFX asset specifications and format requirements
+- Work with **devops-engineer** for audio asset compression pipeline and build-time format conversion