@shaykec/app-agent 1.0.9 → 1.0.11

package/.claude/agents/catalog-analyzer.md

@@ -0,0 +1,57 @@
+---
+name: catalog-analyzer
+description: Selects the best template from CATALOG.md and shared modules from MODULES_CATALOG.md in one pass. Uses selected template to boost module accuracy via "Relevant Templates" column.
+tools: Read, Grep, Glob, LS
+model: haiku
+permissionMode: plan
+---
+
+You are a specialised subagent for selecting the best mobile app template AND shared modules.
+
+## Instructions
+
+### Phase 1 — Template Selection
+
+1. Read `templates/CATALOG.md` thoroughly
+2. Evaluate each template: score against keywords, check match criteria, apply exclusion rules, check hybrid table
+3. Choose exactly ONE primary template
+
+### Phase 2 — Module Selection
+
+4. Read `templates/shared/MODULES_CATALOG.md`
+5. Match by keywords + check "Relevant Templates" against selected template (boost signal)
+6. Apply BaaS heuristics (Firebase vs Supabase vs none)
+7. Check dependencies, add missing ones
+8. Apply animation heuristics if needed
+9. Aim for 5-15 modules
+
+## Output Format
+
+```
+SELECTED TEMPLATE: {TemplateName}
+CONFIDENCE: high | medium | low
+REASONING: {1-2 sentence explanation}
+BORROW FROM: {other template name, if hybrid} or "none"
+HYBRID NOTES: {what to borrow and why} or "n/a"
+
+SELECTED MODULES ({N} total):
+- {ModuleName}: {reason} [template boost: yes/no]
+- ...
+
+EXCLUDED MODULES:
+- {ModuleName}: {reason for exclusion}
+- ...
+
+DEPENDENCIES ADDED:
+- {ModuleName}: required by {other module}
+- ...
+```
+
+## Rules
+
+- Always recommend exactly ONE primary template
+- Do NOT recommend building from scratch
+- Features covered by modules don't affect template scoring
+- No auto-include — every module must match via keywords
+- "Relevant Templates" is a boost, not a hard filter
+- Aim for 5-15 modules

package/.claude/skills/android-customizer/SKILL.md

@@ -102,7 +102,19 @@ Android templates use Material 3 dynamic theming in `Theme.kt`:
 - Apply typography scale if the design brief specifies custom fonts
 - Apply shape theme (corner radius) from the design brief
 
-### Step 5.5 — Generate App Launcher Icon
+### Step 5.5 — Visual Polish Application
+
+Apply the **Visual Polish Plan** from the manifest. MANDATORY for every build.
+
+1. **Shadows/Elevation**: `Card(elevation = CardDefaults.cardElevation(defaultElevation = 4.dp))` on all cards. 8dp for FABs.
+2. **Gradients**: `Brush.linearGradient(listOf(Primary, Secondary))` on hero sections and CTAs.
+3. **Press feedback**: `Modifier.scaleOnPress()` or clickable scale animation (0.95). Haptic via `HapticFeedbackConstants.CONFIRM`.
+4. **Staggered animations**: `Modifier.staggeredAppear(index)` on all LazyColumn/LazyRow items.
+5. **Empty states**: Gradient circle behind icon + slide-in animation.
+6. **Material surfaces**: `Surface(tonalElevation)` for sheets and overlays.
+7. **Haptic**: `performHapticFeedback()` on favorite toggles and primary actions.
+
+### Step 5.6 — Generate App Launcher Icon
 
 Customize the adaptive icon using the manifest's **App Launcher Icon** section:
 
@@ -223,16 +235,17 @@ If the customization manifest includes an **"Animation & Sensory Plan"** section
 2. For each screen in your batch, apply the assigned modifiers:
 
 ```kotlin
-// MicroInteractions — press feedback
-Button(onClick = { }, modifier = Modifier.scaleOnPress().hapticFeedback(HapticFeedbackStyle.IMPACT_MEDIUM))
-
-// ScrollEffects — parallax header
+// Built-in (always available)
+Button(onClick = { }, modifier = Modifier.scaleOnPress()) { Text("Add") }
+ItemRow(item = item, modifier = Modifier.staggeredAppear(index = index))
+Card(modifier = Modifier.cardShadow()) { /* content */ }
+EmptyState(modifier = Modifier.slideIn())
+Box(modifier = Modifier.fillMaxWidth().height(60.dp).shimmer()) // loading placeholder
+Box(modifier = Modifier.size(8.dp).pulse()) // live indicator
+Icon(icon, modifier = Modifier.heartBounce(isActive = isFavorite)) // favorite toggle
+
+// Modules (if integrated)
 ParallaxHeader(height = 280.dp, scrollState = scrollState) { AsyncImage(model = item.imageUrl) }
-
-// AnimatedTransitions — staggered list items
-ItemRow(item = item, modifier = Modifier.staggeredAppearance(index = index))
-
-// CelebrationEffects — success overlay
 Box(modifier = Modifier.celebrationOverlay(isActive = showCelebration, style = CelebrationStyle.CONFETTI))
 ```
 

package/.claude/skills/bug-fixer/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: bug-fixer
+description: Reads a bug report and systematically fixes each bug. Rebuilds, re-tests fixed screens, produces a fix report.
+allowed-tools: Read, Write, Grep, Glob, LS, Shell, inspect, act, assert, wait, device
+context: fork
+---
+
+# Bug Fixer Skill
+
+Fix bugs from `reports/11-bug-report.md`. Read the report, fix each bug, rebuild, verify.
+
+## Instructions
+
+### Step 1 — Read and Prioritize
+
+Read `output/{app-name}/reports/11-bug-report.md`. Sort by severity (P0→P3). Triage:
+- **FIX** — fixable in source code
+- **DEFER** — needs major refactoring (document recommendation)
+- **SKIP** — false positive
+
+### Step 2 — Locate Source Files
+
+- `[STRUCTURED]` bugs: file path in bug report or test plan
+- `[EXPLORATORY]` bugs: find `{ScreenName}View.swift` / `{ScreenName}Screen.kt` / `{ScreenName}Screen.tsx`
+- `[A11Y]` bugs: open View file, add accessibility modifiers
+- Content bugs: check AppConfig, MockDataProvider, strings
+
+### Step 3 — Fix Each Bug (priority order)
+
+**Fix patterns:**
+- `[VISUAL]`: lineLimit, frame, padding, spacing, ZStack ordering
+- `[A11Y]`: `.accessibilityLabel()`, `contentDescription`, increase touch targets
+- `[UX]`: fix action handler, navigation call, target
+- `[CONTENT]`: replace leftover text, update AppConfig/MockDataProvider
+- `[STATE]`: fix ViewModel save call, check binding, update provider
+- `[CRASH]`: add nil checks, bounds checking, optional binding
+
+### Step 4 — Rebuild
+
+Follow `build-tester` skill. Max 3 rebuild cycles.
+
+### Step 5 — Verify Fixes
+
+Boot simulator, install, launch. For each fixed bug: navigate to screen, verify fix, check no regressions.
+
+### Step 6 — Write Fix Report
+
+Write `output/{app-name}/reports/12-fix-report.md`: summary counts, per-bug fix details (root cause, fix, files, verified), deferred bugs with recommendations, rebuild/verification results.
+
+Update `summary.json` with step 12 entry.
+
+## Rules
+
+- Fix P0 first, P3 last
+- Minimal changes — don't refactor unrelated code
+- Preserve MVVM architecture and MockDataProvider pattern
+- Max 3 rebuild cycles
+- Only write under `output/`
+- DEFER bugs requiring new dependencies or >50 lines across >3 files

package/.claude/skills/catalog-analyzer/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: catalog-analyzer
+description: Selects the best template from CATALOG.md and shared modules from MODULES_CATALOG.md in one pass. Uses selected template to boost module accuracy via "Relevant Templates" column.
+allowed-tools: Read, Grep, Glob, LS
+context: fork
+agent: Explore
+---
+
+# Catalog Analyzer Skill
+
+Select the best template AND shared modules for the user's app in one pass.
+
+## When to Use
+
+- Step 0, in parallel with prompt validation and design brand selection
+- Before cloning any template to `output/`
+
+## Instructions
+
+### Phase 1 — Template Selection
+
+#### Step 1 — Read the Template Catalog
+
+Read `templates/CATALOG.md`. Understand each template's feature set, "Best-For Keywords", "Best match when" criteria, and "NOT a match when" rules.
+
+#### Step 2 — Score Each Template
+
+For each template: score against user description keywords, check match criteria, apply exclusion rules, consider navigation pattern similarity.
+
+#### Step 3 — Handle Edge Cases
+
+Check the "Hybrid Apps" table if the app spans categories. Follow "When No Template Fits" guidance if needed.
+
+#### Step 4 — Select ONE Template
+
+Choose exactly ONE primary template. Determine confidence (high/medium/low). Features covered by shared modules should NOT affect template scoring.
+
+### Phase 2 — Module Selection (uses template from Phase 1)
+
+#### Step 5 — Read Modules Catalog
+
+Read `templates/shared/MODULES_CATALOG.md`. Note each module's keywords, relevant templates, and dependencies.
+
+#### Step 6 — Match by Keywords + Relevant Templates
+
+For every module:
+1. Compare "Best-For Keywords" against user description (primary signal)
+2. Check if selected template is in "Relevant Templates" column (boost signal)
+3. Keyword match + template match = strong include
+4. Keyword match + no template match = include with lower confidence
+5. No keyword match + template match = consider if implied by domain
+
+**Guidance:** Aim for **5-15 modules**. Consider implicit needs (shopping → payment, social → sharing).
+
+**BaaS selection:** FirebaseProvider OR SupabaseProvider (not both) when description mentions auth/users/cloud/sync/backend. Default: no BaaS. Supabase needs CachedRepository; Firebase does not. Prefer Firebase when both fit equally.
+
+#### Step 7 — Check Dependencies
+
+Verify dependencies (Paywall→BiometricAuth, AccountDeletion→ConsentPrivacy, PushNotifications→ConsentPrivacy, etc.). Add missing ones.
+
+#### Step 8 — Animation Heuristics
+
+For "stunning/beautiful/premium/polished" descriptions, consider MicroInteractions, AnimatedTransitions, CelebrationEffects, HapticEngine, etc. Auto-include MotionPreferences when any animation module is selected.
+
+#### Step 9 — Final List
+
+Produce selected modules with reasoning.
+
+## Report Output
+
+Write `output/{app-name}/reports/02-catalog-analysis.md` with both template selection and module selection sections. Update `summary.json`:
+
+```json
+{
+  "step": 0,
+  "name": "catalog-analysis",
+  "result": "PASS",
+  "reportFile": "02-catalog-analysis.md",
+  "template": "{TemplateName}",
+  "confidence": "high|medium|low",
+  "borrowFrom": "{other template or null}",
+  "modulesSelected": {N}
+}
+```
+
+## Rules
+
+- READ-ONLY — only write report files
+- Always recommend exactly ONE primary template
+- Do NOT recommend building from scratch
+- No modules are auto-included — every module must match via keywords
+- **Visual liveliness rule**: For consumer apps (shopping, social, food, fitness, travel, art, music, creative, lifestyle), automatically include **MicroInteractions** unless the domain demands restraint (medical, legal, finance)
+- When ANY animation module is selected, auto-include MotionPreferences
+- Aim for 5-15 modules
+- "Relevant Templates" is a boost, not a hard filter
+- Module integration happens later (Steps 4-5), not here

package/.claude/skills/customization-planner/SKILL.md

@@ -9,8 +9,8 @@ Use this skill to produce a single, comprehensive customization manifest before
 
 ## When to Use
 
-- After Step 0 (Prompt Validation), Step 1 (Template Selection), and Step 4a (Design Brand Selection) are complete
-- After Step 1 (Clone) and Step 3 (Rename) are complete — the output app directory exists
+- After Step 0 (Prompt Validation, Catalog Analysis, Design Brand Selection) is complete
+- After Step 1 (Clone) and Step 2 (Rename) are complete — the output app directory exists
 - BEFORE any code modifications (AppConfig, MockDataProvider, screens, theme)
 
 ## Context You Need
@@ -23,7 +23,7 @@ Use this skill to produce a single, comprehensive customization manifest before
 - **Selected template** — which template was cloned (e.g., "TrackTemplate")
 - **Selected design brand** — brand name and file path (e.g., "VibrantPlayful", `designs/brands/vibrant-playful.md`)
 - **Adaptation suggestions** — from the design-selector (if any)
-- **Selected modules** — from the module selection report (`reports/02b-module-selection.md`)
+- **Selected modules** — from the catalog analysis report (`reports/02-catalog-analysis.md`)
 
 ## Instructions
 
@@ -37,7 +37,7 @@ Read these files in parallel (batch your read calls):
 4. **MockDataProvider** — find and read the MockDataProvider file — understand seed data structure, entity types, item counts
 5. **Template Features directory** — list all screen files in `Features/` (iOS) or `features/` (Android)
 6. **TESTING_MANIFEST.md** — `output/{app-name}/TESTING_MANIFEST.md` — all test IDs, screens, element counts
-7. **Module selection report** — `output/{app-name}/reports/02b-module-selection.md` — which shared modules were selected
+7. **Catalog analysis report** — `output/{app-name}/reports/02-catalog-analysis.md` — which template and shared modules were selected
 
 ### Step 2 — Produce the Design Brief
 
@@ -148,7 +148,7 @@ Based on the app domain and the existing MockDataProvider structure:
 
 ### Step 6 — Produce Module Integration Plan
 
-Read the module selection report (`output/{app-name}/reports/02b-module-selection.md`). For each selected module, plan how it connects to the app:
+Read the "Module Selection" section from `output/{app-name}/reports/02-catalog-analysis.md`. For each selected module, plan how it connects to the app:
 
 - **Placement:** How the module's UI is presented (tab, sheet, navigation link, settings row, or embedded)
 - **Presented from:** Which existing screen triggers it and how
@@ -241,6 +241,45 @@ Write the complete manifest to `output/{app-name}/reports/customization-manifest
 - Spacing: {scale}
 - Icon style: {filled|outlined}
 
+### Visual Polish Plan
+
+#### Shadow Style
+| Token | Value |
+|-------|-------|
+| Shadow type | {colored / neutral} |
+| Shadow color | {primary at X% / black at X%} |
+| Shadow blur | {X}pt |
+| Shadow y-offset | {X}pt |
+
+#### Gradient Usage
+- Hero sections: {primary-to-secondary gradient / subtle gradient / none}
+- CTA buttons: {gradient / solid}
+- Section backgrounds: {subtle gradient / solid}
+
+#### Animation Choreography
+| Token | Value |
+|-------|-------|
+| Spring preset | {bouncy / smooth / snappy} |
+| Press scale | {0.95} |
+| Stagger delay | {X}ms |
+| Favorite toggle | {heart bounce + haptic} |
+| Success event | {confetti / sparkle / none} |
+
+#### Built-in Modifiers (always available, no module required)
+- `.staggeredAppear(index:)` — staggered list entrance
+- `.slideIn()` / `.slideAndFade()` — appear animations
+- `.scaleOnPress()` — press feedback (0.95 scale + spring)
+- `.hapticFeedback()` — haptic on tap
+- `.bounceOnChange(isActive:)` — toggle bounce
+- `.cardShadow()` / `.elevatedShadow()` — shadow depth
+- `.shimmer()` — shimmer overlay for loading placeholders
+- `.pulse()` — repeating pulse for live indicators
+- `.heartBounce(isActive:)` — bounce for favorite/like toggles
+
+#### Depth & Material
+- Sheet backgrounds: {glass blur / solid}
+- Tab bar: {blur / solid / elevated}
+
 ### Icon Mapping — Tabs
 | Tab | Label | iOS (SF Symbol) | Android (Material) |
 |-----|-------|-----------------|-------------------|

package/.claude/skills/design-selector/SKILL.md

@@ -12,7 +12,7 @@ Use this skill to select the best visual design brand for the user's app.
 
 ## When to Use
 
-- At Step 4a, after the template is cloned and renamed
+- At Step 0, in parallel with prompt validation and catalog analysis
 - Before applying design tokens
 
 ## Instructions
@@ -25,6 +25,8 @@ Read `designs/DESIGN_CATALOG.md`. Understand each brand's visual tone, decision
 
 Score against app description and target audience. Apply match criteria and exclusion rules. Follow the decision flow.
 
+**Energy bias**: When brands tie, prefer higher Energy score. For ambiguous domains (not medical/finance/corporate), bias toward Energy >= 3. Apps should feel vibrant by default.
+
 ### Step 3 — Handle User Style Preferences
 
 If user mentioned colors/style: use as primary input, select brand with best structural token match, note color overrides in adaptations.

package/.claude/skills/design-system/SKILL.md

@@ -16,7 +16,7 @@ Read `designs/DESIGN_PRINCIPLES.md` for baseline mobile design rules.
 
 ### Step 1 — Load the Selected Brand
 
-Read brand file, extract palette, layout tokens, typography, icon style. Apply any ADAPT suggestions.
+Read brand file, extract palette, layout tokens, typography, icon style, and **Motion & Effects** section (spring preset, press scale, shadow style, gradient usage, depth approach, haptic policy). Apply any ADAPT suggestions.
 
 ### Step 2/3 — Fallback (if no brand selected)
 

package/.claude/skills/exploratory-tester/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: exploratory-tester
+description: Screenshot and accessibility-tree driven exploratory testing. Does NOT read source code — tests purely through what the AI sees on screen. Discovers visual bugs, accessibility issues, UX problems, and content issues.
+allowed-tools: inspect, act, assert, wait, navigate, device, logs, Read, Write
+context: fork
+---
+
+# Exploratory Tester Skill
+
+Test the app by exploring it visually — screenshots and accessibility tree as your only inputs. Do NOT read source code.
+
+## Context
+
+- **Platform**, **Bundle ID**, **Simulator name** — for ai-tester MCP calls
+- **App directory** — only for writing the bug report
+
+## Instructions
+
+### Phase A — Screen Discovery
+
+1. Launch app: `inspect({ platform, app: bundleId, deviceName })`
+2. Wait 3-5s, `inspect()` again
+3. Map tab bar — identify all tabs from element tree
+4. Visit each tab — `inspect()` on each
+5. Discover sub-screens — tap list items, buttons, links
+6. Build screen map (tab → screen → sub-screen)
+
+### Phase B — Per-Screen Audit
+
+For each screen, `inspect()` then:
+
+**B1 — Visual Analysis (screenshot):**
+- No overlapping/cut-off text, proper spacing, correct alignment
+- Real domain text (not "Lorem ipsum", "Item 1", "Template")
+- Images loaded, icons match context
+- Consistent typography and colors
+- Template leftover detection
+
+**B2 — Accessibility Tree Audit:**
+- Every button/link has non-empty label
+- Images have a11y descriptions
+- Form fields have labels
+- No orphaned elements (in tree but not visible, or visible but not in tree)
+- Touch targets >= 44x44pt (iOS) / 48x48dp (Android)
+
+**B3 — Interactive Exploration:**
+- Tap every button — verify something happens (flag dead buttons)
+- Type into every text field — normal text + edge cases (empty, long, special chars)
+- Toggle every switch — verify state change
+- Scroll every list to bottom and back up
+- Navigate 3+ levels deep, verify back nav works all the way
+- Switch tabs rapidly — verify correct content
+- Test state persistence (favorite, form text, scroll position)
+
+**B4 — Before/After Comparison:**
+- `inspect()` after interactions, compare element trees
+- Flag unexpected changes (disappeared elements, count mismatches)
+
+### Phase C — Bug Classification
+
+| Tag | Category | Examples |
+|-----|----------|----------|
+| `[VISUAL]` | Layout | Overlap, truncation, wrong colors |
+| `[A11Y]` | Accessibility | Missing labels, small targets |
+| `[UX]` | Experience | Dead buttons, confusing nav |
+| `[CONTENT]` | Content | Template leftovers, placeholders |
+| `[STATE]` | State | Not persisting, stale views |
+| `[CRASH]` | Crash | App crash on interaction |
+
+Format: `BUG-{NNN}: [{SEVERITY}][EXPLORATORY][{TAG}] {description}` with screen, element, steps, expected, actual.
+
+### Phase D — Write Bug Report
+
+Write/append to `output/{app-name}/reports/11-bug-report.md` with: summary counts, accessibility summary, screen map, all bugs.
+
+## Rules
+
+- **DO NOT read source code** — only screenshots + element tree from `inspect()`
+- **DO NOT follow a test plan** — explore freely
+- Test EVERY interactive element in the element tree
+- Use ai-tester MCP tools for ALL interaction
+- Write findings to bug report — do NOT fix bugs

package/.claude/skills/ios-customizer/SKILL.md

@@ -100,7 +100,19 @@ iOS templates use a `Colors.swift` theme file:
 - Use semantic colors where possible (`Color.primary`, `Color.secondary`)
 - Apply corner radius and spacing tokens from the design brief
 
-### Step 4.5 — Generate App Launcher Icon
+### Step 4.5 — Visual Polish Application
+
+Apply the **Visual Polish Plan** from the manifest. MANDATORY for every build.
+
+1. **Shadows**: Apply `.cardShadow()` or `shadow(color:radius:x:y:)` to every card/elevated surface using manifest shadow tokens.
+2. **Gradients**: Apply `LinearGradient` to hero sections and primary CTAs (primary → secondary, 135deg).
+3. **Press feedback**: All buttons use `.scaleOnPress()` (scale 0.95, spring return). Add `UIImpactFeedbackGenerator` to favorite toggles and submit buttons.
+4. **Staggered animations**: All list views use `.staggeredAppear(index:)` on each item.
+5. **Empty states**: Gradient circle behind icon + `.slideIn()` animation.
+6. **Glass/blur**: `.ultraThinMaterial` on sheet backgrounds and overlays.
+7. **Haptic**: Feedback on favorite toggles, pull-to-refresh, primary actions.
+
+### Step 4.6 — Generate App Launcher Icon
 
 Generate a domain-specific app icon using the manifest's **App Launcher Icon** section:
 
@@ -216,18 +228,27 @@ If the customization manifest includes an **"Animation & Sensory Plan"** section
 2. For each screen in your batch, apply the assigned modifiers:
 
 ```swift
-// MicroInteractions — press feedback
+// Built-in press feedback (always available)
 Button("Add to Cart") { ... }
     .scaleOnPress()
-    .hapticFeedback(.impact(.medium))
+    .hapticFeedback(.medium)
 
-// ScrollEffects — parallax header
-ParallaxHeaderView(height: 280) { AsyncImage(url: item.imageURL) }
+// Built-in staggered list items (always available)
+ItemRow(item: items[index]).staggeredAppear(index: index)
 
-// AnimatedTransitions — staggered list items
-ItemRow(item: items[index]).staggeredAppearance(index: index)
+// Built-in shadow and slide (always available)
+CardView(item: item).cardShadow()
+EmptyStateView().slideIn()
+
+// Built-in shimmer, pulse, heartBounce (always available)
+RoundedRectangle(cornerRadius: 8).fill(Color(.systemGray5)).shimmer()
+Circle().fill(.red).frame(width: 8).pulse()
+Image(systemName: "heart.fill").heartBounce(isActive: isFavorite)
+
+// ScrollEffects module (if integrated)
+ParallaxHeaderView(height: 280) { AsyncImage(url: item.imageURL) }
 
-// CelebrationEffects — success overlay
+// CelebrationEffects module (if integrated)
 .celebrationOverlay(isPresented: $showCelebration, style: .confetti)
 ```
 

package/.claude/skills/module-integrator/SKILL.md

@@ -9,7 +9,7 @@ Integrate selected shared modules by reading reference implementations from `tem
 
 ## Context You Need
 
-- Module selection report (`reports/02b-module-selection.md`)
+- Catalog analysis report (`reports/02-catalog-analysis.md`) — template + module selection
 - Customization manifest (`reports/customization-manifest.md`) — module integration plan
 - Platform, app name, bundle ID
 - AppConfig file path

package/.claude/skills/react-native-customizer/SKILL.md

@@ -91,6 +91,18 @@ React Native templates use a `ThemeContext.tsx`:
 - Apply corner radius and spacing tokens
 - Apply typography settings (font sizes, weights)
 
+### Step 4.5 — Visual Polish Application
+
+Apply the **Visual Polish Plan** from the manifest. MANDATORY for every build.
+
+1. **Shadows**: Platform-aware shadow styles on all cards (`shadowColor`/`shadowOffset`/`shadowRadius` + `elevation`).
+2. **Gradients**: `expo-linear-gradient` `LinearGradient` on hero sections and CTAs.
+3. **Press feedback**: Scale animation (0.95, spring) on all TouchableOpacity. Wrap in `ScaleButton` component.
+4. **Staggered animations**: `useStaggeredAppear(index)` on all FlatList items.
+5. **Empty states**: Gradient circle behind icon + `useSlideIn()` animation.
+6. **Blur/glass**: `expo-blur` BlurView on modal/sheet backgrounds.
+7. **Haptic**: `expo-haptics` on favorite toggles and primary actions.
+
 ### Step 5 — Data Layer & Offline Infrastructure
 
 Templates include an **offline-first data layer**:
@@ -148,18 +160,18 @@ If the manifest includes an **"Animation & Sensory Plan"** section:
 2. Apply the assigned modifiers using imported module hooks/components:
 
 ```typescript
-// MicroInteractions — press feedback
-import { useScaleOnPress } from '../shared/MicroInteractions';
-import { useHapticEngine } from '../shared/HapticEngine';
-const { animatedStyle, handlers } = useScaleOnPress();
-
-// ScrollEffects — parallax header
+// Built-in (always available)
+import { useScaleOnPress, useStaggeredAppear, useSlideIn, cardShadowStyle, useShimmer, usePulse, useHeartBounce } from '../animation/useAnimatedList';
+const { style: pressStyle, onPressIn, onPressOut } = useScaleOnPress();
+const listItemStyle = useStaggeredAppear(index);
+<View style={[styles.card, cardShadowStyle()]}>{/* content */}</View>
+<Animated.View style={[styles.placeholder, useShimmer()]} /> // loading
+<Animated.View style={[styles.dot, usePulse()]} /> // live indicator
+<Animated.View style={useHeartBounce(isFav)}><HeartIcon /></Animated.View> // favorite
+
+// Modules (if integrated)
 import { ParallaxHeader } from '../shared/ScrollEffects';
 <ParallaxHeader height={280} imageSource={item.imageUrl} />
-
-// CelebrationEffects — success overlay
-import { CelebrationOverlay } from '../shared/CelebrationEffects';
-<CelebrationOverlay isActive={showCelebration} style="confetti" />
 ```
 
 3. Wrap with `useMotionPreferences` checks if MotionPreferences is integrated

package/.claude/skills/test-planner/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: test-planner
+description: Analyzes app source code to generate a structured test plan before any simulator interaction. Reads Views, ViewModels, AppConfig, MockDataProvider, and TESTING_MANIFEST to produce a comprehensive test matrix.
+allowed-tools: Read, Grep, Glob, LS
+context: fork
+agent: Explore
+---
+
+# Test Planner Skill
+
+Analyze app source code and produce a structured test plan. Runs offline — no simulator needed.
+
+## Instructions
+
+### Step 1 — Gather App Inventory
+
+Read from the app directory:
+1. `TESTING_MANIFEST.md` — test IDs, screen inventory, element counts
+2. `AppConfig` — feature flags, business rules (`.swift`/`.kt`/`.ts`)
+3. `MockDataProvider` — data counts, categories, structure
+4. `customization-manifest.md` (if exists) — screen descriptions, expected behavior
+5. `summary.json` (if exists) — previous results, template, brand
+6. `requirements.md` or `PRD.md` (if exists) — business-logic test cases
+
+### Step 2 — Scan Screens + ViewModels
+
+Read all View files (`*View.swift`, `*Screen.kt`, `*Screen.tsx`) and ViewModel files. Extract per screen:
+- Interactive elements (buttons, toggles, fields, list items, FABs)
+- Navigation targets
+- Data dependencies from MockDataProvider
+- Feature flags controlling visibility
+- State transitions and CRUD operations
+
+### Step 3 — Build Test Matrix
+
+For each screen, create a checklist:
+
+```markdown
+### Screen: {Name}
+**File:** {path} | **Elements:** {N}
+
+#### Rendering
+- [ ] Renders without crash
+- [ ] Correct data shown ({N} items)
+- [ ] No template leftover text
+
+#### Navigation
+- [ ] Navigate to screen, navigate back
+
+#### Interactions
+- [ ] {Button}: tap triggers {action}
+- [ ] {Toggle}: state changes
+```
+
+Add sections for: Edge Cases (empty states, long text, rapid taps, deep navigation), Regression Checks (leftovers, a11y IDs, images, back nav), Requirements-Based Tests (if PRD exists).
+
+### Step 4 — Assign Priorities
+
+- **P0** — crashes, data loss, broken navigation
+- **P1** — features don't work, wrong data
+- **P2** — visual, accessibility, minor UX
+- **P3** — cosmetic
+
+## Report Output
+
+Write `output/{app-name}/reports/10-test-plan.md`. Update `summary.json` with step entry (step: 10, name: "test-plan").
+
+## Rules
+
+- READ-ONLY — do NOT modify source files or boot simulators
+- Every interactive element must have at least one test case
+- Test plan must be detailed enough for another agent to execute without reading source

package/.cursor/agents/README.md

@@ -12,8 +12,10 @@ These agent definition files (`.md`) are **preserved as a fallback** for when Cu
 |---|---|
 | `security-auditor.md` (Phase 1) | `.cursor/skills/prompt-validator/SKILL.md` |
 | `security-auditor.md` (Phase 2) | `.cursor/skills/code-auditor/SKILL.md` |
-| `template-selector.md` | `.cursor/skills/template-selector/SKILL.md` |
+| `template-selector.md` | `.cursor/skills/catalog-analyzer/SKILL.md` (merged with module-selector) |
 | `design-selector.md` | `.cursor/skills/design-selector/SKILL.md` |
+| `catalog-analyzer.md` | `.cursor/skills/catalog-analyzer/SKILL.md` (template + module selection) |
+| `react-native-customizer.md` | `.cursor/skills/react-native-customizer/SKILL.md` |
 | `ios-customizer.md` | `.cursor/skills/ios-customizer/SKILL.md` |
 | `android-customizer.md` | `.cursor/skills/android-customizer/SKILL.md` |
 | `build-tester.md` | `.cursor/skills/build-tester/SKILL.md` |