@neyugn/agent-kits 0.1.0

package/kits/coder/skills/react-native-patterns/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: react-native-patterns
+description: React Native with Expo development patterns. Use when building mobile apps with React Native, implementing navigation, native modules, or offline-first architecture. Covers Expo Router, EAS Build, and performance.
+allowed-tools: Read, Write, Edit, Bash
+version: 1.0
+priority: MEDIUM
+---
+
+# React Native Patterns - Mobile Excellence with Expo
+
+> **Philosophy:** Use Expo unless you have a very specific reason not to. OTA updates, managed native code, and faster development are worth the trade-offs.
+
+---
+
+## 🎯 Core Principles
+
+| Principle          | Rule                                                  |
+| ------------------ | ----------------------------------------------------- |
+| **Expo First**     | Start with Expo, eject only when absolutely necessary |
+| **Platform Aware** | One codebase, platform-specific polish                |
+| **Offline Ready**  | Assume network is unreliable                          |
+| **Performance**    | FlashList, memoization, native thread animations      |
+| **Type Safe**      | TypeScript is mandatory                               |
+
+```
+❌ WRONG: Bare React Native for simple apps
+✅ CORRECT: Expo with EAS Build, eject later if needed
+```
+
+---
+
+## 📁 Project Structure
+
+```
+src/
+├── app/                    # Expo Router screens
+│   ├── (auth)/             # Auth group
+│   │   ├── login.tsx
+│   │   └── register.tsx
+│   ├── (tabs)/             # Tab navigation
+│   │   ├── _layout.tsx
+│   │   ├── index.tsx
+│   │   └── profile.tsx
+│   └── _layout.tsx         # Root layout
+├── components/
+│   ├── ui/                 # Reusable UI components
+│   └── features/           # Feature-specific components
+├── hooks/                  # Custom hooks
+├── services/               # API and native services
+├── stores/                 # State management
+├── utils/                  # Utilities
+└── types/                  # TypeScript types
+```
+
+---
+
+## 🔀 Expo vs Bare React Native
+
+| Feature            | Expo           | Bare RN        |
+| ------------------ | -------------- | -------------- |
+| Setup complexity   | Low            | High           |
+| Native modules     | EAS Build      | Manual linking |
+| OTA updates        | Built-in       | Manual setup   |
+| Build service      | EAS            | Custom CI      |
+| Custom native code | Config plugins | Direct access  |
+| Time to MVP        | Fast           | Slow           |
+
+### When to Use Bare React Native
+
+- Need custom native modules not available in Expo
+- Existing native app integration
+- Very specific native build requirements
+- Corporate restrictions on cloud build services
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Create new Expo project
+npx create-expo-app@latest my-app -t expo-template-blank-typescript
+
+# Install essential dependencies
+npx expo install expo-router expo-status-bar react-native-safe-area-context
+npx expo install @react-native-async-storage/async-storage
+npx expo install expo-secure-store expo-haptics
+```
+
+---
+
+## 🧭 Expo Router Navigation
+
+```typescript
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function RootLayout() {
+  return (
+    <Stack screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="(tabs)" />
+      <Stack.Screen name="(auth)" />
+      <Stack.Screen name="modal" options={{ presentation: 'modal' }} />
+    </Stack>
+  )
+}
+
+// app/(tabs)/_layout.tsx
+import { Tabs } from 'expo-router'
+import { Home, User } from 'lucide-react-native'
+
+export default function TabLayout() {
+  return (
+    <Tabs>
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: 'Home',
+          tabBarIcon: ({ color, size }) => <Home size={size} color={color} />,
+        }}
+      />
+      <Tabs.Screen
+        name="profile"
+        options={{
+          title: 'Profile',
+          tabBarIcon: ({ color, size }) => <User size={size} color={color} />,
+        }}
+      />
+    </Tabs>
+  )
+}
+```
+
+### Programmatic Navigation
+
+```typescript
+import { router } from "expo-router";
+
+// Navigate
+router.push("/profile/123");
+router.replace("/login");
+router.back();
+
+// With params
+router.push({
+  pathname: "/product/[id]",
+  params: { id: "123", referrer: "home" },
+});
+```
+
+---
+
+## 💾 Offline-First with React Query
+
+```typescript
+// providers/QueryProvider.tsx
+import { QueryClient } from "@tanstack/react-query";
+import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
+import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import NetInfo from "@react-native-community/netinfo";
+import { onlineManager } from "@tanstack/react-query";
+
+// Sync online status
+onlineManager.setEventListener((setOnline) => {
+  return NetInfo.addEventListener((state) => {
+    setOnline(!!state.isConnected);
+  });
+});
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      gcTime: 1000 * 60 * 60 * 24, // 24 hours
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      networkMode: "offlineFirst",
+    },
+  },
+});
+
+const persister = createAsyncStoragePersister({
+  storage: AsyncStorage,
+  key: "REACT_QUERY_CACHE",
+});
+```
+
+---
+
+## ⚡ Performance Patterns
+
+### FlashList over FlatList
+
+```typescript
+import { FlashList } from '@shopify/flash-list'
+import { memo, useCallback } from 'react'
+
+const ProductItem = memo(function ProductItem({ item, onPress }) {
+  const handlePress = useCallback(() => onPress(item.id), [item.id, onPress])
+
+  return (
+    <Pressable onPress={handlePress}>
+      <FastImage source={{ uri: item.image }} />
+      <Text>{item.name}</Text>
+    </Pressable>
+  )
+})
+
+export function ProductList({ products, onProductPress }) {
+  const renderItem = useCallback(
+    ({ item }) => <ProductItem item={item} onPress={onProductPress} />,
+    [onProductPress]
+  )
+
+  return (
+    <FlashList
+      data={products}
+      renderItem={renderItem}
+      estimatedItemSize={100}
+      removeClippedSubviews={true}
+    />
+  )
+}
+```
+
+### Reanimated for 60fps Animations
+
+```typescript
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress, children }) {
+  const scale = useSharedValue(1)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }))
+
+  const handlePressIn = () => {
+    scale.value = withSpring(0.95)
+  }
+
+  const handlePressOut = () => {
+    scale.value = withSpring(1)
+  }
+
+  return (
+    <Animated.View style={animatedStyle}>
+      <Pressable
+        onPress={onPress}
+        onPressIn={handlePressIn}
+        onPressOut={handlePressOut}
+      >
+        {children}
+      </Pressable>
+    </Animated.View>
+  )
+}
+```
+
+---
+
+## 📱 Platform-Specific Code
+
+```typescript
+import { Platform, StyleSheet } from "react-native";
+
+const styles = StyleSheet.create({
+  shadow: Platform.select({
+    ios: {
+      shadowColor: "#000",
+      shadowOffset: { width: 0, height: 2 },
+      shadowOpacity: 0.1,
+      shadowRadius: 4,
+    },
+    android: {
+      elevation: 4,
+    },
+  }),
+});
+
+// Or use file-based separation
+// Button.ios.tsx
+// Button.android.tsx
+// Button.web.tsx
+```
+
+---
+
+## 🔐 Native Services
+
+```typescript
+// Haptics
+import * as Haptics from "expo-haptics";
+
+if (Platform.OS !== "web") {
+  Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+}
+
+// Secure Storage
+import * as SecureStore from "expo-secure-store";
+
+await SecureStore.setItemAsync("token", authToken);
+const token = await SecureStore.getItemAsync("token");
+
+// Biometrics
+import * as LocalAuthentication from "expo-local-authentication";
+
+const result = await LocalAuthentication.authenticateAsync({
+  promptMessage: "Authenticate",
+});
+```
+
+---
+
+## 📦 EAS Build & Submit
+
+```json
+// eas.json
+{
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal",
+      "android": { "buildType": "apk" }
+    },
+    "production": {
+      "autoIncrement": true
+    }
+  }
+}
+```
+
+```bash
+# Build commands
+eas build --platform ios --profile production
+eas build --platform android --profile production
+
+# Submit to stores
+eas submit --platform ios
+eas submit --platform android
+
+# OTA updates
+eas update --branch production --message "Bug fixes"
+```
+
+---
+
+## 🚨 Anti-Patterns
+
+| ❌ Don't                     | ✅ Do                                |
+| ---------------------------- | ------------------------------------ |
+| Use FlatList for large lists | Use FlashList                        |
+| Inline styles                | Use StyleSheet.create                |
+| Fetch in render              | Use useEffect or React Query         |
+| Ignore platform differences  | Test on both iOS and Android         |
+| Store secrets in code        | Use environment variables            |
+| Skip error boundaries        | Handle crashes gracefully            |
+| Animate on JS thread         | Use Reanimated for native animations |
+| Forget offline handling      | Implement offline-first              |
+
+---
+
+## ✅ Self-Check Before Completing
+
+| Check               | Question                                 |
+| ------------------- | ---------------------------------------- |
+| ✅ **Expo?**        | Using Expo unless specifically required? |
+| ✅ **TypeScript?**  | Full type coverage?                      |
+| ✅ **Offline?**     | Handles offline state gracefully?        |
+| ✅ **Platform?**    | Tested on both iOS and Android?          |
+| ✅ **Performance?** | FlashList, memoization, Reanimated?      |
+| ✅ **Secure?**      | Tokens in SecureStore, not AsyncStorage? |
+| ✅ **Navigation?**  | Expo Router properly configured?         |
+
+---
+
+## 🔗 Related Skills
+
+| Need               | Skill              |
+| ------------------ | ------------------ |
+| Flutter comparison | `flutter-patterns` |
+| Mobile design      | `mobile-design`    |
+| React patterns     | `react-patterns`   |
+| Testing            | `testing-patterns` |
+
+---
+
+> **Remember:** Mobile users expect instant responses, offline capability, and native feel. Every millisecond of loading time matters.

package/kits/coder/skills/react-patterns/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: react-patterns
+description: React and Next.js performance optimization and design patterns. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, or implementing server/client-side optimizations. Covers hooks, composition, state management, React 19 features, and Vercel best practices.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# React Patterns
+
+> **Philosophy:** Measure first, optimize second. React is about composition - build small, combine thoughtfully.
+
+---
+
+## 📑 Content Map
+
+| File                            | When to Read                  |
+| ------------------------------- | ----------------------------- |
+| `references/hook-patterns.md`   | Advanced custom hooks         |
+| `references/performance.md`     | Deep performance optimization |
+| `references/nextjs-patterns.md` | Next.js App Router specific   |
+
+---
+
+## 1. Component Design Principles
+
+### Component Types
+
+| Type               | Use                   | State             | Example                  |
+| ------------------ | --------------------- | ----------------- | ------------------------ |
+| **Server**         | Data fetching, static | None              | Page layouts, data grids |
+| **Client**         | Interactivity         | useState, effects | Forms, modals, dropdowns |
+| **Presentational** | UI display            | Props only        | Button, Card, Avatar     |
+| **Container**      | Logic/state           | Heavy state       | UserProfileContainer     |
+
+### Design Rules
+
+| Rule                         | Rationale                        |
+| ---------------------------- | -------------------------------- |
+| One responsibility           | Easier testing, reuse            |
+| Props down, events up        | Predictable data flow            |
+| Composition over inheritance | Flexibility, avoid prop drilling |
+| Small, focused components    | Better tree shaking, readability |
+
+---
+
+## 2. Hook Patterns
+
+### When to Extract Custom Hooks
+
+| Pattern           | Extract When                           |
+| ----------------- | -------------------------------------- |
+| `useLocalStorage` | Same storage logic needed              |
+| `useDebounce`     | Multiple debounced values              |
+| `useFetch`        | Repeated fetch patterns                |
+| `useForm`         | Complex form state                     |
+| `useClickOutside` | Multiple modal/dropdown components     |
+| `usePrevious`     | Need previous value in multiple places |
+
+### Hook Rules (CRITICAL)
+
+| Rule                    | Violation Consequence            |
+| ----------------------- | -------------------------------- |
+| Top level only          | Inconsistent state               |
+| Same order every render | React loses track of state       |
+| Prefix with "use"       | Lint error, convention violation |
+| Clean up effects        | Memory leaks, stale closures     |
+
+### React 19 New Hooks
+
+| Hook             | Purpose                  | Example Use Case               |
+| ---------------- | ------------------------ | ------------------------------ |
+| `useActionState` | Form submission state    | Server Actions with pending UI |
+| `useOptimistic`  | Optimistic UI updates    | Like button, comment posting   |
+| `use`            | Read resources in render | Reading promises, context      |
+| `useFormStatus`  | Form submission status   | Submit button loading state    |
+
+---
+
+## 3. State Management Selection
+
+### Decision Tree
+
+```
+State scope?
+│
+├── Single component → useState
+│
+├── Parent-child (1-2 levels) → Lift state up
+│
+├── Subtree (3+ levels) → Context
+│
+├── Server state → React Query / SWR
+│
+└── Complex global → Zustand / Redux Toolkit
+```
+
+### State Placement Guide
+
+| Scope            | Solution          | When to Use               |
+| ---------------- | ----------------- | ------------------------- |
+| Single component | `useState`        | Form inputs, toggles      |
+| Parent-child     | Props + callbacks | Controlled components     |
+| Subtree          | Context           | Theme, auth, locale       |
+| Server state     | React Query       | API data, caching         |
+| Complex global   | Zustand           | Cart, filters, multi-step |
+
+---
+
+## 4. Performance Optimization (Priority Order)
+
+### 🔴 CRITICAL: Eliminating Waterfalls
+
+| Pattern             | Problem                      | Solution                            |
+| ------------------- | ---------------------------- | ----------------------------------- |
+| `async-defer-await` | Blocking unrelated code      | Move await into branches where used |
+| `async-parallel`    | Sequential independent calls | `Promise.all()` for independent ops |
+| `async-suspense`    | Waiting for all data         | Use Suspense to stream content      |
+
+### 🔴 CRITICAL: Bundle Size
+
+| Pattern                 | Problem                   | Solution                       |
+| ----------------------- | ------------------------- | ------------------------------ |
+| `bundle-barrel-imports` | Importing entire library  | Import directly from module    |
+| `bundle-dynamic`        | Loading unused code       | `next/dynamic` for heavy comps |
+| `bundle-defer-third`    | Analytics blocking render | Load after hydration           |
+
+### 🟡 HIGH: Server-Side Performance
+
+| Pattern                | Problem               | Solution                       |
+| ---------------------- | --------------------- | ------------------------------ |
+| `server-cache-react`   | Duplicate requests    | `React.cache()` per-request    |
+| `server-serialization` | Large client payloads | Minimize data passed to client |
+| `server-parallel`      | Sequential fetching   | Restructure for parallel       |
+
+### 🟢 MEDIUM: Re-render Optimization
+
+| Pattern                  | Problem                      | Solution                      |
+| ------------------------ | ---------------------------- | ----------------------------- |
+| `rerender-memo`          | Expensive child re-renders   | Extract to memoized component |
+| `rerender-dependencies`  | Unstable effect dependencies | Use primitive dependencies    |
+| `rerender-derived-state` | Subscribing to raw values    | Subscribe to derived booleans |
+| `rerender-lazy-init`     | Expensive initial state      | Pass function to useState     |
+
+---
+
+## 5. Composition Patterns
+
+### Compound Components
+
+```tsx
+// ✅ Flexible composition
+<Tabs defaultValue="tab1">
+  <Tabs.List>
+    <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
+    <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="tab1">Content 1</Tabs.Content>
+  <Tabs.Content value="tab2">Content 2</Tabs.Content>
+</Tabs>
+```
+
+**Use for:** Tabs, Accordion, Dropdown, Modal, Dialog
+
+### Render Props vs Hooks
+
+| Use Case           | Prefer This  | Why                      |
+| ------------------ | ------------ | ------------------------ |
+| Reusable logic     | Custom hook  | Cleaner, easier to test  |
+| Render flexibility | Render props | Consumer controls UI     |
+| Cross-cutting      | HOC          | Auth, logging, analytics |
+
+---
+
+## 6. Error Handling
+
+### Error Boundary Strategy
+
+| Scope     | Placement              | Fallback                    |
+| --------- | ---------------------- | --------------------------- |
+| App-wide  | Root level             | "Something went wrong" page |
+| Feature   | Route/feature level    | Feature-specific message    |
+| Component | Around risky component | Graceful degradation        |
+
+### Recovery Pattern
+
+| Step | Action                         |
+| ---- | ------------------------------ |
+| 1    | Show fallback UI               |
+| 2    | Log error (Sentry, DataDog)    |
+| 3    | Offer retry option             |
+| 4    | Preserve user data if possible |
+
+---
+
+## 7. TypeScript Integration
+
+### Props Typing
+
+| Pattern   | Use For               | Example                       |
+| --------- | --------------------- | ----------------------------- |
+| Interface | Component props       | `interface ButtonProps {}`    |
+| Type      | Unions, complex types | `type Status = 'on' \| 'off'` |
+| Generic   | Reusable components   | `<DataTable<T>>`              |
+
+### Essential Types
+
+| Need          | Type                     |
+| ------------- | ------------------------ |
+| Children      | `ReactNode`              |
+| Event handler | `MouseEventHandler<T>`   |
+| Ref           | `RefObject<Element>`     |
+| Component ref | `ComponentRef<typeof X>` |
+
+---
+
+## 8. Testing Priorities
+
+### Test Pyramid for React
+
+| Level       | What to Test                     | Tools               |
+| ----------- | -------------------------------- | ------------------- |
+| Unit        | Pure functions, hooks logic      | Vitest, Jest        |
+| Integration | Component behavior, interactions | React Testing Lib   |
+| E2E         | Critical user flows              | Playwright, Cypress |
+
+### Focus Areas
+
+- [ ] User-visible behavior (not implementation)
+- [ ] Edge cases (empty states, loading, errors)
+- [ ] Accessibility assertions
+- [ ] Form validation scenarios
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't                      | ✅ Do                         | Why                         |
+| ----------------------------- | ----------------------------- | --------------------------- |
+| `'use client'` everywhere     | Server Components by default  | Smaller bundle, better SEO  |
+| Prop drilling (5+ levels)     | Context or state management   | Maintainability             |
+| Index as key                  | Stable unique ID              | Correct reconciliation      |
+| `useEffect` for everything    | Server Components for data    | Avoid waterfalls            |
+| Premature optimization        | Profile first                 | Don't guess, measure        |
+| Giant components (500+ lines) | Split into smaller pieces     | Testing, reuse, readability |
+| Inline function in render     | `useCallback` for stable refs | Performance (when needed)   |
+
+---
+
+## 10. Next.js App Router Specifics
+
+### Server vs Client Decision
+
+```
+Does component need...?
+│
+├── useState, useEffect, event handlers → 'use client'
+│
+├── Direct data fetching, no interactivity → Server (default)
+│
+└── Both? → Split: Server parent + Client child
+```
+
+### File Conventions
+
+| File            | Purpose          |
+| --------------- | ---------------- |
+| `page.tsx`      | Route UI         |
+| `layout.tsx`    | Shared layout    |
+| `loading.tsx`   | Loading skeleton |
+| `error.tsx`     | Error boundary   |
+| `not-found.tsx` | 404 page         |
+
+### Caching Strategy
+
+| Layer      | Control         | Use Case               |
+| ---------- | --------------- | ---------------------- |
+| Request    | fetch options   | Per-request caching    |
+| Data       | revalidate/tags | ISR, on-demand refresh |
+| Full route | route config    | Static pages           |
+
+---
+
+## 11. Quick Decision Trees
+
+### "Which state solution?"
+
+```
+Server data? → React Query
+Form state? → React Hook Form
+Global UI? → Zustand
+Theme/Auth? → Context
+Simple local? → useState
+```
+
+### "Why is it slow?"
+
+```
+1. Profile with React DevTools
+2. Check for:
+   - Unnecessary re-renders → React.memo, useMemo
+   - Large bundles → Dynamic imports, barrel avoidance
+   - Network waterfalls → Parallel fetching, suspense
+   - Memory leaks → Effect cleanup
+```
+
+---
+
+## Related Skills
+
+| Need                  | Skill                   |
+| --------------------- | ----------------------- |
+| Styling               | `tailwind-patterns`     |
+| Testing               | `testing-patterns`      |
+| API integration       | `api-patterns`          |
+| TypeScript advanced   | `typescript-patterns`   |
+| Performance deep-dive | `performance-profiling` |
+
+---
+
+> **Remember:** React 19+ with Server Components changes everything. Start server-side, add client only when needed.