agentic-team-templates 0.3.0

package/templates/mobile/.cursorrules/navigation.md

@@ -0,0 +1,246 @@
+# Mobile Navigation
+
+Best practices for navigation in mobile applications.
+
+## Navigation Patterns
+
+### Stack Navigation
+For hierarchical content flow.
+
+```tsx
+// React Native example
+const Stack = createNativeStackNavigator();
+
+function AppNavigator() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name="Home" component={HomeScreen} />
+      <Stack.Screen name="Details" component={DetailsScreen} />
+      <Stack.Screen
+        name="Settings"
+        component={SettingsScreen}
+        options={{ presentation: 'modal' }}
+      />
+    </Stack.Navigator>
+  );
+}
+```
+
+### Tab Navigation
+For top-level app sections.
+
+```tsx
+const Tab = createBottomTabNavigator();
+
+function MainTabs() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen
+        name="Home"
+        component={HomeStack}
+        options={{
+          tabBarIcon: ({ color }) => <HomeIcon color={color} />,
+        }}
+      />
+      <Tab.Screen name="Search" component={SearchStack} />
+      <Tab.Screen name="Profile" component={ProfileStack} />
+    </Tab.Navigator>
+  );
+}
+```
+
+### Drawer Navigation
+For app-wide menu access.
+
+```tsx
+const Drawer = createDrawerNavigator();
+
+function AppDrawer() {
+  return (
+    <Drawer.Navigator>
+      <Drawer.Screen name="Main" component={MainTabs} />
+      <Drawer.Screen name="Settings" component={SettingsScreen} />
+      <Drawer.Screen name="Help" component={HelpScreen} />
+    </Drawer.Navigator>
+  );
+}
+```
+
+## Deep Linking
+
+### Configuration
+
+```tsx
+const linking = {
+  prefixes: ['myapp://', 'https://myapp.com'],
+  config: {
+    screens: {
+      Home: '',
+      Details: 'details/:id',
+      Profile: 'user/:userId',
+      Settings: 'settings',
+    },
+  },
+};
+
+function App() {
+  return (
+    <NavigationContainer linking={linking}>
+      <AppNavigator />
+    </NavigationContainer>
+  );
+}
+```
+
+### Handling Deep Links
+
+```tsx
+// Handle incoming links
+useEffect(() => {
+  const handleDeepLink = (event: { url: string }) => {
+    const route = parseDeepLink(event.url);
+    if (route) {
+      navigation.navigate(route.screen, route.params);
+    }
+  };
+
+  const subscription = Linking.addEventListener('url', handleDeepLink);
+  return () => subscription.remove();
+}, []);
+```
+
+## Type-Safe Navigation
+
+```tsx
+// Define route params
+type RootStackParamList = {
+  Home: undefined;
+  Details: { id: string };
+  Profile: { userId: string; initialTab?: string };
+};
+
+// Type-safe navigation
+const navigation = useNavigation<NativeStackNavigationProp<RootStackParamList>>();
+
+// Type-safe route params
+const route = useRoute<RouteProp<RootStackParamList, 'Details'>>();
+const { id } = route.params;
+
+// Navigate with type checking
+navigation.navigate('Details', { id: '123' });  // ✓
+navigation.navigate('Details');                  // ✗ Error: id required
+```
+
+## Navigation State
+
+### Persisting State
+
+```tsx
+function App() {
+  const [isReady, setIsReady] = useState(false);
+  const [initialState, setInitialState] = useState();
+
+  useEffect(() => {
+    const restoreState = async () => {
+      const savedState = await AsyncStorage.getItem('NAV_STATE');
+      if (savedState) {
+        setInitialState(JSON.parse(savedState));
+      }
+      setIsReady(true);
+    };
+    restoreState();
+  }, []);
+
+  if (!isReady) return <SplashScreen />;
+
+  return (
+    <NavigationContainer
+      initialState={initialState}
+      onStateChange={(state) => {
+        AsyncStorage.setItem('NAV_STATE', JSON.stringify(state));
+      }}
+    >
+      <AppNavigator />
+    </NavigationContainer>
+  );
+}
+```
+
+## Authentication Flow
+
+```tsx
+function RootNavigator() {
+  const { user, isLoading } = useAuth();
+
+  if (isLoading) {
+    return <SplashScreen />;
+  }
+
+  return (
+    <Stack.Navigator screenOptions={{ headerShown: false }}>
+      {user ? (
+        <Stack.Screen name="Main" component={MainNavigator} />
+      ) : (
+        <Stack.Screen name="Auth" component={AuthNavigator} />
+      )}
+    </Stack.Navigator>
+  );
+}
+```
+
+## Best Practices
+
+### Avoid Prop Drilling Navigation
+
+```tsx
+// Bad: Passing navigation through props
+<ChildComponent navigation={navigation} />
+
+// Good: Use hooks
+function ChildComponent() {
+  const navigation = useNavigation();
+}
+```
+
+### Handle Android Back Button
+
+```tsx
+useEffect(() => {
+  const onBackPress = () => {
+    if (shouldPreventBack) {
+      Alert.alert('Discard changes?', '...', [
+        { text: 'Cancel', style: 'cancel' },
+        { text: 'Discard', onPress: () => navigation.goBack() },
+      ]);
+      return true;  // Prevent default
+    }
+    return false;  // Allow default
+  };
+
+  BackHandler.addEventListener('hardwareBackPress', onBackPress);
+  return () => BackHandler.removeEventListener('hardwareBackPress', onBackPress);
+}, []);
+```
+
+### Use beforeRemove for Unsaved Changes
+
+```tsx
+useEffect(() => {
+  const unsubscribe = navigation.addListener('beforeRemove', (e) => {
+    if (!hasUnsavedChanges) return;
+
+    e.preventDefault();
+
+    Alert.alert('Discard changes?', 'You have unsaved changes.', [
+      { text: 'Cancel', style: 'cancel' },
+      {
+        text: 'Discard',
+        style: 'destructive',
+        onPress: () => navigation.dispatch(e.data.action),
+      },
+    ]);
+  });
+
+  return unsubscribe;
+}, [hasUnsavedChanges]);
+```

package/templates/mobile/.cursorrules/offline-first.md

@@ -0,0 +1,302 @@
+# Offline-First Development
+
+Building mobile apps that work reliably without network connectivity.
+
+## Principles
+
+### 1. Assume Unreliable Network
+Mobile networks are inconsistent. Design for it.
+
+### 2. Local-First
+Read from local storage, sync in background.
+
+### 3. Optimistic Updates
+Update UI immediately, reconcile later.
+
+### 4. Graceful Degradation
+Show what's available, queue what isn't.
+
+## Data Storage
+
+### Choosing Storage
+
+| Storage Type | Use Case | Persistence |
+|--------------|----------|-------------|
+| AsyncStorage | Simple key-value, settings | Persistent |
+| SQLite/Realm | Structured data, queries | Persistent |
+| MMKV | Fast key-value | Persistent |
+| In-memory | Temporary, session data | Session only |
+
+### Local Database
+
+```ts
+// Example with SQLite/TypeORM
+@Entity()
+class Task {
+  @PrimaryColumn()
+  id: string;
+
+  @Column()
+  title: string;
+
+  @Column({ default: false })
+  completed: boolean;
+
+  @Column({ default: false })
+  syncedToServer: boolean;
+
+  @Column({ type: 'datetime', nullable: true })
+  lastModified: Date;
+}
+```
+
+## Sync Strategies
+
+### Pull Strategy (Server → Device)
+
+```ts
+async function pullChanges() {
+  const lastSync = await getLastSyncTimestamp();
+
+  const changes = await api.getChanges({ since: lastSync });
+
+  await db.transaction(async (tx) => {
+    for (const item of changes.items) {
+      await tx.upsert('tasks', item);
+    }
+    await tx.update('metadata', { lastSync: changes.timestamp });
+  });
+}
+```
+
+### Push Strategy (Device → Server)
+
+```ts
+async function pushChanges() {
+  const pendingChanges = await db.query(
+    'SELECT * FROM tasks WHERE syncedToServer = false'
+  );
+
+  for (const change of pendingChanges) {
+    try {
+      await api.syncTask(change);
+      await db.update('tasks', change.id, { syncedToServer: true });
+    } catch (error) {
+      if (!isNetworkError(error)) {
+        throw error;  // Server rejected, need conflict resolution
+      }
+      // Network error, will retry later
+    }
+  }
+}
+```
+
+### Conflict Resolution
+
+```ts
+type ConflictResolution = 'server-wins' | 'client-wins' | 'manual';
+
+async function resolveConflict(
+  local: Task,
+  server: Task,
+  strategy: ConflictResolution
+): Promise<Task> {
+  switch (strategy) {
+    case 'server-wins':
+      return server;
+
+    case 'client-wins':
+      await api.updateTask(local);
+      return local;
+
+    case 'manual':
+      // Store conflict for user resolution
+      await storeConflict({ local, server });
+      throw new ConflictError('Manual resolution required');
+  }
+}
+```
+
+## Network State Management
+
+### Detecting Connectivity
+
+```ts
+import NetInfo from '@react-native-community/netinfo';
+
+function useNetworkStatus() {
+  const [isOnline, setIsOnline] = useState(true);
+  const [connectionType, setConnectionType] = useState<string | null>(null);
+
+  useEffect(() => {
+    const unsubscribe = NetInfo.addEventListener((state) => {
+      setIsOnline(state.isConnected ?? false);
+      setConnectionType(state.type);
+    });
+
+    return unsubscribe;
+  }, []);
+
+  return { isOnline, connectionType };
+}
+```
+
+### Queueing Operations
+
+```ts
+class OperationQueue {
+  private queue: Operation[] = [];
+
+  async enqueue(operation: Operation) {
+    await this.persistQueue([...this.queue, operation]);
+    this.queue.push(operation);
+    this.processIfOnline();
+  }
+
+  private async processIfOnline() {
+    if (!await isOnline()) return;
+
+    while (this.queue.length > 0) {
+      const op = this.queue[0];
+      try {
+        await this.execute(op);
+        this.queue.shift();
+        await this.persistQueue(this.queue);
+      } catch (error) {
+        if (isNetworkError(error)) {
+          break;  // Stop, will retry when online
+        }
+        throw error;
+      }
+    }
+  }
+}
+```
+
+## Optimistic Updates
+
+```tsx
+function useOptimisticTask() {
+  const queryClient = useQueryClient();
+
+  const updateTask = useMutation({
+    mutationFn: api.updateTask,
+
+    onMutate: async (newTask) => {
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({ queryKey: ['tasks'] });
+
+      // Snapshot current value
+      const previousTasks = queryClient.getQueryData(['tasks']);
+
+      // Optimistically update
+      queryClient.setQueryData(['tasks'], (old: Task[]) =>
+        old.map((t) => (t.id === newTask.id ? newTask : t))
+      );
+
+      return { previousTasks };
+    },
+
+    onError: (err, newTask, context) => {
+      // Rollback on error
+      queryClient.setQueryData(['tasks'], context?.previousTasks);
+    },
+
+    onSettled: () => {
+      // Refetch after error or success
+      queryClient.invalidateQueries({ queryKey: ['tasks'] });
+    },
+  });
+
+  return updateTask;
+}
+```
+
+## Caching
+
+### Cache Headers
+
+```ts
+const cacheConfig = {
+  images: { maxAge: 7 * 24 * 60 * 60 },      // 1 week
+  apiResponses: { maxAge: 5 * 60 },          // 5 minutes
+  staticAssets: { maxAge: 30 * 24 * 60 * 60 }, // 30 days
+};
+```
+
+### Stale-While-Revalidate
+
+```ts
+async function fetchWithSWR<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
+  // Return cached data immediately
+  const cached = await cache.get(key);
+  if (cached) {
+    // Revalidate in background
+    fetcher()
+      .then((fresh) => cache.set(key, fresh))
+      .catch(console.error);
+    return cached;
+  }
+
+  // No cache, wait for network
+  const data = await fetcher();
+  await cache.set(key, data);
+  return data;
+}
+```
+
+## UI Patterns
+
+### Show Sync Status
+
+```tsx
+function TaskItem({ task }: { task: Task }) {
+  return (
+    <View style={styles.item}>
+      <Text>{task.title}</Text>
+      {!task.syncedToServer && (
+        <View style={styles.syncIndicator}>
+          <CloudOffIcon />
+          <Text>Pending sync</Text>
+        </View>
+      )}
+    </View>
+  );
+}
+```
+
+### Offline Banner
+
+```tsx
+function OfflineBanner() {
+  const { isOnline } = useNetworkStatus();
+
+  if (isOnline) return null;
+
+  return (
+    <View style={styles.banner}>
+      <Text>You're offline. Changes will sync when connected.</Text>
+    </View>
+  );
+}
+```
+
+### Queue Indicator
+
+```tsx
+function SyncStatus() {
+  const { pendingCount, isSyncing } = useSyncStatus();
+
+  if (pendingCount === 0) return null;
+
+  return (
+    <View style={styles.syncStatus}>
+      {isSyncing ? (
+        <ActivityIndicator />
+      ) : (
+        <Text>{pendingCount} changes pending</Text>
+      )}
+    </View>
+  );
+}
+```

package/templates/mobile/.cursorrules/overview.md

@@ -0,0 +1,71 @@
+# Mobile Development
+
+Guidelines for building mobile applications.
+
+## Scope
+
+This ruleset applies to:
+- React Native applications
+- Flutter applications
+- Native iOS/Android development
+- Cross-platform mobile frameworks
+
+## Key Principles
+
+### 1. Mobile-First UX
+Design for touch, small screens, and variable connectivity.
+
+### 2. Performance Matters
+60fps animations, fast startup, efficient battery usage.
+
+### 3. Offline-First
+Apps should work without network when possible.
+
+### 4. Platform Conventions
+Respect each platform's design language and conventions.
+
+## Project Structure
+
+```
+src/
+├── components/       # Reusable UI components
+├── screens/          # Screen/page components
+├── navigation/       # Navigation configuration
+├── hooks/            # Custom hooks
+├── services/         # API and native service wrappers
+├── store/            # State management
+├── utils/            # Utility functions
+├── types/            # TypeScript definitions
+└── assets/           # Images, fonts, etc.
+```
+
+## Core Concerns
+
+### Navigation
+- Use standard navigation patterns (stack, tab, drawer)
+- Handle deep linking
+- Manage navigation state
+- Support gestures
+
+### Native Features
+- Camera, location, notifications
+- File system, storage
+- Biometric authentication
+- Background tasks
+
+### Performance
+- Optimize list rendering (virtualization)
+- Minimize re-renders
+- Lazy load images
+- Profile and optimize startup time
+
+## Definition of Done
+
+A mobile feature is complete when:
+- [ ] Works on both platforms (if cross-platform)
+- [ ] Handles offline gracefully
+- [ ] Animations run at 60fps
+- [ ] Accessible (screen readers, dynamic type)
+- [ ] Tests pass on device/simulator
+- [ ] No memory leaks
+- [ ] Handles permissions correctly