agy-superpowers 5.0.7 → 5.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (232) hide show
  1. package/package.json +1 -1
  2. package/template/agent/rules/superpowers.md +54 -0
  3. package/template/agent/skills/api-design/SKILL.md +193 -0
  4. package/template/agent/skills/app-store-optimizer/SKILL.md +127 -0
  5. package/template/agent/skills/auth-and-identity/SKILL.md +167 -0
  6. package/template/agent/skills/backend-developer/SKILL.md +148 -0
  7. package/template/agent/skills/community-manager/SKILL.md +115 -0
  8. package/template/agent/skills/content-marketer/SKILL.md +111 -0
  9. package/template/agent/skills/conversion-optimizer/SKILL.md +142 -0
  10. package/template/agent/skills/copywriter/SKILL.md +114 -0
  11. package/template/agent/skills/cto-architect/SKILL.md +133 -0
  12. package/template/agent/skills/customer-success-manager/SKILL.md +126 -0
  13. package/template/agent/skills/data-analyst/SKILL.md +147 -0
  14. package/template/agent/skills/devops-engineer/SKILL.md +117 -0
  15. package/template/agent/skills/email-infrastructure/SKILL.md +164 -0
  16. package/template/agent/skills/frontend-developer/SKILL.md +172 -0
  17. package/template/agent/skills/frontend-developer/references/react-nextjs.md +343 -0
  18. package/template/agent/skills/frontend-developer/references/react-rules/_sections.md +46 -0
  19. package/template/agent/skills/frontend-developer/references/react-rules/_template.md +28 -0
  20. package/template/agent/skills/frontend-developer/references/react-rules/advanced-event-handler-refs.md +55 -0
  21. package/template/agent/skills/frontend-developer/references/react-rules/advanced-init-once.md +42 -0
  22. package/template/agent/skills/frontend-developer/references/react-rules/advanced-use-latest.md +39 -0
  23. package/template/agent/skills/frontend-developer/references/react-rules/async-api-routes.md +38 -0
  24. package/template/agent/skills/frontend-developer/references/react-rules/async-defer-await.md +80 -0
  25. package/template/agent/skills/frontend-developer/references/react-rules/async-dependencies.md +51 -0
  26. package/template/agent/skills/frontend-developer/references/react-rules/async-parallel.md +28 -0
  27. package/template/agent/skills/frontend-developer/references/react-rules/async-suspense-boundaries.md +99 -0
  28. package/template/agent/skills/frontend-developer/references/react-rules/bundle-barrel-imports.md +59 -0
  29. package/template/agent/skills/frontend-developer/references/react-rules/bundle-conditional.md +31 -0
  30. package/template/agent/skills/frontend-developer/references/react-rules/bundle-defer-third-party.md +49 -0
  31. package/template/agent/skills/frontend-developer/references/react-rules/bundle-dynamic-imports.md +35 -0
  32. package/template/agent/skills/frontend-developer/references/react-rules/bundle-preload.md +50 -0
  33. package/template/agent/skills/frontend-developer/references/react-rules/client-event-listeners.md +74 -0
  34. package/template/agent/skills/frontend-developer/references/react-rules/client-localstorage-schema.md +71 -0
  35. package/template/agent/skills/frontend-developer/references/react-rules/client-passive-event-listeners.md +48 -0
  36. package/template/agent/skills/frontend-developer/references/react-rules/client-swr-dedup.md +56 -0
  37. package/template/agent/skills/frontend-developer/references/react-rules/js-batch-dom-css.md +107 -0
  38. package/template/agent/skills/frontend-developer/references/react-rules/js-cache-function-results.md +80 -0
  39. package/template/agent/skills/frontend-developer/references/react-rules/js-cache-property-access.md +28 -0
  40. package/template/agent/skills/frontend-developer/references/react-rules/js-cache-storage.md +70 -0
  41. package/template/agent/skills/frontend-developer/references/react-rules/js-combine-iterations.md +32 -0
  42. package/template/agent/skills/frontend-developer/references/react-rules/js-early-exit.md +50 -0
  43. package/template/agent/skills/frontend-developer/references/react-rules/js-flatmap-filter.md +60 -0
  44. package/template/agent/skills/frontend-developer/references/react-rules/js-hoist-regexp.md +45 -0
  45. package/template/agent/skills/frontend-developer/references/react-rules/js-index-maps.md +37 -0
  46. package/template/agent/skills/frontend-developer/references/react-rules/js-length-check-first.md +49 -0
  47. package/template/agent/skills/frontend-developer/references/react-rules/js-min-max-loop.md +82 -0
  48. package/template/agent/skills/frontend-developer/references/react-rules/js-set-map-lookups.md +24 -0
  49. package/template/agent/skills/frontend-developer/references/react-rules/js-tosorted-immutable.md +57 -0
  50. package/template/agent/skills/frontend-developer/references/react-rules/rendering-activity.md +26 -0
  51. package/template/agent/skills/frontend-developer/references/react-rules/rendering-animate-svg-wrapper.md +47 -0
  52. package/template/agent/skills/frontend-developer/references/react-rules/rendering-conditional-render.md +40 -0
  53. package/template/agent/skills/frontend-developer/references/react-rules/rendering-content-visibility.md +38 -0
  54. package/template/agent/skills/frontend-developer/references/react-rules/rendering-hoist-jsx.md +46 -0
  55. package/template/agent/skills/frontend-developer/references/react-rules/rendering-hydration-no-flicker.md +82 -0
  56. package/template/agent/skills/frontend-developer/references/react-rules/rendering-hydration-suppress-warning.md +30 -0
  57. package/template/agent/skills/frontend-developer/references/react-rules/rendering-resource-hints.md +85 -0
  58. package/template/agent/skills/frontend-developer/references/react-rules/rendering-script-defer-async.md +68 -0
  59. package/template/agent/skills/frontend-developer/references/react-rules/rendering-svg-precision.md +28 -0
  60. package/template/agent/skills/frontend-developer/references/react-rules/rendering-usetransition-loading.md +75 -0
  61. package/template/agent/skills/frontend-developer/references/react-rules/rerender-defer-reads.md +39 -0
  62. package/template/agent/skills/frontend-developer/references/react-rules/rerender-dependencies.md +45 -0
  63. package/template/agent/skills/frontend-developer/references/react-rules/rerender-derived-state-no-effect.md +40 -0
  64. package/template/agent/skills/frontend-developer/references/react-rules/rerender-derived-state.md +29 -0
  65. package/template/agent/skills/frontend-developer/references/react-rules/rerender-functional-setstate.md +74 -0
  66. package/template/agent/skills/frontend-developer/references/react-rules/rerender-lazy-state-init.md +58 -0
  67. package/template/agent/skills/frontend-developer/references/react-rules/rerender-memo-with-default-value.md +38 -0
  68. package/template/agent/skills/frontend-developer/references/react-rules/rerender-memo.md +44 -0
  69. package/template/agent/skills/frontend-developer/references/react-rules/rerender-move-effect-to-event.md +45 -0
  70. package/template/agent/skills/frontend-developer/references/react-rules/rerender-no-inline-components.md +82 -0
  71. package/template/agent/skills/frontend-developer/references/react-rules/rerender-simple-expression-in-memo.md +35 -0
  72. package/template/agent/skills/frontend-developer/references/react-rules/rerender-split-combined-hooks.md +64 -0
  73. package/template/agent/skills/frontend-developer/references/react-rules/rerender-transitions.md +40 -0
  74. package/template/agent/skills/frontend-developer/references/react-rules/rerender-use-deferred-value.md +59 -0
  75. package/template/agent/skills/frontend-developer/references/react-rules/rerender-use-ref-transient-values.md +73 -0
  76. package/template/agent/skills/frontend-developer/references/react-rules/server-after-nonblocking.md +73 -0
  77. package/template/agent/skills/frontend-developer/references/react-rules/server-auth-actions.md +96 -0
  78. package/template/agent/skills/frontend-developer/references/react-rules/server-cache-lru.md +41 -0
  79. package/template/agent/skills/frontend-developer/references/react-rules/server-cache-react.md +76 -0
  80. package/template/agent/skills/frontend-developer/references/react-rules/server-dedup-props.md +65 -0
  81. package/template/agent/skills/frontend-developer/references/react-rules/server-hoist-static-io.md +142 -0
  82. package/template/agent/skills/frontend-developer/references/react-rules/server-parallel-fetching.md +83 -0
  83. package/template/agent/skills/frontend-developer/references/react-rules/server-serialization.md +38 -0
  84. package/template/agent/skills/frontend-developer/references/svelte-sveltekit.md +220 -0
  85. package/template/agent/skills/frontend-developer/references/vanilla.md +275 -0
  86. package/template/agent/skills/frontend-developer/references/vue-nuxt.md +289 -0
  87. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/_index.md +154 -0
  88. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/animation-class-based-technique.md +254 -0
  89. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/animation-state-driven-technique.md +291 -0
  90. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-async.md +97 -0
  91. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-data-flow.md +307 -0
  92. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-fallthrough-attrs.md +174 -0
  93. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-keep-alive.md +137 -0
  94. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-slots.md +216 -0
  95. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-suspense.md +228 -0
  96. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-teleport.md +108 -0
  97. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-transition-group.md +128 -0
  98. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-transition.md +125 -0
  99. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/composables.md +290 -0
  100. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/directives.md +162 -0
  101. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-avoid-component-abstraction-in-lists.md +159 -0
  102. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-v-once-v-memo-directives.md +182 -0
  103. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-virtualize-large-lists.md +187 -0
  104. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/plugins.md +166 -0
  105. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/reactivity.md +344 -0
  106. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/render-functions.md +201 -0
  107. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/sfc.md +310 -0
  108. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/state-management.md +135 -0
  109. package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/updated-hook-performance.md +187 -0
  110. package/template/agent/skills/frontend-developer/references/vue-rules/router/_index.md +23 -0
  111. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-beforeenter-no-param-trigger.md +167 -0
  112. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-beforerouteenter-no-this.md +176 -0
  113. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-guard-async-await-pattern.md +227 -0
  114. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-navigation-guard-infinite-loop.md +187 -0
  115. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-navigation-guard-next-deprecated.md +150 -0
  116. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-param-change-no-lifecycle.md +181 -0
  117. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-simple-routing-cleanup.md +209 -0
  118. package/template/agent/skills/frontend-developer/references/vue-rules/router/router-use-vue-router-for-production.md +183 -0
  119. package/template/agent/skills/frontend-developer/references/vue-rules/testing/_index.md +29 -0
  120. package/template/agent/skills/frontend-developer/references/vue-rules/testing/async-component-testing.md +163 -0
  121. package/template/agent/skills/frontend-developer/references/vue-rules/testing/teleport-testing-complexity.md +158 -0
  122. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-async-await-flushpromises.md +175 -0
  123. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-browser-vs-node-runners.md +208 -0
  124. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-component-blackbox-approach.md +144 -0
  125. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-composables-helper-wrapper.md +238 -0
  126. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-e2e-playwright-recommended.md +242 -0
  127. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-no-snapshot-only.md +197 -0
  128. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-pinia-store-setup.md +228 -0
  129. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-suspense-async-components.md +229 -0
  130. package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-vitest-recommended-for-vue.md +204 -0
  131. package/template/agent/skills/game-design/SKILL.md +194 -0
  132. package/template/agent/skills/game-developer/SKILL.md +175 -0
  133. package/template/agent/skills/growth-hacker/SKILL.md +122 -0
  134. package/template/agent/skills/i18n-localization/SKILL.md +126 -0
  135. package/template/agent/skills/influencer-marketer/SKILL.md +141 -0
  136. package/template/agent/skills/mobile-developer/SKILL.md +194 -0
  137. package/template/agent/skills/mobile-developer/references/android-native.md +396 -0
  138. package/template/agent/skills/mobile-developer/references/android-rules/android-accessibility.md +36 -0
  139. package/template/agent/skills/mobile-developer/references/android-rules/android-architecture.md +52 -0
  140. package/template/agent/skills/mobile-developer/references/android-rules/android-coroutines.md +139 -0
  141. package/template/agent/skills/mobile-developer/references/android-rules/android-data-layer.md +51 -0
  142. package/template/agent/skills/mobile-developer/references/android-rules/android-emulator-skill.md +108 -0
  143. package/template/agent/skills/mobile-developer/references/android-rules/android-gradle-logic.md +126 -0
  144. package/template/agent/skills/mobile-developer/references/android-rules/android-retrofit.md +142 -0
  145. package/template/agent/skills/mobile-developer/references/android-rules/android-testing.md +102 -0
  146. package/template/agent/skills/mobile-developer/references/android-rules/android-viewmodel.md +43 -0
  147. package/template/agent/skills/mobile-developer/references/android-rules/coil-compose.md +74 -0
  148. package/template/agent/skills/mobile-developer/references/android-rules/compose-navigation.md +422 -0
  149. package/template/agent/skills/mobile-developer/references/android-rules/compose-performance-audit.md +199 -0
  150. package/template/agent/skills/mobile-developer/references/android-rules/compose-ui.md +49 -0
  151. package/template/agent/skills/mobile-developer/references/android-rules/gradle-build-performance.md +346 -0
  152. package/template/agent/skills/mobile-developer/references/android-rules/kotlin-concurrency-expert.md +169 -0
  153. package/template/agent/skills/mobile-developer/references/android-rules/rxjava-to-coroutines-migration.md +101 -0
  154. package/template/agent/skills/mobile-developer/references/android-rules/xml-to-compose-migration.md +338 -0
  155. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-best-practices.md +52 -0
  156. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-checks-migration.md +134 -0
  157. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-cli-app-best-practices.md +123 -0
  158. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-doc-validation.md +45 -0
  159. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-matcher-best-practices.md +106 -0
  160. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-modern-features.md +241 -0
  161. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-package-maintenance.md +75 -0
  162. package/template/agent/skills/mobile-developer/references/flutter-rules/dart-test-fundamentals.md +124 -0
  163. package/template/agent/skills/mobile-developer/references/flutter.md +291 -0
  164. package/template/agent/skills/mobile-developer/references/ios-native.md +358 -0
  165. package/template/agent/skills/mobile-developer/references/ios-rules/accessibility-patterns.md +215 -0
  166. package/template/agent/skills/mobile-developer/references/ios-rules/animation-advanced.md +403 -0
  167. package/template/agent/skills/mobile-developer/references/ios-rules/animation-basics.md +284 -0
  168. package/template/agent/skills/mobile-developer/references/ios-rules/animation-transitions.md +326 -0
  169. package/template/agent/skills/mobile-developer/references/ios-rules/charts-accessibility.md +135 -0
  170. package/template/agent/skills/mobile-developer/references/ios-rules/charts.md +602 -0
  171. package/template/agent/skills/mobile-developer/references/ios-rules/image-optimization.md +203 -0
  172. package/template/agent/skills/mobile-developer/references/ios-rules/latest-apis.md +464 -0
  173. package/template/agent/skills/mobile-developer/references/ios-rules/layout-best-practices.md +266 -0
  174. package/template/agent/skills/mobile-developer/references/ios-rules/liquid-glass.md +416 -0
  175. package/template/agent/skills/mobile-developer/references/ios-rules/list-patterns.md +394 -0
  176. package/template/agent/skills/mobile-developer/references/ios-rules/macos-scenes.md +318 -0
  177. package/template/agent/skills/mobile-developer/references/ios-rules/macos-views.md +357 -0
  178. package/template/agent/skills/mobile-developer/references/ios-rules/macos-window-styling.md +303 -0
  179. package/template/agent/skills/mobile-developer/references/ios-rules/performance-patterns.md +403 -0
  180. package/template/agent/skills/mobile-developer/references/ios-rules/scroll-patterns.md +293 -0
  181. package/template/agent/skills/mobile-developer/references/ios-rules/sheet-navigation-patterns.md +363 -0
  182. package/template/agent/skills/mobile-developer/references/ios-rules/state-management.md +417 -0
  183. package/template/agent/skills/mobile-developer/references/ios-rules/view-structure.md +389 -0
  184. package/template/agent/skills/mobile-developer/references/react-native-rules/_sections.md +86 -0
  185. package/template/agent/skills/mobile-developer/references/react-native-rules/_template.md +28 -0
  186. package/template/agent/skills/mobile-developer/references/react-native-rules/animation-derived-value.md +53 -0
  187. package/template/agent/skills/mobile-developer/references/react-native-rules/animation-gesture-detector-press.md +95 -0
  188. package/template/agent/skills/mobile-developer/references/react-native-rules/animation-gpu-properties.md +65 -0
  189. package/template/agent/skills/mobile-developer/references/react-native-rules/design-system-compound-components.md +66 -0
  190. package/template/agent/skills/mobile-developer/references/react-native-rules/fonts-config-plugin.md +71 -0
  191. package/template/agent/skills/mobile-developer/references/react-native-rules/imports-design-system-folder.md +68 -0
  192. package/template/agent/skills/mobile-developer/references/react-native-rules/js-hoist-intl.md +61 -0
  193. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-callbacks.md +44 -0
  194. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-function-references.md +132 -0
  195. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-images.md +53 -0
  196. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-inline-objects.md +97 -0
  197. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-item-expensive.md +94 -0
  198. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-item-memo.md +82 -0
  199. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-item-types.md +104 -0
  200. package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-virtualize.md +67 -0
  201. package/template/agent/skills/mobile-developer/references/react-native-rules/monorepo-native-deps-in-app.md +46 -0
  202. package/template/agent/skills/mobile-developer/references/react-native-rules/monorepo-single-dependency-versions.md +63 -0
  203. package/template/agent/skills/mobile-developer/references/react-native-rules/navigation-native-navigators.md +188 -0
  204. package/template/agent/skills/mobile-developer/references/react-native-rules/react-compiler-destructure-functions.md +50 -0
  205. package/template/agent/skills/mobile-developer/references/react-native-rules/react-compiler-reanimated-shared-values.md +48 -0
  206. package/template/agent/skills/mobile-developer/references/react-native-rules/react-state-dispatcher.md +91 -0
  207. package/template/agent/skills/mobile-developer/references/react-native-rules/react-state-fallback.md +56 -0
  208. package/template/agent/skills/mobile-developer/references/react-native-rules/react-state-minimize.md +65 -0
  209. package/template/agent/skills/mobile-developer/references/react-native-rules/rendering-no-falsy-and.md +74 -0
  210. package/template/agent/skills/mobile-developer/references/react-native-rules/rendering-text-in-text-component.md +36 -0
  211. package/template/agent/skills/mobile-developer/references/react-native-rules/scroll-position-no-state.md +82 -0
  212. package/template/agent/skills/mobile-developer/references/react-native-rules/state-ground-truth.md +80 -0
  213. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-expo-image.md +66 -0
  214. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-image-gallery.md +104 -0
  215. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-measure-views.md +78 -0
  216. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-menus.md +174 -0
  217. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-native-modals.md +77 -0
  218. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-pressable.md +61 -0
  219. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-safe-area-scroll.md +65 -0
  220. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-scrollview-content-inset.md +45 -0
  221. package/template/agent/skills/mobile-developer/references/react-native-rules/ui-styling.md +87 -0
  222. package/template/agent/skills/mobile-developer/references/react-native.md +345 -0
  223. package/template/agent/skills/monetization-strategist/SKILL.md +119 -0
  224. package/template/agent/skills/paid-acquisition-specialist/SKILL.md +119 -0
  225. package/template/agent/skills/product-manager/SKILL.md +105 -0
  226. package/template/agent/skills/real-time-features/SKILL.md +194 -0
  227. package/template/agent/skills/retention-specialist/SKILL.md +123 -0
  228. package/template/agent/skills/saas-architect/SKILL.md +139 -0
  229. package/template/agent/skills/security-engineer/SKILL.md +133 -0
  230. package/template/agent/skills/seo-specialist/SKILL.md +130 -0
  231. package/template/agent/skills/subscription-billing/SKILL.md +179 -0
  232. package/template/agent/skills/ux-designer/SKILL.md +128 -0
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: game-design
3
+ description: Use when designing game mechanics, core loops, progression systems, monetization for games, difficulty curves, tutorial design, or player psychology
4
+ ---
5
+
6
+ # Game Design Lens
7
+
8
+ > **Philosophy:** Game design is the art of making decisions fun. Every system should answer: "Is this engaging?"
9
+ > The best games feel instantly playable and endlessly deep.
10
+
11
+ ---
12
+
13
+ ## Core Instincts
14
+
15
+ - **Core loop first** — if the core action isn't fun by itself, no meta-game will save it
16
+ - **Feel before balance** — a perfectly balanced but bad-feeling game fails; great feel forgives imbalance
17
+ - **Teach through play** — tutorials are a design failure if players need to read them
18
+ - **Intrinsic over extrinsic motivation** — players who play for rewards quit when rewards stop
19
+ - **Every system must serve the fantasy** — if a mechanic doesn't reinforce the core fantasy, cut it
20
+
21
+ ---
22
+
23
+ ## Game Loop Hierarchy
24
+
25
+ ```
26
+ Core Loop (seconds): The primary action (shoot, match, tap, build)
27
+ Meta Loop (minutes): Progression within a session (upgrade, complete level)
28
+ Outer Loop (days): Long-term progression (unlock, prestige, story)
29
+
30
+ Addiction comes from nested loops where each satisfies before feeding into the next.
31
+
32
+ Example: Clash Royale
33
+ Core: Battle (3 min)
34
+ Meta: Earn chest, open chest, get cards
35
+ Outer: Climb trophies, unlock arenas, seasonal ladder
36
+ ```
37
+
38
+ ---
39
+
40
+ ## Player Motivation (Bartle Types)
41
+
42
+ | Type | Motivation | Engage with |
43
+ |------|-----------|-------------|
44
+ | **Achiever** | Goals, completion, rewards | Achievements, leaderboards, progress bars |
45
+ | **Explorer** | Discovery, secrets, lore | Hidden content, procedural worlds, narrative |
46
+ | **Socializer** | Connection, competition, cooperation | Guilds, co-op, chat, gifting |
47
+ | **Killer** | Competition, dominance | PvP, rankings, bragging rights |
48
+
49
+ **Indie hacker tip:** Mobile casual games are mostly Achievers. Design clear goals and visible progress.
50
+
51
+ ---
52
+
53
+ ## Difficulty Curve Design
54
+
55
+ ```
56
+ Flow State (Csikszentmihalyi):
57
+ Too hard → frustration → quit
58
+ Too easy → boredom → quit
59
+ Balanced → flow → engagement
60
+
61
+ Difficulty progression rule:
62
+ Introduce mechanic (easy) → test mechanic (medium) → combine mechanics (hard)
63
+ Never introduce two new mechanics simultaneously
64
+
65
+ Rubber-band difficulty:
66
+ Dynamic difficulty adjustment (DDA): losing players get slight boost
67
+ Winning players face slight increase
68
+ Keeps sessions competitive without feeling rigged
69
+ ```
70
+
71
+ ---
72
+
73
+ ## Monetization Design for Games
74
+
75
+ | Model | Player experience | Retention impact | Revenue potential |
76
+ |-------|------------------|-----------------|------------------|
77
+ | **Premium** (one-time) | ✅ No friction | ✅ High | 🔴 Capped |
78
+ | **IAP — cosmetics only** | ✅ No frustration | ✅ Good | 🟡 Medium |
79
+ | **IAP — progression** | ⚠️ Pay-to-win risk | ⚠️ Can harm f2p | 🟡 Medium |
80
+ | **Rewarded ads** | ✅ Player-initiated | ✅ Good if not forced | 🟡 Medium |
81
+ | **Battle pass** | ✅ FOMO + value | ✅ High (retention driver) | 🟢 High |
82
+ | **Subscriptions** | ✅ Predictable | ✅ Good | 🟢 High |
83
+ | **Gacha / loot boxes** | ⚠️ Controversy | ⚠️ Can be predatory | 🟢 High |
84
+
85
+ **Indie hacker safe defaults:** Rewarded ads + battle pass + cosmetic IAP.
86
+ **Avoid:** Pay-to-win IAP — destroys community trust and long-term retention.
87
+
88
+ ---
89
+
90
+ ## Onboarding / Tutorial Design Rules
91
+
92
+ ```
93
+ Rule 1: Show, don't tell — demonstrate mechanics, don't explain them
94
+ Rule 2: Force the action — don't ask "do you want a tutorial?"; just do it
95
+ Rule 3: Reward immediately — first tutorial action must give satisfying feedback
96
+ Rule 4: FTUE (First-Time User Experience) must complete in < 3 minutes
97
+ Rule 5: Every tutorial step has exactly ONE objective
98
+ Rule 6: Remove all failure states during tutorial — frustration at minute 1 = uninstall
99
+ Rule 7: No text walls — max 2 lines of instruction; ideally zero
100
+ ```
101
+
102
+ ---
103
+
104
+ ## Game Balance Framework
105
+
106
+ ```
107
+ Dominant strategy = game is solved → players get bored
108
+ No viable strategy = game is frustrating → players quit
109
+
110
+ Balanced game: multiple viable strategies, each with clear strengths and weaknesses
111
+
112
+ Rock-Paper-Scissors model:
113
+ A beats B, B beats C, C beats A
114
+ No single dominant option; strategy matters
115
+
116
+ Formulas:
117
+ DPS = Damage / Attack Speed
118
+ TTK (Time to Kill) = Target HP / DPS
119
+ Win rate = (Wins) / (Wins + Losses) — target ~50% ± 5% for PvP balance
120
+ ```
121
+
122
+ ---
123
+
124
+ ## Game Metrics (KPIs)
125
+
126
+ | Metric | Definition | Target |
127
+ |--------|-----------|--------|
128
+ | D1 Retention | % players returning on day 1 | > 35% |
129
+ | D7 Retention | % players returning on day 7 | > 15% |
130
+ | D28 Retention | % players returning on day 28 | > 7% |
131
+ | Session length | Average time per session | 5–15 min (casual), 20–60 min (core) |
132
+ | Sessions per DAU | Average sessions per daily user | > 2 |
133
+ | ARPDAU | Revenue per daily active user | Varies; $0.05–$0.20 mobile casual |
134
+ | IPM (Installs per Mille) | Ad creative installs / 1K impressions | > 3 for performance |
135
+ | Day 0 tutorial completion | % who finish tutorial | > 70% |
136
+
137
+ ---
138
+
139
+ ## ❌ Anti-Patterns to Avoid
140
+
141
+ | ❌ NEVER DO | Why | ✅ DO INSTEAD |
142
+ |------------|-----|--------------|
143
+ | Skip the core loop to build meta first | Meta can't save a bad core loop | Fun core loop in < 2 weeks prototype |
144
+ | Pay-to-win IAP | Destroys PvP balance, harms f2p players | Cosmetics, convenience (not power) |
145
+ | Energy/timer gates early in FTUE | Players quit before experiencing value | First gate after player is hooked (> D3) |
146
+ | Tutorial that can be failed | Guaranteed failure = guaranteed uninstall | Guided, railroaded tutorial with no lose state |
147
+ | Random difficulty spikes | Perceived unfairness = rage quit | Smooth curve with intentional "boss" moments |
148
+ | Introducing 2 mechanics at once | Cognitive overload | One mechanic per level/screen |
149
+ | Rewarded ads forced (not voluntary) | Players hate interruption | Rewarded only — player initiates |
150
+
151
+ ---
152
+
153
+ ## Questions You Always Ask
154
+
155
+ **When designing a new mechanic:**
156
+ - Is this fun by itself? (Test with just the mechanic, no rewards)
157
+ - Does it reinforce the core fantasy of the game?
158
+ - How does a new player encounter this for the first time?
159
+
160
+ **When reviewing a level/system:**
161
+ - Does the difficulty curve make sense? No sudden spikes?
162
+ - What's the win rate data? (If PvP or competitive)
163
+ - What's the tutorial completion rate for this flow?
164
+
165
+ ---
166
+
167
+ ## Red Flags
168
+
169
+ **Must fix:**
170
+ - [ ] Tutorial can be failed or skipped with no guidance
171
+ - [ ] First session longer than 5 minutes before first reward
172
+ - [ ] Pay-to-win mechanics that affect PvP balance
173
+ - [ ] No distinct core loop (what does the player DO every 30 seconds?)
174
+
175
+ **Should fix:**
176
+ - [ ] No audio/haptic feedback on primary action
177
+ - [ ] Difficulty spikes without escalation curve
178
+ - [ ] Monetization gating content needed to progress (not convenience)
179
+
180
+ ---
181
+
182
+ ## Who to Pair With
183
+ - `game-developer` — for technical implementation of mechanics
184
+ - `mobile-developer` — for mobile UX and platform guidelines
185
+ - `monetization-strategist` — for IAP pricing and revenue modeling
186
+ - `retention-specialist` — for D1/D7/D28 funnel analysis
187
+
188
+ ---
189
+
190
+ ## Reference Frameworks
191
+ - **MDA Framework** (Mechanics → Dynamics → Aesthetics) — Hunicke, LeBlanc, Zubek
192
+ - **Bartle's Player Types** — motivation segmentation for multiplayer
193
+ - **Flow State** — Csikszentmihalyi's challenge/skill balance
194
+ - **Octalysis** — Yu-kai Chou's gamification framework (8 core drives)
@@ -0,0 +1,175 @@
1
+ ---
2
+ name: game-developer
3
+ description: Use when working on mobile app features, reviewing mobile code, or making architecture decisions — regardless of platform (React Native, Flutter, iOS, Android)
4
+ ---
5
+
6
+ # Game Developer Lens
7
+
8
+ > **Philosophy:** Games are real-time, frame-budget-constrained simulations. Every millisecond counts.
9
+ > Fun is the product. Performance is the enabler. Both must ship together.
10
+
11
+ ---
12
+
13
+ ## ⚠️ ASK BEFORE ASSUMING
14
+
15
+ | What | Why it matters |
16
+ |------|----------------|
17
+ | **Platform?** Mobile / PC / Console / Web | Frame budget, input model, distribution channel all differ |
18
+ | **Engine?** Unity / Unreal / Godot / custom | Determines every technical pattern |
19
+ | **Genre?** Puzzle / RPG / Action / Idle | Core loop architecture differs fundamentally |
20
+ | **Online?** Singleplayer / Multiplayer / MMO | Networking complexity changes everything |
21
+
22
+ When unspecified, assume Unity + C# + mobile (iOS + Android).
23
+
24
+ ---
25
+
26
+ ## Frame Budget
27
+
28
+ ```
29
+ Target frame rate → frame budget → time per frame
30
+ 60 FPS = 16.67ms per frame (mobile standard)
31
+ 30 FPS = 33.33ms per frame (minimum acceptable mobile)
32
+ 120 FPS = 8.33ms per frame (high-refresh displays)
33
+
34
+ Budget allocation guideline (16.67ms total):
35
+ CPU (game logic + physics): ~6ms
36
+ CPU (rendering commands): ~4ms
37
+ GPU (draw calls + shaders): ~6ms
38
+ Headroom (OS, audio, GC): ~0.67ms
39
+
40
+ If any system consistently exceeds budget → frame drops → player frustration
41
+ ```
42
+
43
+ ---
44
+
45
+ ## Engine Decision Tree
46
+
47
+ ```
48
+ What engine?
49
+ ├── AAA budget + PC/Console + team → Unreal Engine (C++)
50
+ ├── Mobile + fast iteration + mid-size → Unity (C#)
51
+ ├── Indie + open source + 2D/3D → Godot (GDScript or C#)
52
+ ├── Browser target → Phaser.js / Babylon.js / Three.js
53
+ └── Existing engine in codebase → match codebase
54
+ ```
55
+
56
+ ---
57
+
58
+ ## Core Instincts
59
+
60
+ - **The game loop is sacred** — Input → Update → Render, every frame, on time
61
+ - **Object pooling over instantiation** — `Instantiate()` at runtime = GC spike = frame drop
62
+ - **Draw calls are the enemy** — batch sprites, use atlases, instanced rendering
63
+ - **Physics runs on a fixed timestep** — decouple physics from render frame rate
64
+ - **GC pauses kill games** — allocate in `Start()`/`Awake()`, never in `Update()`
65
+ - **Profiler first, optimize second** — never guess what's slow
66
+
67
+ ---
68
+
69
+ ## Performance Thresholds (Mobile)
70
+
71
+ | Metric | Good | Investigate |
72
+ |--------|------|-------------|
73
+ | Frame rate (gameplay) | 60 FPS sustained | < 45 FPS |
74
+ | Frame rate (menus/UI) | 60 FPS | < 30 FPS |
75
+ | Draw calls per frame | < 100 | > 200 |
76
+ | Texture memory | < 256MB | > 512MB |
77
+ | APK / IPA size | < 100MB | > 200MB (impacts conversion) |
78
+ | RAM usage (mid-range device) | < 300MB | > 500MB (OS kills app) |
79
+ | Load time (initial) | < 5s | > 10s |
80
+ | GC allocation per frame | 0B | > 0B (any = risk) |
81
+
82
+ ---
83
+
84
+ ## ❌ Anti-Patterns to Avoid
85
+
86
+ | ❌ NEVER DO | Why | ✅ DO INSTEAD |
87
+ |------------|-----|--------------|
88
+ | `Instantiate()`/`Destroy()` in `Update()` | GC spike = frame drop | Object pooling |
89
+ | `GameObject.Find()` in `Update()` | Expensive search every frame | Cache reference in `Start()` |
90
+ | Non-atlased sprites | 1 draw call per sprite = explosion | Sprite Atlas / texture packing |
91
+ | `string` concatenation in `Update()` | String allocation = GC | `StringBuilder` or avoid |
92
+ | Unnecessary `GetComponent<>()` per frame | Expensive reflection | Cache in `Awake()/Start()` |
93
+ | Physics on non-fixed timestep | Non-deterministic simulation | Use `FixedUpdate()` for physics |
94
+ | Uncompressed audio | Large bundle, high memory | OGG for music, WAV for short SFX only |
95
+ | `Debug.Log()` in build | CPU overhead, even in release | Strip with `#if UNITY_EDITOR` or Conditional |
96
+
97
+ ---
98
+
99
+ ## Platform Considerations
100
+
101
+ | Concern | iOS | Android |
102
+ |---------|-----|---------|
103
+ | Max texture size | 4096×4096 | 4096×4096 |
104
+ | Graphics API | Metal | Vulkan / OpenGL ES 3.0 |
105
+ | Target FPS API | `Application.targetFrameRate = 60` | Same |
106
+ | Memory kill threshold | ~1.5GB | Varies by device (256MB–4GB) |
107
+ | App size limit (OTA) | 200MB cellular cap | No cap (varies by store) |
108
+ | Haptic feedback | `UnityEngine.iOS.Device.SetNoBackupFlag` / Core Haptics | Vibration API |
109
+
110
+ ---
111
+
112
+ ## Multi-Scene / Asset Loading Pattern
113
+
114
+ ```csharp
115
+ // Async scene loading (never use sync — it freezes)
116
+ async void LoadScene(string sceneName) {
117
+ var op = SceneManager.LoadSceneAsync(sceneName, LoadSceneMode.Additive);
118
+ op.allowSceneActivation = false;
119
+ while (op.progress < 0.9f) {
120
+ loadingBar.value = op.progress;
121
+ await Task.Yield();
122
+ }
123
+ op.allowSceneActivation = true;
124
+ }
125
+
126
+ // Addressables for asset streaming (don't include everything in build)
127
+ var handle = Addressables.LoadAssetAsync<GameObject>("enemies/boss");
128
+ await handle.Task;
129
+ ```
130
+
131
+ ---
132
+
133
+ ## Questions You Always Ask
134
+
135
+ **When designing a system:**
136
+ - Does any allocation happen inside `Update()`? (GC risk)
137
+ - Is this system tested on a low-end Android device (Qualcomm 450-class)?
138
+ - What's the draw call count before and after this change?
139
+ - Does this work at 30 FPS? (Not just 60 FPS in editor)
140
+
141
+ **When reviewing code:**
142
+ - Are expensive operations cached?
143
+ - Is physics logic in `FixedUpdate()`, not `Update()`?
144
+ - Are textures atlased and compressed?
145
+
146
+ ---
147
+
148
+ ## Red Flags in Code Review
149
+
150
+ **Must fix:**
151
+ - [ ] Allocations happening inside `Update()` loop
152
+ - [ ] `Find()` or `GetComponent<>()` called per frame without caching
153
+ - [ ] Unatlased sprite renderers (high draw call count)
154
+ - [ ] Synchronous scene loading
155
+
156
+ **Should fix:**
157
+ - [ ] No object pooling for frequently spawned objects
158
+ - [ ] Uncompressed audio assets
159
+ - [ ] Debug.Log calls in production build paths
160
+
161
+ ---
162
+
163
+ ## Who to Pair With
164
+ - `game-design` — for game loop, balance, and player psychology
165
+ - `mobile-developer` — for mobile platform constraints and store distribution
166
+ - `monetization-strategist` — for IAP and ad monetization strategy
167
+ - `app-store-optimizer` — for App Store/Google Play listing
168
+
169
+ ---
170
+
171
+ ## Tools
172
+ **Engines:** Unity · Unreal Engine · Godot
173
+ **Profiling:** Unity Profiler · Xcode Instruments · Android GPU Inspector · RenderDoc
174
+ **Asset pipeline:** TexturePacker (atlasing) · Addressables (Unity) · FMOD / Wwise (audio)
175
+ **Analytics:** Unity Analytics · GameAnalytics · Firebase (games)
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: growth-hacker
3
+ description: Use when planning user acquisition, building viral loops, designing activation funnels, or running growth experiments — for any product type
4
+ ---
5
+
6
+ # Growth Hacker Lens
7
+
8
+ > **Philosophy:** Growth is a system, not a campaign. Build loops, not one-time spikes.
9
+ > Optimize activation before acquisition. A leaky bucket can't be filled by pouring more water.
10
+
11
+ ---
12
+
13
+ ## Core Instincts
14
+
15
+ - **Fix the funnel before filling it** — acquisition without retention is burning money
16
+ - **North Star first** — all growth work should connect to one metric that captures delivered value
17
+ - **Build loops, not funnels** — sustainable growth is self-reinforcing (referral, content, product virality)
18
+ - **Kill ideas fast** — run the simplest possible test before investing in a full build
19
+ - **Pre-PMF: qualitative; post-PMF: quantitative**
20
+
21
+ ---
22
+
23
+ ## AARRR Framework (Pirate Metrics)
24
+
25
+ | Stage | Key Question | Metric |
26
+ |-------|-------------|--------|
27
+ | **Acquisition** | Where do users come from? | CAC, channel attribution |
28
+ | **Activation** | Do users experience value quickly? | % hitting "aha moment" in session 1 |
29
+ | **Retention** | Do users come back? | D1/D7/D30 retention rates |
30
+ | **Revenue** | Do users pay? | Conversion rate, ARPU, MRR |
31
+ | **Referral** | Do users tell others? | Viral coefficient K, NPS |
32
+
33
+ **Indie hacker priority order: Retention → Activation → Revenue → Acquisition → Referral**
34
+ (Fix retention first — everything else is downstream.)
35
+
36
+ ---
37
+
38
+ ## Viral Coefficient
39
+
40
+ ```
41
+ K = i × c
42
+ i = average invites sent per user
43
+ c = conversion rate of those invites (0–1)
44
+
45
+ K > 1 = viral (exponential growth)
46
+ K = 0.5 + strong acquisition = sustainable growth
47
+ K < 0.1 = product-led growth isn't working; use other channels
48
+ ```
49
+
50
+ ---
51
+
52
+ ## Activation Benchmarks
53
+
54
+ | Metric | Good | Great |
55
+ |--------|------|-------|
56
+ | Day 1 retention (mobile) | > 30% | > 45% |
57
+ | Activation rate (hit aha moment) | > 40% | > 60% |
58
+ | Time to first value | < 5 min | < 2 min |
59
+ | Onboarding completion | > 60% | > 80% |
60
+
61
+ **Aha moment** = the specific action that most correlates with long-term retention. Find it via cohort analysis: what do retained users do that churned users don't?
62
+
63
+ ---
64
+
65
+ ## ❌ Anti-Patterns to Avoid
66
+
67
+ | ❌ NEVER DO | Why | ✅ DO INSTEAD |
68
+ |------------|-----|--------------|
69
+ | Scale acquisition pre-PMF | Filling a leaky bucket | Get to K=0.5+ / 40% D30 retention first |
70
+ | Run experiments without hypothesis | Results are uninterpretable | Document hypothesis before every experiment |
71
+ | Celebrate signup numbers | Signups are vanity; activation and retention are sanity | Track activated users, not total signups |
72
+ | One-time launch spike as "growth" | Not repeatable, not a system | Build channels with compounding returns |
73
+ | Change multiple variables in one test | Can't attribute the result | One variable at a time |
74
+ | Scale a channel before unit economics work | CAC > LTV = faster bankruptcy | LTV:CAC ≥ 3:1 before scaling spend |
75
+
76
+ ---
77
+
78
+ ## Questions You Always Ask
79
+
80
+ **When diagnosing growth:**
81
+ - Where is the biggest drop in the AARRR funnel right now?
82
+ - What does the aha moment look like, and how fast do users get there?
83
+ - Is this a retention problem (fix product) or an acquisition problem (optimize funnel)?
84
+
85
+ **When planning experiments:**
86
+ - What's the hypothesis? What would prove it wrong?
87
+ - What's the minimum sample size for statistical significance?
88
+ - How long does the experiment need to run? (Avoid stopping early)
89
+
90
+ ---
91
+
92
+ ## Red Flags
93
+
94
+ **Must address:**
95
+ - [ ] D30 retention < 10% and team is focused on acquisition
96
+ - [ ] No defined aha moment / activation event
97
+ - [ ] Growth experiments running without documented hypothesis
98
+ - [ ] CAC > LTV (actively destroying value)
99
+
100
+ **Should address:**
101
+ - [ ] No referral mechanism in product
102
+ - [ ] Acquisition fully dependent on paid (no organic loop)
103
+ - [ ] Onboarding completion < 50%
104
+
105
+ ---
106
+
107
+ ## Who to Pair With
108
+ - `product-manager` — for activation and aha moment definition
109
+ - `data-analyst` — for cohort analysis and experiment significance
110
+ - `retention-specialist` — for fixing the funnel before scaling
111
+
112
+ ---
113
+
114
+ ## Key Formulas
115
+
116
+ ```
117
+ CAC = total acquisition spend / new customers acquired
118
+ LTV = ARPU × (1 / monthly_churn_rate)
119
+ LTV:CAC = should be ≥ 3:1 (ideally > 5:1)
120
+ Payback = CAC / monthly_gross_margin_per_customer (target < 12 months)
121
+ K = invites_per_user × invite_conversion_rate
122
+ ```
@@ -0,0 +1,126 @@
1
+ ---
2
+ name: i18n-localization
3
+ description: Use when planning internationalization (i18n) architecture, localizing an app for new markets, managing translations, or optimizing for non-English app store listings
4
+ ---
5
+
6
+ # i18n / Localization Lens
7
+
8
+ > **Philosophy:** Localization is not translation. It's redesigning the experience for a different culture.
9
+ > A poorly localized app signals "we don't really care about your market."
10
+
11
+ ---
12
+
13
+ ## Core Instincts
14
+
15
+ - **i18n first, l10n second** — build the architecture for internationalization before translating
16
+ - **Never hardcode strings** — every user-visible string lives in an external translation file
17
+ - **RTL is a layout problem, not a text problem** — Hebrew, Arabic require mirrored layouts
18
+ - **Local market ≠ translated market** — date formats, numbers, currencies, cultural norms all differ
19
+ - **App Store localization = free ASO** — localized store listings rank in local search without app changes
20
+
21
+ ---
22
+
23
+ ## i18n vs l10n
24
+
25
+ | Term | Definition |
26
+ |------|-----------|
27
+ | **i18n** (internationalization) | Engineering — building support for multiple locales |
28
+ | **l10n** (localization) | Content — adapting content for a specific locale |
29
+ | **t9n** (translation) | Linguistic — converting text between languages |
30
+
31
+ ---
32
+
33
+ ## Technical Requirements
34
+
35
+ ### Strings
36
+ - Never concatenate user-visible strings: `"Hello " + name` → use named placeholders: `"Hello {name}"`
37
+ - Pluralization rules differ by language (Russian has 4 plural forms; English has 2)
38
+ - Use ICU message format for complex strings: `{count, plural, one {# item} other {# items}}`
39
+
40
+ ### Date / Time / Numbers
41
+ | Category | Example variance |
42
+ |----------|-----------------|
43
+ | Date format | US: 12/31/2024, EU: 31/12/2024, ISO: 2024-12-31 |
44
+ | Time format | 12h (US) vs 24h (EU/Asia) |
45
+ | Number format | 1,234.56 (US) vs 1.234,56 (EU) vs 1 234,56 (FR) |
46
+ | Currency | Symbol position varies; decimal precision varies by currency |
47
+ | Calendar | Gregorian default; some markets use Islamic, Hebrew, Chinese calendars |
48
+
49
+ **Always use:** `Intl.DateTimeFormat`, `Intl.NumberFormat` (JS) or locale-aware libraries — never manually format.
50
+
51
+ ### Right-to-Left (RTL) Languages
52
+ Arabic, Hebrew, Persian, Urdu — require:
53
+ - Mirrored layout (left → right becomes right → left)
54
+ - Text alignment: `start` / `end` instead of `left` / `right`
55
+ - Icons that indicate direction must be flipped
56
+ - Test with: RTL pseudo-localization before translating
57
+
58
+ ---
59
+
60
+ ## App Store Localization Priority
61
+
62
+ Localize store listings first — no code changes needed, immediate revenue impact.
63
+
64
+ | Market | Language | Potential uplift |
65
+ |--------|----------|-----------------|
66
+ | China | Simplified Chinese | 🔴 High (largest iOS market) |
67
+ | Japan | Japanese | 🔴 High (highest ARPU per user) |
68
+ | Germany | German | 🟠 Medium-high |
69
+ | Brazil | Portuguese (BR) | 🟠 Medium-high |
70
+ | France | French | 🟡 Medium |
71
+ | South Korea | Korean | 🟡 Medium |
72
+
73
+ **Rule:** Localize App Store listing → measure download increase → justify full app localization.
74
+
75
+ ---
76
+
77
+ ## ❌ Anti-Patterns to Avoid
78
+
79
+ | ❌ NEVER DO | Why | ✅ DO INSTEAD |
80
+ |------------|-----|--------------|
81
+ | Hardcode strings in UI components | Impossible to translate in future | All strings in `i18n/en.json` from day one |
82
+ | Use string concatenation for sentences | Word order differs by language | Named placeholders in translation keys |
83
+ | Assume text length = English length | German is ~35% longer; Chinese is ~50% shorter | Design UI for 150% of English text length |
84
+ | Use machine translation (Google Translate) for store listing | Quality signals carelessness | Professional translation for app store copy |
85
+ | Translate only UI — not error messages, emails, notifications | Inconsistent experience | All user-visible text in translation files |
86
+ | Design with only LTR in mind | RTL markets are large (Arabic = 400M speakers) | Use logical CSS properties (`inset-inline-start`) from start |
87
+
88
+ ---
89
+
90
+ ## Questions You Always Ask
91
+
92
+ **When architecting i18n:**
93
+ - Are all strings externalized into translation files (zero hardcoded UI text)?
94
+ - Does the date/number/currency formatting use locale-aware APIs?
95
+ - Is the layout system using logical properties (`start`/`end`) for RTL readiness?
96
+
97
+ **When planning a new market:**
98
+ - What's the current revenue from that country without localization?
99
+ - What's the expected uplift from App Store listing localization vs full app localization?
100
+ - Are there cultural norms that affect UX? (e.g., messaging apps are primary in some markets)
101
+
102
+ ---
103
+
104
+ ## Red Flags
105
+
106
+ **Must fix:**
107
+ - [ ] Hardcoded strings in UI code
108
+ - [ ] String concatenation for user-visible sentences
109
+ - [ ] Manual date/number formatting (not using `Intl.*` or locale library)
110
+
111
+ **Should fix:**
112
+ - [ ] App Store listing not localized for top 3 download markets
113
+ - [ ] Layout uses `left`/`right` instead of `start`/`end` (RTL-incompatible)
114
+ - [ ] No pseudo-localization test (catches text overflow and layout issues before real translation)
115
+
116
+ ---
117
+
118
+ ## Who to Pair With
119
+ - `app-store-optimizer` — for App Store listing localization strategy
120
+ - `mobile-developer` — for React Native / Flutter i18n implementation
121
+ - `frontend-developer` — for web i18n and RTL CSS
122
+
123
+ ---
124
+
125
+ ## Tools
126
+ **React:** `react-i18next` / `next-intl` · **Flutter:** `flutter_localizations` + ARB files · **iOS native:** `NSLocalizedString` + `.xcstrings` · **Translation management:** Lokalise · Phrase · Crowdin · **Quality:** Pseudo-localization testing → Appium