cfsa-antigravity 1.0.0

package/template/.agent/skill-library/stack/mobile/flutter/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: flutter
+description: "Expert Flutter guide covering widget composition, state management (Riverpod, BLoC), navigation (GoRouter), Dart best practices (null safety, freezed, sealed classes), platform channels, performance (const widgets, RepaintBoundary, DevTools), testing (widget tests, golden tests, integration), and deployment (Fastlane, Codemagic). Use when building cross-platform apps with Flutter."
+version: 1.0.0
+---
+
+# Flutter Expert Guide
+
+> Use this skill when building iOS/Android/Web/Desktop apps with Flutter. Targets Flutter 3.x with Dart 3.x.
+
+## When to Use This Skill
+
+- Building cross-platform apps (iOS, Android, Web, Desktop)
+- Designing widget hierarchies and custom UI
+- Implementing state management patterns
+- Optimizing Flutter rendering performance
+- Writing widget and integration tests
+
+## When NOT to Use This Skill
+
+- React Native projects → use React Native skill
+- Native iOS only → use SwiftUI
+- Web-only → use a frontend framework
+- Game development → use Flame engine or Godot
+
+---
+
+## 1. Project Structure (CRITICAL)
+
+```
+lib/
+├── main.dart              # Entry point
+├── app/                   # App-level config
+│   ├── app.dart           # MaterialApp / GoRouter setup
+│   └── theme.dart         # ThemeData
+├── features/              # Feature-first organization
+│   ├── auth/
+│   │   ├── data/          # Repositories, data sources
+│   │   ├── domain/        # Models, use cases
+│   │   └── presentation/  # Screens, widgets, controllers
+│   └── home/
+│       ├── data/
+│       ├── domain/
+│       └── presentation/
+├── shared/                # Cross-feature code
+│   ├── widgets/           # Reusable UI components
+│   ├── extensions/        # Dart extensions
+│   └── utils/             # Helpers
+└── l10n/                  # Localization
+```
+
+---
+
+## 2. Widget Composition (CRITICAL)
+
+### Composition Over Inheritance
+
+```dart
+// ✅ Small, focused widgets
+class UserAvatar extends StatelessWidget {
+  const UserAvatar({
+    super.key,
+    required this.imageUrl,
+    this.size = 40,
+  });
+
+  final String imageUrl;
+  final double size;
+
+  @override
+  Widget build(BuildContext context) {
+    return ClipRRect(
+      borderRadius: BorderRadius.circular(size / 2),
+      child: CachedNetworkImage(
+        imageUrl: imageUrl,
+        width: size,
+        height: size,
+        fit: BoxFit.cover,
+        placeholder: (_, __) => const CircularProgressIndicator(),
+        errorWidget: (_, __, ___) => const Icon(Icons.person),
+      ),
+    );
+  }
+}
+```
+
+### Use `const` Constructors
+
+```dart
+// ✅ const prevents unnecessary rebuilds
+const SizedBox(height: 16);
+const Divider();
+const Text('Static text');
+
+// ✅ const constructor in custom widgets
+class AppCard extends StatelessWidget {
+  const AppCard({super.key, required this.child});
+  final Widget child;
+
+  @override
+  Widget build(BuildContext context) => Card(child: child);
+}
+```
+
+---
+
+## 3. State Management
+
+### Riverpod (Recommended)
+
+```dart
+// Provider definition
+final userProvider = FutureProvider.autoDispose<User>((ref) async {
+  final repository = ref.watch(userRepositoryProvider);
+  return repository.getCurrentUser();
+});
+
+// Notifier for mutable state
+@riverpod
+class Counter extends _$Counter {
+  @override
+  int build() => 0;
+
+  void increment() => state++;
+  void decrement() => state--;
+}
+
+// Consuming in a widget
+class HomePage extends ConsumerWidget {
+  const HomePage({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final userAsync = ref.watch(userProvider);
+
+    return userAsync.when(
+      data: (user) => Text('Hello, ${user.name}'),
+      loading: () => const CircularProgressIndicator(),
+      error: (err, stack) => Text('Error: $err'),
+    );
+  }
+}
+```
+
+### BLoC Pattern
+
+```dart
+// Events
+sealed class AuthEvent {}
+class LoginRequested extends AuthEvent {
+  final String email;
+  final String password;
+  LoginRequested({required this.email, required this.password});
+}
+
+// States
+sealed class AuthState {}
+class AuthInitial extends AuthState {}
+class AuthLoading extends AuthState {}
+class AuthSuccess extends AuthState {
+  final User user;
+  AuthSuccess(this.user);
+}
+class AuthFailure extends AuthState {
+  final String message;
+  AuthFailure(this.message);
+}
+
+// Bloc
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  AuthBloc(this._authRepository) : super(AuthInitial()) {
+    on<LoginRequested>(_onLoginRequested);
+  }
+
+  final AuthRepository _authRepository;
+
+  Future<void> _onLoginRequested(
+    LoginRequested event,
+    Emitter<AuthState> emit,
+  ) async {
+    emit(AuthLoading());
+    try {
+      final user = await _authRepository.login(event.email, event.password);
+      emit(AuthSuccess(user));
+    } catch (e) {
+      emit(AuthFailure(e.toString()));
+    }
+  }
+}
+```
+
+---
+
+## 4. Navigation (GoRouter)
+
+```dart
+final router = GoRouter(
+  initialLocation: '/',
+  redirect: (context, state) {
+    final isLoggedIn = /* check auth */;
+    if (!isLoggedIn && !state.matchedLocation.startsWith('/auth')) {
+      return '/auth/login';
+    }
+    return null;
+  },
+  routes: [
+    ShellRoute(
+      builder: (context, state, child) => ScaffoldWithNavBar(child: child),
+      routes: [
+        GoRoute(
+          path: '/',
+          builder: (context, state) => const HomeScreen(),
+        ),
+        GoRoute(
+          path: '/profile/:userId',
+          builder: (context, state) {
+            final userId = state.pathParameters['userId']!;
+            return ProfileScreen(userId: userId);
+          },
+        ),
+      ],
+    ),
+  ],
+);
+```
+
+---
+
+## 5. Dart Best Practices
+
+### Null Safety & Pattern Matching
+
+```dart
+// ✅ Exhaustive pattern matching (Dart 3)
+String describeStatus(AuthState state) => switch (state) {
+  AuthInitial() => 'Not started',
+  AuthLoading() => 'Loading...',
+  AuthSuccess(:final user) => 'Welcome, ${user.name}',
+  AuthFailure(:final message) => 'Error: $message',
+};
+
+// ✅ Null-aware operators
+final name = user?.name ?? 'Anonymous';
+final items = list?.where((i) => i.isActive).toList() ?? [];
+```
+
+### Freezed (Immutable Models)
+
+```dart
+@freezed
+class User with _$User {
+  const factory User({
+    required String id,
+    required String name,
+    required String email,
+    @Default(false) bool isVerified,
+  }) = _User;
+
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+```
+
+---
+
+## 6. Performance
+
+| Rule | Detail |
+|------|--------|
+| Use `const` constructors | Prevents widget rebuild when parent rebuilds |
+| `RepaintBoundary` | Isolates expensive painting operations |
+| `ListView.builder` | Lazy builds only visible items |
+| Avoid `setState` at top level | Rebuilds entire subtree; use granular state |
+| Profile with DevTools | Use Flutter DevTools timeline to find jank |
+| `compute()` for heavy work | Isolate heavy computation to background |
+
+---
+
+## 7. Testing
+
+```dart
+// Widget test
+testWidgets('displays user name', (tester) async {
+  await tester.pumpWidget(
+    const MaterialApp(home: UserCard(name: 'Alice')),
+  );
+  expect(find.text('Alice'), findsOneWidget);
+});
+
+// Golden test
+testWidgets('matches golden', (tester) async {
+  await tester.pumpWidget(const MaterialApp(home: AppButton(text: 'OK')));
+  await expectLater(find.byType(AppButton), matchesGoldenFile('button.png'));
+});
+```
+
+---
+
+## 8. Common Anti-Patterns
+
+1. **God widgets** — split into small, focused widgets (one job each)
+2. **Business logic in widgets** — extract to repositories / use cases
+3. **Not using `const`** — every static widget should be `const`
+4. **setState for complex state** — use Riverpod or BLoC
+5. **Hardcoded strings** — use `l10n` / ARB files for localization
+6. **Ignoring platform conventions** — use `Cupertino` widgets on iOS, `Material` on Android
+7. **No error boundaries** — always handle `.error` state in async providers
+
+---
+
+## References
+
+- [Flutter Documentation](https://docs.flutter.dev/)
+- [Dart Language](https://dart.dev/language)
+- [Riverpod](https://riverpod.dev/)
+- [GoRouter](https://pub.dev/packages/go_router)
+- [Flutter Performance](https://docs.flutter.dev/perf)

package/template/.agent/skill-library/stack/mobile/react-native/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: react-native
+description: "Expert React Native guide covering Expo vs bare workflow, navigation (React Navigation, Expo Router), native modules, platform-specific code, performance (FlatList, memo, Hermes), state management, animations (Reanimated, Gesture Handler), testing (Detox, RNTL), and deployment (EAS Build, CodePush). Use when building cross-platform mobile apps with React Native."
+version: 1.0.0
+---
+
+# React Native Expert Guide
+
+> Use this skill when building iOS/Android apps with React Native. Targets React Native 0.73+ with Expo SDK 50+ or bare workflow.
+
+## When to Use This Skill
+
+- Building cross-platform mobile apps (iOS + Android)
+- Choosing between Expo and bare React Native
+- Implementing navigation, animations, or native modules
+- Optimizing mobile performance (lists, renders, memory)
+- Setting up CI/CD for mobile app deployment
+
+## When NOT to Use This Skill
+
+- Web-only apps → use Next.js / React
+- Native iOS only → use SwiftUI
+- Native Android only → use Kotlin Compose
+- Game development → use Godot or Unity
+- Flutter projects → use Flutter skill
+
+---
+
+## 1. Project Setup (CRITICAL)
+
+### Expo vs Bare Workflow
+
+| Factor | Expo (Managed) | Bare |
+|--------|---------------|------|
+| Setup time | Minutes | Hours |
+| Native modules | Expo Modules API | Manual linking |
+| OTA updates | Built-in (EAS Update) | CodePush |
+| EAS Build | ✅ Cloud builds | Manual Xcode/Gradle |
+| Custom native code | Via config plugins | Full access |
+| **Recommendation** | **Start here** | Only if Expo can't support a requirement |
+
+```bash
+# ✅ Start with Expo
+npx create-expo-app@latest my-app --template blank-typescript
+
+# Bare workflow (only when needed)
+npx react-native@latest init MyApp
+```
+
+### Project Structure
+
+```
+src/
+├── app/                 # Expo Router screens (file-based routing)
+│   ├── (tabs)/          # Tab layout group
+│   │   ├── _layout.tsx
+│   │   ├── index.tsx    # Home tab
+│   │   └── profile.tsx  # Profile tab
+│   ├── _layout.tsx      # Root layout
+│   └── [id].tsx         # Dynamic route
+├── components/          # Reusable UI components
+│   ├── ui/              # Design system primitives
+│   └── features/        # Feature-specific components
+├── hooks/               # Custom hooks
+├── services/            # API clients, storage
+├── stores/              # State management
+├── constants/           # Colors, dimensions, config
+└── types/               # TypeScript type definitions
+```
+
+---
+
+## 2. Navigation
+
+### Expo Router (Recommended)
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <Stack>
+      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+      <Stack.Screen name="modal" options={{ presentation: 'modal' }} />
+    </Stack>
+  );
+}
+```
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { Tabs } from 'expo-router';
+import { Ionicons } from '@expo/vector-icons';
+
+export default function TabLayout() {
+  return (
+    <Tabs>
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: 'Home',
+          tabBarIcon: ({ color, size }) => (
+            <Ionicons name="home" size={size} color={color} />
+          ),
+        }}
+      />
+    </Tabs>
+  );
+}
+```
+
+### Typed Navigation
+
+```tsx
+import { useRouter, useLocalSearchParams } from 'expo-router';
+
+export default function DetailScreen() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+  const router = useRouter();
+
+  return (
+    <Pressable onPress={() => router.push(`/items/${id}`)}>
+      <Text>View Item {id}</Text>
+    </Pressable>
+  );
+}
+```
+
+---
+
+## 3. Performance (CRITICAL)
+
+### FlatList Optimization
+
+```tsx
+import { FlatList, type ListRenderItem } from 'react-native';
+
+const renderItem: ListRenderItem<Item> = ({ item }) => (
+  <ItemRow item={item} />
+);
+
+const keyExtractor = (item: Item) => item.id;
+
+<FlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={keyExtractor}
+  // ✅ Performance props
+  removeClippedSubviews={true}
+  maxToRenderPerBatch={10}
+  windowSize={5}
+  initialNumToRender={10}
+  getItemLayout={(_, index) => ({
+    length: ITEM_HEIGHT,
+    offset: ITEM_HEIGHT * index,
+    index,
+  })}
+/>
+```
+
+### Memoization
+
+```tsx
+import { memo, useCallback, useMemo } from 'react';
+
+// ✅ Memoize list items
+const ItemRow = memo(function ItemRow({ item, onPress }: Props) {
+  return (
+    <Pressable onPress={() => onPress(item.id)}>
+      <Text>{item.title}</Text>
+    </Pressable>
+  );
+});
+
+// ✅ Stable callbacks
+const onItemPress = useCallback((id: string) => {
+  router.push(`/items/${id}`);
+}, []);
+
+// ✅ Expensive computations
+const filteredItems = useMemo(
+  () => items.filter(i => i.category === selectedCategory),
+  [items, selectedCategory]
+);
+```
+
+### Image Optimization
+
+```tsx
+import { Image } from 'expo-image';
+
+// ✅ expo-image with caching
+<Image
+  source={{ uri: imageUrl }}
+  style={{ width: 200, height: 200 }}
+  contentFit="cover"
+  placeholder={blurhash}
+  transition={200}
+/>
+```
+
+---
+
+## 4. Animations
+
+### Reanimated
+
+```tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+
+function AnimatedCard() {
+  const scale = useSharedValue(1);
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }));
+
+  const onPressIn = () => { scale.value = withSpring(0.95); };
+  const onPressOut = () => { scale.value = withSpring(1); };
+
+  return (
+    <Pressable onPressIn={onPressIn} onPressOut={onPressOut}>
+      <Animated.View style={[styles.card, animatedStyle]}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </Pressable>
+  );
+}
+```
+
+### Gesture Handler
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+
+function SwipeableCard() {
+  const translateX = useSharedValue(0);
+
+  const panGesture = Gesture.Pan()
+    .onUpdate((e) => { translateX.value = e.translationX; })
+    .onEnd(() => {
+      if (Math.abs(translateX.value) > SWIPE_THRESHOLD) {
+        translateX.value = withTiming(
+          translateX.value > 0 ? SCREEN_WIDTH : -SCREEN_WIDTH
+        );
+      } else {
+        translateX.value = withSpring(0);
+      }
+    });
+
+  return (
+    <GestureDetector gesture={panGesture}>
+      <Animated.View style={useAnimatedStyle(() => ({
+        transform: [{ translateX: translateX.value }],
+      }))}>
+        <Text>Swipe me</Text>
+      </Animated.View>
+    </GestureDetector>
+  );
+}
+```
+
+---
+
+## 5. Platform-Specific Code
+
+```tsx
+import { Platform, StyleSheet } from 'react-native';
+
+const styles = StyleSheet.create({
+  container: {
+    paddingTop: Platform.OS === 'ios' ? 44 : 0,
+    ...Platform.select({
+      ios: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 } },
+      android: { elevation: 4 },
+    }),
+  },
+});
+
+// File-based: Component.ios.tsx / Component.android.tsx
+```
+
+---
+
+## 6. Deployment
+
+### EAS Build (Expo)
+
+```bash
+# Install EAS CLI
+npm install -g eas-cli
+
+# Configure
+eas build:configure
+
+# Build
+eas build --platform all --profile production
+
+# Submit to stores
+eas submit --platform ios
+eas submit --platform android
+```
+
+### OTA Updates
+
+```bash
+# Push JS-only updates without App Store review
+eas update --branch production --message "Bug fix"
+```
+
+---
+
+## 7. Common Anti-Patterns
+
+1. **Inline styles** — use `StyleSheet.create()` for performance (styles are sent to native once)
+2. **Anonymous functions in renderItem** — causes re-renders; extract and memoize
+3. **ScrollView for long lists** — use `FlatList` or `FlashList` for virtualization
+4. **Ignoring Hermes** — enable Hermes engine for faster startup and lower memory
+5. **Not testing on real devices** — simulators miss performance issues and native behaviors
+6. **Storing sensitive data in AsyncStorage** — use `expo-secure-store` for tokens/secrets
+7. **Giant bundle sizes** — use `react-native-bundle-visualizer` to audit imports
+
+---
+
+## References
+
+- [Expo Documentation](https://docs.expo.dev/)
+- [React Native Documentation](https://reactnative.dev/docs/getting-started)
+- [Expo Router](https://docs.expo.dev/router/introduction/)
+- [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/)
+- [React Native Performance](https://reactnative.dev/docs/performance)