@shaykec/app-agent 1.0.8 → 1.0.10

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

@@ -0,0 +1,189 @@
+---
+name: bug-fixer
+description: Reads a bug report from a previous deep-test run and systematically fixes each bug. Rebuilds the app, re-tests the fixed screens, and produces a fix report. Used in Phase 4 of --deep-test --fix or standalone via --fix.
+---
+
+# Bug Fixer Skill
+
+Use this skill to fix bugs documented in a bug report from a previous deep-test run. You read the report, fix each bug in the source code, rebuild, and verify the fixes.
+
+## When to Use
+
+- As Phase 4 of the `--deep-test --fix` pipeline (after testing phases complete)
+- Standalone via the `--fix` command (reads an existing bug report without re-testing)
+- When you have a `reports/11-bug-report.md` with documented bugs to fix
+
+## Context You Need
+
+- **App directory** — path under `output/` (e.g., `output/pawspa-ios/`)
+- **Platform** — `ios`, `android`, or `react-native`
+- **App name** — display name
+- **Bundle ID** — e.g., `com.pawspa.app`
+- **Bug report** — `reports/11-bug-report.md` with categorized bugs
+- **Build artifact path** — for re-testing after fixes (may need to rebuild)
+
+## Instructions
+
+### Step 1 — Read and Prioritize Bugs
+
+1. Read `output/{app-name}/reports/11-bug-report.md`
+2. Parse all bugs (both `[EXPLORATORY]` and `[STRUCTURED]` tagged)
+3. Sort by severity: P0 (Critical) → P1 (High) → P2 (Medium) → P3 (Low)
+4. Triage each bug into one of three categories:
+   - **FIX** — can be fixed in the source code
+   - **DEFER** — requires major refactoring or design change (document recommendation instead)
+   - **SKIP** — false positive or cosmetic non-issue
+
+### Step 2 — Locate Source Files
+
+For each bug marked FIX:
+
+#### For `[STRUCTURED]` bugs:
+- The bug report typically includes the file path — open it directly
+- Cross-reference with the test plan (`reports/10-test-plan.md`) for additional context
+
+#### For `[EXPLORATORY]` bugs:
+- Use the screen name and element description to find the relevant source file
+- **iOS:** Search for `{ScreenName}View.swift` and `{ScreenName}ViewModel.swift`
+- **Android:** Search for `{ScreenName}Screen.kt` and `{ScreenName}ViewModel.kt`
+- **React Native:** Search for `{ScreenName}Screen.tsx` and `use{ScreenName}.ts`
+- For content bugs: also check `AppConfig`, `MockDataProvider`, and string resources
+
+#### For `[A11Y]` bugs:
+- Open the View file for the affected screen
+- Search for the element type mentioned in the bug (Image, Button, etc.)
+- Add accessibility modifiers/attributes
+
+### Step 3 — Fix Each Bug
+
+Apply fixes in priority order (P0 first, P3 last). For each bug:
+
+1. **Read the source file(s)** involved
+2. **Understand the root cause** — don't just patch the symptom
+3. **Apply the minimal fix** — change as little code as possible to fix the bug
+4. **Document the fix** — record what you changed and why
+
+#### Fix Patterns by Bug Type
+
+**`[VISUAL]` — Layout/visual issues:**
+- Truncation: add `lineLimit`, adjust `frame`, use `minimumScaleFactor`
+- Overlap: fix `ZStack` ordering, add padding/spacing, fix constraint priorities
+- Spacing: adjust `padding`, `spacing` parameters
+
+**`[A11Y]` — Accessibility issues:**
+- Missing label: add `.accessibilityLabel("Description")` (iOS) or `contentDescription` (Android) or `accessibilityLabel` (React Native)
+- Missing image description: add `.accessibilityLabel` to Image views
+- Small touch targets: increase `frame` size or add `.contentShape(Rectangle())` + padding
+
+**`[UX]` — Dead buttons / broken navigation:**
+- Dead button: check the action handler — likely missing navigation call or action dispatch
+- Broken navigation: verify `NavigationLink` destination or `navigate()` call
+- Wrong destination: fix the navigation target
+
+**`[CONTENT]` — Template leftovers / wrong text:**
+- Search the file for the leftover text and replace with domain-appropriate text
+- Check `AppConfig` and `MockDataProvider` for the source of the wrong text
+- Check string resource files if the text comes from a resource
+
+**`[STATE]` — State not persisting:**
+- Check ViewModel — is the state being saved after the action?
+- Check MockDataProvider — is the update method being called?
+- Check binding: is the View observing the ViewModel correctly?
+
+**`[CRASH]` — App crashes:**
+- Look for force unwraps (`!`), array index out of bounds, nil reference
+- Add nil checks, use optional binding, add bounds checking
+- If crash is in navigation, check for missing views or circular dependencies
+
+### Step 4 — Rebuild the App
+
+After all fixes are applied:
+
+1. Follow the `build-tester` skill to rebuild the app
+2. If the build fails, fix the compilation errors (your fixes may have introduced syntax issues)
+3. Maximum **3 rebuild cycles** for build errors
+
+### Step 5 — Verify Fixes
+
+After a successful build:
+
+1. Boot a simulator (or use an existing one if already running)
+2. Install the new build artifact
+3. Launch the app
+4. For each fixed bug, navigate to the affected screen and verify:
+   - The specific issue is resolved
+   - No new issues were introduced on that screen
+   - The fix didn't break navigation to/from that screen
+
+Use ai-tester MCP tools for verification:
+```
+inspect({ platform: "{platform}", app: "{bundleId}", deviceName: "{sim}" })
+act({ action: "tap", ... })
+assert({ type: "visible", ... })
+```
+
+### Step 6 — Write Fix Report
+
+Write `output/{app-name}/reports/12-fix-report.md`:
+
+```markdown
+# Fix Report
+
+## Summary
+- Bugs in report: {total}
+- Fixed: {N}
+- Deferred: {N}
+- Skipped (false positive): {N}
+
+## Bugs Fixed
+
+### BUG-{NNN}: [{SEVERITY}][{SOURCE}][{TAG}] {description}
+- **Root cause:** {what was actually wrong}
+- **Fix:** {what you changed}
+- **Files modified:** {list of files}
+- **Verified:** PASS / FAIL
+
+### BUG-{NNN}: ...
+...
+
+## Bugs Deferred
+
+### BUG-{NNN}: [{SEVERITY}][{SOURCE}][{TAG}] {description}
+- **Reason:** {why this can't be fixed in a quick pass}
+- **Recommendation:** {what should be done to fix it properly}
+
+## Rebuild Result
+- Build: PASS / FAIL
+- Build cycles: {N}
+
+## Verification Result
+- Fixes verified: {N}/{total fixed}
+- Regressions found: {N}
+```
+
+Update `summary.json` — add a step entry:
+
+```json
+{
+  "step": 12,
+  "name": "bug-fix",
+  "result": "PASS",
+  "bugsTotal": 0,
+  "bugsFixed": 0,
+  "bugsDeferred": 0,
+  "bugsSkipped": 0,
+  "rebuildCycles": 0,
+  "verificationsPass": 0
+}
+```
+
+## Important Rules
+
+- **Fix in priority order** — P0 first, P3 last. If you run out of fix cycles, at least the critical bugs are fixed.
+- **Minimal fixes** — change as little code as possible. Don't refactor unrelated code.
+- **Preserve architecture** — keep MVVM separation, don't merge View and ViewModel code
+- **Preserve MockDataProvider** — update data through the provider, don't hardcode data in views
+- **Maximum 3 rebuild cycles** — if you can't get a clean build in 3 tries, stop and document remaining issues
+- **ONLY write files under `output/`** — never modify templates or skills
+- If a bug fix requires adding a new dependency, DEFER it instead — no new dependencies allowed
+- If a bug fix would require significant redesign (>50 lines changed across >3 files), DEFER it with a recommendation

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

@@ -0,0 +1,222 @@
+---
+name: catalog-analyzer
+description: Selects the best template from CATALOG.md and the best shared modules from MODULES_CATALOG.md in a single pass. Uses the selected template to boost module selection accuracy via the "Relevant Templates" column.
+---
+
+# Catalog Analyzer Skill
+
+Use this skill to select the best template AND the best shared modules for the user's app in one pass.
+
+## When to Use
+
+- At Step 0 of the AppAgent workflow, in parallel with prompt validation and design brand selection
+- When you need to pick both a starting template and shared modules
+- Before cloning any template to `output/`
+
+## Context You Need
+
+- **User description** — what kind of app the user wants to build
+- **Platform** — `ios`, `android`, or `react-native`
+- **Sanitized description** — from the prompt-validator skill (if available)
+
+## Instructions
+
+### Phase 1 — Template Selection
+
+#### Step 1 — Read the Template Catalog
+
+Read `templates/CATALOG.md` thoroughly. Understand each template's:
+- Feature set and architecture
+- "Best-For Keywords" in the decision matrix
+- "Best match when" criteria
+- "NOT a match when" exclusion rules
+
+#### Step 2 — Score Each Template
+
+For each template in the catalog:
+1. Score it against the user's description using the "Best-For Keywords"
+2. Check the "Best match when" criteria — how many match?
+3. Apply the "NOT a match when" rules — does any exclusion trigger?
+4. Consider navigation pattern similarity (tabs, lists, detail screens)
+
+#### Step 3 — Handle Edge Cases
+
+- If the app spans multiple categories, check the "Hybrid Apps" table in the catalog
+- 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
+- Consider the platform (iOS vs Android vs React Native) — all templates are available on all three platforms. The same template names exist under `templates/ios/`, `templates/android/`, and `templates/react-native/`
+
+#### Step 4 — Select ONE Template
+
+Choose exactly ONE primary template. Determine confidence:
+- **high** — multiple criteria match, clear winner
+- **medium** — good fit but some aspects don't align perfectly
+- **low** — no great match, picking the closest option
+
+If hybrid is needed, identify what to borrow from a secondary template.
+
+**Important:** Features covered by shared modules (consent, paywall, push notifications, etc.) should NOT affect template scoring — they are handled by module selection in Phase 2.
+
+### Phase 2 — Module Selection
+
+Uses the template selected in Phase 1 for improved accuracy.
+
+#### Step 5 — Read the Modules Catalog
+
+Read `templates/shared/MODULES_CATALOG.md` thoroughly. Understand each module's:
+- "Best-For Keywords" in the decision matrix
+- "Relevant Templates" column
+- Module dependencies
+
+#### Step 6 — Match Modules by Keywords + Relevant Templates
+
+For every module in the catalog:
+1. Compare its "Best-For Keywords" against the user's description (primary signal)
+2. Check if the **selected template** (from Phase 1) is in the "Relevant Templates" column (boost signal)
+3. If keyword matches AND template matches → **strong include**
+4. If keyword matches but template doesn't match → include with lower confidence
+5. If no keyword match but template matches → consider if implied by domain
+
+**Selection guidance:**
+- Aim for **5-15 modules** that genuinely match the app's features
+- Don't over-select — only include modules the app will actually use
+- Don't under-select — if a keyword matches, the module is likely needed
+- Consider implicit needs (e.g., a "shopping app" implies payment, a "social app" implies sharing)
+
+#### Step 7 — BaaS Module Selection
+
+**BaaS module selection (FirebaseProvider, SupabaseProvider, CachedRepository):**
+- Select FirebaseProvider OR SupabaseProvider (not both) when the description mentions: "real data", "users", "auth", "login", "sign up", "accounts", "cloud", "sync", "backend", "database", "multi-device", "server"
+- Default (no BaaS keywords): NO BaaS module. The app uses `localStorage` (Core Data / Room) by default.
+- If SupabaseProvider is selected, also add CachedRepository (Supabase has no built-in offline cache)
+- If FirebaseProvider is selected, do NOT add CachedRepository (Firestore has built-in offline persistence)
+- Prefer Firebase for "Google ecosystem" keywords, Supabase for "PostgreSQL", "open source", "self-hosted" keywords
+- When both would fit equally, prefer Firebase (more mature mobile SDK)
+
+#### Step 8 — Check Dependencies
+
+Verify that included modules have their dependencies met:
+- Paywall depends on BiometricAuth (optional)
+- AccountDeletion depends on ConsentPrivacy
+- PushNotifications depends on ConsentPrivacy
+- PaymentMethods depends on Paywall
+- GamificationKit depends on ChartsLibrary
+- NotificationCenter depends on PushNotifications
+- CloudSync depends on NetworkBanner
+- LiveActivities depends on PushNotifications
+- SupabaseProvider depends on CachedRepository (for offline support)
+- FirebaseProvider depends on ErrorHandling (optional), NetworkBanner (optional)
+- SupabaseProvider depends on ErrorHandling (optional), NetworkBanner (optional)
+
+If a dependency is missing, add it.
+
+#### Step 9 — Animation & Sensory Module Heuristics
+
+When the user description contains words like **"stunning", "beautiful", "premium feel", "polished", "delightful", "smooth", "animated", "modern", "sleek", "creative", "artistic", "colorful", "vibrant", "elegant", "stylish", "cool", "interactive"**, consider these signal-word matches:
+
+| Signal Word | Consider Modules |
+|---|---|
+| stunning, beautiful, premium, polished | MicroInteractions, AnimatedTransitions, CelebrationEffects |
+| haptic, tactile, vibration, feedback | HapticEngine |
+| sound, audio, click sound, chime | AudioFeedback |
+| parallax, scroll effect, header animation | ScrollEffects |
+| confetti, celebration, achievement | CelebrationEffects |
+| onboarding, walkthrough, tutorial | AnimatedOnboarding |
+| transitions, hero, card flip, animated navigation | AnimatedTransitions |
+| micro-animations, bounce, press, stagger | MicroInteractions |
+
+**Auto-include rule:** When ANY of HapticEngine, AudioFeedback, ScrollEffects, CelebrationEffects, MicroInteractions, AnimatedTransitions, or AnimatedOnboarding is selected, **MotionPreferences is automatically added** (it provides the accessibility foundation — reduce motion support).
+
+**Visual liveliness rule:** For apps that should feel vibrant and alive (most consumer apps — shopping, social, food, fitness, travel, art, music, creative, lifestyle), automatically include **MicroInteractions** (press feedback, bounces) unless the domain explicitly demands restraint (medical, legal, finance). This ensures every app gets basic visual polish through press feedback and toggle animations.
+
+#### Step 10 — Final Module List
+
+Produce the final list of selected modules with reasoning for each.
+
+## Report Output
+
+Write the report to `output/{app-name}/reports/02-catalog-analysis.md`:
+
+```markdown
+# Catalog Analysis Report
+
+**Step:** 0
+**Skill:** catalog-analyzer
+**Timestamp:** {ISO 8601}
+**Result:** PASS
+
+## Template Selection
+
+**Selected Template:** {TemplateName}
+**Confidence:** high | medium | low
+
+### Reasoning
+
+{2-3 sentences explaining why this template was chosen}
+
+### Scoring
+
+| Template | Score | Match Criteria | Exclusions |
+|----------|-------|---------------|------------|
+| {name}   | {/10} | {matched}     | {any}      |
+
+### Hybrid Recommendation
+
+**Borrow From:** {other template name} or "none"
+**Hybrid Notes:** {what to borrow and why} or "n/a"
+
+## Module Selection — {N} total
+
+| Module | Matched Keywords | Template Boost | Reason |
+|--------|-----------------|----------------|--------|
+| {name} | {keywords}      | yes/no         | {why included} |
+...
+
+### Excluded Modules
+
+| Module | Reason for Exclusion |
+|--------|---------------------|
+...
+
+### Dependencies Added
+
+| Module | Added Because |
+|--------|--------------|
+| {name} | Required by {other module} |
+...
+```
+
+Update `output/{app-name}/reports/summary.json` — read the file, append this step.
+
+**Timing:** Record the current timestamp when you begin this skill. When writing the step entry, set `"startedAt"` to that timestamp (ISO 8601) and `"durationSeconds"` to the elapsed seconds.
+
+```json
+{
+  "step": 0,
+  "name": "catalog-analysis",
+  "startedAt": "{ISO 8601 timestamp}",
+  "durationSeconds": 0,
+  "result": "PASS",
+  "reportFile": "02-catalog-analysis.md",
+  "template": "{TemplateName}",
+  "confidence": "high|medium|low",
+  "borrowFrom": "{other template or null}",
+  "modulesSelected": {N}
+}
+```
+
+Also update the top-level `"template"` field in summary.json.
+
+## Important Rules
+
+- This skill is READ-ONLY — do NOT create, edit, or delete any app source files during this step
+- The ONLY files you write are the report files in `reports/`
+- Always recommend exactly ONE primary template
+- If confidence is "low", explain what aspects don't fit well
+- Do NOT recommend building from scratch — always pick the closest template
+- Consider the platform when relevant — all templates are available on iOS, Android, and React Native
+- For React Native, templates use TypeScript + React Navigation + custom hooks (MVVM-hook pattern)
+- Features covered by shared modules should NOT affect template scoring — they are handled in Phase 2
+- No modules are auto-included — every module must earn its place via keyword matching (exception: MotionPreferences is auto-included when any animation/sensory module is selected)
+- Aim for 5-15 modules — be selective, not exhaustive
+- Module integration happens later during customization (Steps 4-5) — this skill only produces the selection list
+- The "Relevant Templates" column is a **boost signal**, not a hard filter — a module can be selected without template match if keywords are strong

package/.cursor/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), `features/` (Android), or `src/screens/` (React Native)
 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
 
@@ -165,7 +165,7 @@ DATA REPOSITORY:
 
 ### 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:
 
 ```
 MODULE INTEGRATION PLAN:
@@ -271,6 +271,39 @@ 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 |
+| Floating element shadow | {deeper: blur Xpt, y Xpt} |
+
+#### 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} |
+| Spring response | {X}s |
+| Spring damping | {X} |
+| Stagger delay | {X}ms per item |
+| Press scale | {0.95} |
+| Button feedback | {scale + haptic (light)} |
+| Favorite toggle | {heart bounce + haptic} |
+| Success event | {confetti / sparkle / none} |
+
+#### Depth & Material
+- Sheet backgrounds: {glass blur / solid / gradient}
+- Navigation bar: {transparent+blur / solid / gradient}
+- Tab bar: {blur / solid / elevated}
+
 ### Icon Mapping — Tabs
 | Tab | Label | iOS (SF Symbol) | Android (Material) |
 |-----|-------|-----------------|-------------------|
@@ -364,11 +397,25 @@ Write the complete manifest to `output/{app-name}/reports/customization-manifest
 {List selected animation/sensory modules and their purpose in this app}
 
 ### Per-Screen Animation Modifiers
+
+**Built-in modifiers (always available, no module required):**
+- `.staggeredAppear(index:)` — staggered fade+slide for list items
+- `.slideIn()` — slide-from-bottom on appear
+- `.slideAndFade()` — slide-from-side + fade on appear
+- `.scaleOnPress()` — scale-down press feedback (0.95 + spring)
+- `.hapticFeedback()` / `.hapticFeedback(.medium)` — haptic on tap
+- `.bounceOnChange(isActive:)` — scale bounce on state toggle
+- `.cardShadow()` — subtle shadow for cards/elevated surfaces
+- `.elevatedShadow()` — deeper shadow for FABs/floating elements
+- `.shimmer()` — shimmer loading overlay for skeleton/placeholder views
+- `.pulse()` — repeating scale pulse for live indicators, notification badges
+- `.heartBounce(isActive:)` — bounce-on-activate for favorite/like buttons
+
 | Screen File | Modifiers to Apply | Notes |
 |---|---|---|
-| HomeView.swift | `.staggeredAppearance()`, `.hapticFeedback(.selection)` | List items stagger in on appear |
-| DetailView.swift | `.slideAndFade()`, `.parallaxHeader()` | Hero image parallax, content slides in |
-| CreateView.swift | `.scaleOnPress()`, `.hapticFeedback(.success)` on save | Button feedback |
+| HomeView.swift | `.staggeredAppear(index:)`, `.cardShadow()` | List items stagger in, cards have shadows |
+| DetailView.swift | `.slideAndFade()`, `.cardShadow()` | Content slides in with shadows |
+| CreateView.swift | `.scaleOnPress()`, `.hapticFeedback(.medium)` on save | Button feedback |
 | {screen} | {modifiers} | {notes} |
 ...
 

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

@@ -9,7 +9,7 @@ Use this skill to select the best visual design brand for the user's app.
 
 ## When to Use
 
-- At Step 4a of the AppAgent workflow, after the template is cloned and renamed
+- At Step 0 of the AppAgent workflow, in parallel with prompt validation and catalog analysis
 - When you need to pick a visual identity from the design brand catalog
 - Before applying design tokens to the app
 
@@ -18,7 +18,7 @@ Use this skill to select the best visual design brand for the user's app.
 - **App name** — display name (e.g., "PawSpa")
 - **App description** — what the app does and who it's for
 - **Platform** — `ios` or `android`
-- **App template** — which template was selected (e.g., "BookTemplate")
+- **App template** (optional) — which template was selected, if available (may not be when running in parallel)
 - **User style preferences** — any explicit color, style, or visual direction the user mentioned (may be empty)
 
 ## Instructions
@@ -40,6 +40,7 @@ For each brand in the catalog:
 3. Apply "NOT a match when" exclusion rules
 4. Follow the "Brand Selection Guide" decision flow
 5. Consider the "Hybrid Brands" table if the app spans categories
+6. **Energy bias**: When multiple brands score equally, prefer the one with higher Energy score (from the catalog's decision matrix). For ambiguous domains (not explicitly medical, finance, or corporate), bias toward brands with Energy >= 3. Apps should feel vibrant and alive by default — only choose low-energy brands when the domain clearly demands restraint.
 
 ### Step 3 — Handle User Style Preferences
 
@@ -59,7 +60,7 @@ Write the report to `output/{app-name}/reports/03-design-brand.md`:
 ```markdown
 # Design Brand Report
 
-**Step:** 4
+**Step:** 0
 **Skill:** design-selector
 **Timestamp:** {ISO 8601}
 **Result:** PASS
@@ -99,7 +100,7 @@ Update `output/{app-name}/reports/summary.json` — read the file, append this s
 
 ```json
 {
-  "step": 4,
+  "step": 0,
   "name": "design-brand",
   "startedAt": "{ISO 8601 timestamp}",
   "durationSeconds": 0,
@@ -121,4 +122,4 @@ Also update the top-level `"designBrand"` field in summary.json.
 - Do NOT recommend building a custom brand from scratch — always start with a catalog brand
 - If the user mentioned specific colors, put them in adaptations — never ignore user style preferences
 - The brand file path must use the exact filename from the catalog (kebab-case .md)
-- Consider the app template when relevant — a FinanceTemplate naturally pairs with CorporateProfessional, but can be overridden
+- If the app template is available, consider it as a weak hint — a FinanceTemplate naturally pairs with CorporateProfessional, but the user description keywords are the primary signal

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

@@ -9,9 +9,9 @@ Use this skill to produce a complete design brief for a newly cloned app. The pr
 
 ## When to Use
 
-- After the `design-selector` subagent has picked a brand (Step 4a complete)
-- Before AppConfig customization (Step 6) — the design brief feeds into CUSTOMIZE:THEME
-- Before the platform customizer runs (Step 8) — it applies the tokens to code
+- After the `design-selector` subagent has picked a brand (Step 0 complete)
+- Before AppConfig customization (Step 4) — the design brief feeds into CUSTOMIZE:THEME
+- Before the platform customizer runs (Step 5) — it applies the tokens to code
 
 ## What You Produce
 
@@ -39,8 +39,9 @@ If the `design-selector` provided a brand:
 3. Extract layout tokens (corner radius, spacing scale, card elevation, border width)
 4. Extract typography settings (font family, heading weight, body weight, body size)
 5. Extract icon style preferences (filled vs outlined, line weight)
-6. Note any brand-specific do's, don'ts, and overrides
-7. Note any ADAPT suggestions from the design-selector
+6. Extract **Motion & Effects** tokens (default spring, press scale, stagger delay, shadow style, gradient usage, depth approach, haptic policy)
+7. Note any brand-specific do's, don'ts, and overrides
+8. Note any ADAPT suggestions from the design-selector
 
 **If the design-selector suggested adaptations** (in the ADAPT field):
 - Apply color overrides (e.g., "shift primary to teal for pet domain")
@@ -256,7 +257,7 @@ ACCESSIBILITY:
 
 After producing the design brief, the tokens are applied to specific files in subsequent steps. All templates follow a standardized theme structure:
 
-### iOS (applied by ios-customizer in Step 8)
+### iOS (applied by ios-customizer in Step 5)
 
 | Token Category | File | Structure |
 |---------------|------|-----------|
@@ -268,7 +269,7 @@ After producing the design brief, the tokens are applied to specific files in su
 | Domain-specific colors | `Core/Theme/Colors.swift` | Semantic color tokens (e.g., `Color.incomeColor`, `Color.starFilled`) |
 | Gradient definitions | `Core/Theme/Colors.swift` | `LinearGradient` extensions |
 
-### Android (applied by android-customizer in Step 8)
+### Android (applied by android-customizer in Step 5)
 
 | Token Category | File | Structure |
 |---------------|------|-----------|