@shaykec/app-agent 1.0.8 → 1.0.10

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

@@ -9,7 +9,7 @@ Use this skill to perform deep iOS/SwiftUI customization on a cloned template.
 
 ## When to Use
 
-- At Step 8 of the AppAgent workflow, when the platform is iOS
+- At Step 5 of the AppAgent workflow, when the platform is iOS
 - After AppConfig, mock data, and design tokens are already in place
 - When you need to modify SwiftUI views, navigation, and themes
 
@@ -100,6 +100,28 @@ 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 — 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:
+
+1. Read the icon spec: `iOS SF Symbol` (e.g., `bag.fill`) and `Background` hex color
+2. Run: `swift scripts/generate-app-icon.swift "{symbol}" "{background}" "output/{app-name}/{AppName}/Resources/Assets.xcassets/AppIcon.appiconset/"`
+3. Verify `AppIcon-1024.png` exists in the output directory
+
+If `scripts/generate-app-icon.swift` does not exist or fails, skip — the template's default icon will be used.
+
 ### Step 5 — Data Layer & Offline Infrastructure
 
 Templates now include an **offline-first data layer**. Understand these components:
@@ -118,18 +140,31 @@ Templates now include an **offline-first data layer**. Understand these componen
 - `Data/SyncManager.swift` — if entity types were renamed, update domain methods
 
 **ViewModel patterns** (how views consume data):
+
+ViewModels use the `DataRepository` protocol abstraction, not `MockDataProvider` directly:
 ```swift
-// ViewModels observe MockDataProvider.shared
-@ObservedObject var store = MockDataProvider.shared
+// ViewModels depend on the DataRepository protocol
+private let repository: any DataRepository
+
+init(repository: any DataRepository = DataSourceResolver.repository) {
+    self.repository = repository
+}
+
+// Read data via the protocol
+let items = repository.items
+let categories = repository.categories
 
-// Or use EnvironmentObject if injected
-@EnvironmentObject var store: MockDataProvider
+// CRUD via the protocol
+repository.addItem(newItem)
+repository.deleteItem(item)
+repository.toggleFavorite(item)
 
-// CRUD via SyncManager
+// If SyncManager exists, it wraps the repository
 SyncManager.shared.addProduct(newProduct)
-SyncManager.shared.deleteProduct(id)
 ```
 
+When customizing ViewModels, ALWAYS use `repository` (from `DataSourceResolver`), never `MockDataProvider.shared` directly. This ensures the app works with any data source.
+
 **OfflineBanner integration** — add to main navigation views:
 ```swift
 VStack(spacing: 0) {
@@ -138,27 +173,87 @@ VStack(spacing: 0) {
 }
 ```
 
-### Step 6 — MockDataProvider Verification
+### Step 6 — Data Layer Verification
 
-Verify the MockDataProvider uses the correct patterns:
+Verify the data layer uses the correct patterns:
 
+**DataRepository protocol:**
 ```swift
-class MockDataProvider: ObservableObject {
+protocol DataRepository: AnyObject {
+    var items: [Item] { get }
+    var categories: [Category] { get }
+    var favoriteItems: [Item] { get }
+    func loadData()
+    func addItem(_ item: Item)
+    // ... all CRUD + query methods
+}
+```
+
+**MockDataProvider (conforms to DataRepository):**
+```swift
+class MockDataProvider: ObservableObject, DataRepository {
     static let shared = MockDataProvider()
-    
-    @Published var products: [Product]  // Reactive, mutable
-    
-    static let defaultProducts: [Product] = [...]  // Seed data
-    
-    func addProduct(_ product: Product) { ... }  // CRUD
-    func reset() { ... }  // Reset to defaults
+    @Published var products: [Product]
+    static let defaultProducts: [Product] = [...]
+    func addProduct(_ product: Product) { ... }
+    func reset() { ... }
 }
 ```
 
-- Verify seed data matches the new domain
-- Ensure CRUD methods reference correct entity types
-- Verify `reset()` works correctly
-- Check that `@Published` properties are being observed by ViewModels
+**DataSourceResolver:**
+```swift
+enum DataSourceResolver {
+    static var repository: any DataRepository {
+        switch AppConfig.DataSource.active {
+        case .mock: return MockDataProvider.shared
+        case .localStorage: return MockDataProvider.shared  // TODO: LocalStorageProvider
+        }
+    }
+}
+```
+
+Verify:
+- DataRepository protocol matches MockDataProvider's public interface
+- MockDataProvider conforms to DataRepository
+- DataSourceResolver returns the correct implementation
+- ViewModels use `DataSourceResolver.repository`, not `MockDataProvider.shared` directly
+- Seed data matches the new domain
+- CRUD methods reference correct entity types
+
+### Step 6.5 — Apply Animation Modifiers (if animation modules are integrated)
+
+If the customization manifest includes an **"Animation & Sensory Plan"** section:
+
+1. Read the "Per-Screen Animation Modifiers" table from the manifest
+2. For each screen in your batch, apply the assigned modifiers:
+
+```swift
+// Built-in press feedback (always available)
+Button("Add to Cart") { ... }
+    .scaleOnPress()
+    .hapticFeedback(.medium)
+
+// Built-in staggered list items (always available)
+ItemRow(item: items[index]).staggeredAppear(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 module (if integrated)
+.celebrationOverlay(isPresented: $showCelebration, style: .confetti)
+```
+
+3. Wrap all applied animations with `.motionAware()` if MotionPreferences is integrated
+4. Do NOT add animation modifiers to screens not listed in the manifest
 
 ## Report Output
 
@@ -167,7 +262,7 @@ Write the report to `output/{app-name}/reports/05-customization.md` (append iOS
 ```markdown
 # Customization Report
 
-**Step:** 8
+**Step:** 5
 **Skill:** ios-customizer
 **Timestamp:** {ISO 8601}
 **Result:** PASS
@@ -201,6 +296,11 @@ iOS (Swift / SwiftUI)
 - SyncManager methods updated: {list or "no changes needed"}
 - Data persistence verified: {yes/no}
 
+## Animation Modifiers Applied
+
+- {modifier}: applied to {screen} — {description}
+- MotionPreferences respected: {yes/no/N/A}
+
 ## Potential Issues
 
 - {any concerns or items needing manual review}
@@ -212,7 +312,7 @@ Update `output/{app-name}/reports/summary.json` — read the file, append this s
 
 ```json
 {
-  "step": 8,
+  "step": 5,
   "name": "ios-customization",
   "startedAt": "{ISO 8601 timestamp}",
   "durationSeconds": 0,

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,27 +91,100 @@ React Native templates use a `ThemeContext.tsx`:
 - Apply corner radius and spacing tokens
 - Apply typography settings (font sizes, weights)
 
-### Step 5 — Data Layer & Mock Data
+### 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**:
 
 **Files you should NOT modify** (generic infrastructure):
 - `src/data/DataRepository.ts` — interface definition
+- `src/data/NetworkMonitor.ts` — connectivity detection
+- `src/data/LocalPersistence.ts` — JSON file persistence
+- `src/components/OfflineBanner.tsx` — offline status banner
 - `src/theme/ThemeContext.tsx` — theme provider
 
 **Files you MAY need to update** (domain-specific):
-- `src/mock/MockDataProvider.ts` — seed data already updated in Step 4. Verify:
-  - Seed data matches the new domain
-  - All CRUD methods work with correct entity types
-  - Subscription/onChange pattern is working
-  - Reset method references correct defaults
+- `src/mock/MockDataProvider.ts` — seed data already updated in Step 4. Verify seed data, CRUD methods, subscription pattern, and reset defaults
+- `src/data/SyncManager.ts` — if entity types were renamed, update domain methods
+
+**ViewModel patterns** — use `DataSourceResolver`, not `MockDataProvider` directly:
+```tsx
+import { DataSourceResolver } from '../data/DataSourceResolver';
+
+export function useHomeViewModel() {
+  const repository = DataSourceResolver.repository;
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    setItems(repository.getItems());
+    const unsubscribe = repository.subscribe(() => setItems(repository.getItems()));
+    return unsubscribe;
+  }, []);
+  return { items };
+}
+```
 
-### Step 6 — MockDataProvider Verification
+**OfflineBanner integration** — add to main navigation screens:
+```tsx
+<View style={{ flex: 1 }}>
+  <OfflineBanner />
+  {/* ... rest of screen content */}
+</View>
+```
+
+### Step 6 — Data Layer Verification
 
-Verify the MockDataProvider uses correct patterns:
-- Implements all DataRepository methods
-- ViewModel hooks use MockDataProvider correctly
+Verify:
+- `DataRepository` interface matches MockDataProvider's public methods
+- MockDataProvider implements DataRepository
+- `DataSourceResolver` returns the correct implementation
+- ViewModel hooks use `DataSourceResolver.repository`, not `MockDataProvider` directly
 - Seed data matches the new domain
 - CRUD methods reference correct entity types
 
+### Step 6.5 — Apply Animation Modifiers (if animation modules are integrated)
+
+If the manifest includes an **"Animation & Sensory Plan"** section:
+
+1. Read the "Per-Screen Animation Modifiers" table
+2. Apply the assigned modifiers using imported module hooks/components:
+
+```typescript
+// 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} />
+```
+
+3. Wrap with `useMotionPreferences` checks if MotionPreferences is integrated
+4. Do NOT add animation modifiers to screens not listed in the manifest
+
+### Step 6.7 — App Icon (if applicable)
+
+React Native apps target both iOS and Android. App icon customization is handled per-platform:
+- **iOS**: If `scripts/generate-app-icon.swift` exists, run it with SF Symbol + background color from manifest
+- **Android**: If `templates/android/ICON_VECTORS.md` exists, update `ic_launcher_foreground.xml` and `ic_launcher_background` color
+
+If scripts/resources are not available, skip — default icons will be used.
+
 ## Report Output
 
 Write the report to `output/{app-name}/reports/05-customization.md`:
@@ -144,6 +217,17 @@ React Native (TypeScript)
 - Empty states: {count}
 - CTAs updated: {count}
 
+## Offline Infrastructure
+
+- OfflineBanner integrated: {yes/no}
+- SyncManager methods updated: {list or "no changes needed"}
+- Data persistence verified: {yes/no}
+
+## Animation Modifiers Applied
+
+- {modifier}: applied to {screen} — {description}
+- MotionPreferences respected: {yes/no/N/A}
+
 ## Potential Issues
 
 - {any concerns}
@@ -191,8 +275,10 @@ Templates include `testID` props on all interactive elements and a `TESTING_MANI
 - ONLY edit files under `output/` — never touch `templates/`
 - Ensure all imports resolve after your changes
 - Preserve `MockDataProvider` CRUD methods and `reset()` function
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
+- Ensure OfflineBanner is integrated into main navigation screens
 - Use `testID` props on ALL interactive elements
-- Follow `{screen}_{element}_{role}` convention for new test IDs
+- Follow `{screen}_{element}_{role}` convention for new test IDs (see `templates/TEST_ID_CONVENTIONS.md`)
 - Use `StyleSheet.create()` for styles, not inline objects
 - Use functional components with TypeScript
 - Keep React Navigation structure intact

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` |

package/.cursor/agents/android-customizer.md

@@ -123,18 +123,19 @@ private val LightColorScheme = lightColorScheme(
 - Use Material 3 color roles (primary, secondary, tertiary, surface, etc.)
 - Keep `dynamicColor` support if present
 
-### MockDataProvider Updates
-Android MockDataProvider uses companion object with functions:
+### Data Layer
+Templates use a `DataRepository` interface with `DataSourceResolver`:
 ```kotlin
-object MockDataProvider {
-    fun getServices(): List<Service> = listOf(...)
-    fun getProviders(): List<Provider> = listOf(...)
-}
+// Screens get the repository from DataSourceResolver
+val repository = remember { DataSourceResolver.repository }
+val items by repository.items.collectAsState()
+repository.addItem(newItem)
 ```
-- Keep the same function signatures
-- Update return values with domain-specific data
-- Use `UUID.randomUUID().toString()` for IDs
-- Use `LocalDateTime.now()` and `LocalDate` for dates
+- ALWAYS use `DataSourceResolver.repository`, never `MockDataProvider` directly
+- Preserve MockDataProvider CRUD functions and `reset()` method
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
+- Verify NetworkMonitor is registered in the Application class
+- Ensure OfflineBanner is integrated into main navigation composables
 
 ## Output
 
@@ -155,5 +156,8 @@ POTENTIAL ISSUES:
 - Ensure all `import` statements resolve after renaming
 - Keep `@HiltAndroidApp`, `@HiltViewModel`, `@AndroidEntryPoint` intact
 - Keep `build.gradle.kts` syntactically valid Kotlin DSL
-- Preserve `MockDataProvider` function signatures
+- Preserve `MockDataProvider` CRUD functions and `reset()` method
+- Do NOT modify NetworkMonitor, LocalPersistence, or OfflineBanner
 - Use Material 3 components (not legacy Material 2)
+- Preserve ALL `Modifier.testTag()` calls — do NOT remove test IDs
+- Follow `{screen}_{element}_{role}` convention for new test tags (see `templates/TEST_ID_CONVENTIONS.md`)

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

@@ -0,0 +1,83 @@
+---
+name: catalog-analyzer
+description: Selects the best template from CATALOG.md and shared modules from MODULES_CATALOG.md in a single pass. Uses selected template context to boost module selection accuracy via "Relevant Templates" column.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - LS
+readonly: true
+---
+
+# Catalog Analyzer
+
+You are a specialised subagent for selecting the best mobile app template AND the best shared modules. You have deep knowledge of both catalogs and their selection criteria.
+
+## Logging Protocol
+
+When you start, print:
+`[SUBAGENT:catalog-analyzer] Starting — catalog analysis for "{app description}"`
+
+When you finish, print:
+`[SUBAGENT:catalog-analyzer] Completed — selected {TemplateName} (confidence: {high|medium|low}), {N} modules`
+
+## Instructions
+
+### Phase 1 — Template Selection
+
+1. Read `templates/CATALOG.md` thoroughly
+2. Given the user's app description and target platform, evaluate each template:
+   - Score against the "Best-For Keywords" in the decision matrix
+   - Check the "Best match when" criteria for each template
+   - Apply the "NOT a match when" rules to eliminate poor fits
+   - Consider the "Hybrid Apps" table if the app spans categories
+3. If no template is a strong match, follow the "When No Template Fits" guidance — pick the template with the most similar navigation and screen patterns
+4. Choose exactly ONE primary template
+
+### Phase 2 — Module Selection
+
+5. Read `templates/shared/MODULES_CATALOG.md` thoroughly
+6. For every module, match by keywords AND check "Relevant Templates" against the selected template:
+   - Keyword match + template match → strong include
+   - Keyword match + no template match → include with lower confidence
+   - No keyword match + template match → consider if implied by domain
+7. Apply BaaS heuristics (Firebase vs Supabase vs none)
+8. Check module dependencies — add missing ones
+9. Apply animation/sensory heuristics if description suggests premium feel
+10. Aim for 5-15 modules
+
+## Output Format
+
+Return your answer in this exact 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
+- If confidence is "low", explain what aspects of the user's request don't fit well
+- For hybrid apps, identify which template to START with and what to borrow from the secondary template
+- Do NOT recommend building from scratch — always pick the closest template
+- Consider the platform (iOS vs Android vs React Native)
+- Features covered by shared modules should NOT affect template scoring
+- No modules are auto-included — every module must earn its place via keyword matching
+- "Relevant Templates" is a boost signal, not a hard filter
+- Aim for 5-15 modules — be selective, not exhaustive