@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/engineering-principles.md

@@ -0,0 +1,82 @@
+# Engineering Principles
+
+## Core Principles
+
+### SOLID
+
+- **S**ingle Responsibility: One reason to change per class/module
+- **O**pen/Closed: Open for extension, closed for modification
+- **L**iskov Substitution: Subtypes must be substitutable for base types
+- **I**nterface Segregation: Many specific interfaces > one general interface
+- **D**ependency Inversion: Depend on abstractions, not concretions
+
+### KISS — Keep It Simple
+
+- Prefer straightforward solutions over clever ones
+- If it's hard to explain, it's probably too complex
+- Complexity is the enemy of reliability
+
+### DRY — Don't Repeat Yourself
+
+- Extract shared logic into reusable functions/modules
+- Single source of truth for business rules
+- But: don't over-abstract prematurely (see YAGNI)
+
+### YAGNI — You Aren't Gonna Need It
+
+- Build only what's needed now
+- No speculative features or "just in case" code
+- Requirements change; premature abstraction wastes effort
+
+### Separation of Concerns
+
+- Each module handles one aspect of functionality
+- UI, business logic, data access in separate layers
+- Clear boundaries between packages
+
+### Dependency Inversion
+
+- High-level modules don't depend on low-level modules
+- Both depend on abstractions (interfaces)
+- Inject dependencies, don't instantiate them
+
+### Explicit > Implicit
+
+- Favor explicit configuration over magic
+- Clear naming over clever shortcuts
+- Readable code over terse code
+
+### Fail Fast
+
+- Validate inputs at boundaries
+- Throw early on invalid state
+- Don't silently swallow errors
+
+### Boring Architecture Wins
+
+- Proven patterns over trendy solutions
+- Standard libraries over custom implementations
+- Maintainability over cleverness
+
+---
+
+## Applying These Principles
+
+### When Writing Code
+
+1. Ask: "Does this class/function do one thing?"
+2. Ask: "Is this the simplest solution that works?"
+3. Ask: "Am I building something I actually need right now?"
+4. Ask: "Would a new team member understand this?"
+
+### When Reviewing Code
+
+- Flag violations of these principles
+- Suggest simpler alternatives
+- Question speculative features
+
+### When Designing
+
+- Start simple, add complexity only when proven necessary
+- Prefer composition over inheritance
+- Design for change, but don't over-engineer

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/gorouter-navigation.md

@@ -0,0 +1,157 @@
+# GoRouter Navigation
+
+## Route Constants (Required Pattern)
+
+```dart
+// lib/core/routes/routes.dart
+abstract class Routes {
+  static const home = '/home';
+  static const profile = '/profile';
+  static const settings = '/settings';
+  static const login = '/auth/login';
+  static const todoDetails = '/todos/:id';
+  static const userProfile = '/users/:userId';
+  
+  // Helper for parameterized routes
+  static String todoDetailsPath(String id) => '/todos/$id';
+  static String userProfilePath(String userId) => '/users/$userId';
+}
+```
+
+## Basic Setup
+
+```dart
+import 'package:go_router/go_router.dart';
+
+final goRouter = GoRouter(
+  initialLocation: Routes.home,
+  redirect: (context, state) {
+    final isLoggedIn = /* check auth */;
+    if (!isLoggedIn && !state.matchedLocation.startsWith('/auth')) {
+      return Routes.login;
+    }
+    return null;
+  },
+  routes: [
+    GoRoute(
+      path: Routes.home,
+      builder: (context, state) => const HomeScreen(),
+    ),
+    GoRoute(
+      path: Routes.todoDetails,
+      builder: (context, state) {
+        final id = state.pathParameters['id']!;
+        return TodoDetailsScreen(id: id);
+      },
+    ),
+    GoRoute(
+      path: Routes.login,
+      builder: (context, state) => const LoginScreen(),
+    ),
+  ],
+);
+```
+
+## Navigation Methods
+
+```dart
+// Navigate and replace history
+context.go(Routes.home);
+
+// Navigate with params
+context.go(Routes.todoDetailsPath('123'));
+
+// Navigate and add to stack
+context.push(Routes.profile);
+
+// Go back
+context.pop();
+
+// Replace current route
+context.pushReplacement(Routes.home);
+
+// Navigate with extra data
+context.push(Routes.todoDetailsPath('123'), extra: {'title': 'My Todo'});
+
+// Access extra in destination
+final extra = GoRouterState.of(context).extra as Map<String, dynamic>?;
+```
+
+## Shell Routes (Persistent UI)
+
+```dart
+final goRouter = GoRouter(
+  routes: [
+    ShellRoute(
+      builder: (context, state, child) {
+        return ScaffoldWithNavBar(child: child);
+      },
+      routes: [
+        GoRoute(path: Routes.home, builder: (_, __) => const HomeScreen()),
+        GoRoute(path: Routes.profile, builder: (_, __) => const ProfileScreen()),
+        GoRoute(path: Routes.settings, builder: (_, __) => const SettingsScreen()),
+      ],
+    ),
+  ],
+);
+```
+
+## Query Parameters
+
+```dart
+abstract class Routes {
+  static const search = '/search';
+  
+  static String searchPath({String? query, int? page}) {
+    final params = <String, String>{};
+    if (query != null) params['q'] = query;
+    if (page != null) params['page'] = page.toString();
+    return Uri(path: search, queryParameters: params.isEmpty ? null : params).toString();
+  }
+}
+
+// Usage
+context.go(Routes.searchPath(query: 'flutter', page: 2));
+
+// In route
+GoRoute(
+  path: Routes.search,
+  builder: (context, state) {
+    final query = state.uri.queryParameters['q'] ?? '';
+    final page = int.tryParse(state.uri.queryParameters['page'] ?? '1') ?? 1;
+    return SearchScreen(query: query, page: page);
+  },
+),
+```
+
+## ✅ DO's
+
+```dart
+// ✅ Use route constants
+context.go(Routes.home);
+context.push(Routes.todoDetailsPath(todo.id));
+
+// ✅ Type-safe params with helper methods
+static String todoDetailsPath(String id) => '/todos/$id';
+```
+
+## ❌ DON'Ts
+
+```dart
+// ❌ NEVER use raw strings
+context.go('/home');
+context.push('/todos/123');
+
+// ❌ NEVER hardcode paths in routes
+GoRoute(path: '/home', ...);  // Use Routes.home
+```
+
+## Quick Reference
+
+| Method | Behavior |
+|--------|----------|
+| `context.go(Routes.x)` | Navigate, replace stack |
+| `context.push(Routes.x)` | Navigate, add to stack |
+| `context.pop()` | Go back |
+| `context.pushReplacement()` | Replace current |
+| `Routes.xPath(id)` | Parameterized route helper |

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/performance.md

@@ -0,0 +1,99 @@
+# Performance Optimization
+
+## Profiling Commands
+
+```bash
+# Run in profile mode
+flutter run --profile
+
+# Analyze performance
+flutter analyze
+
+# DevTools
+flutter pub global activate devtools
+flutter pub global run devtools
+```
+
+## Common Optimizations
+
+### Const Widgets
+```dart
+// ❌ Rebuilds every time
+Widget build(BuildContext context) {
+  return Container(
+    padding: EdgeInsets.all(16),  // Creates new object
+    child: Text('Hello'),
+  );
+}
+
+// ✅ Const prevents rebuilds
+Widget build(BuildContext context) {
+  return Container(
+    padding: const EdgeInsets.all(16),
+    child: const Text('Hello'),
+  );
+}
+```
+
+### Selective Provider Watching
+```dart
+// ❌ Rebuilds on any user change
+final user = ref.watch(userProvider);
+return Text(user.name);
+
+// ✅ Only rebuilds when name changes
+final name = ref.watch(userProvider.select((u) => u.name));
+return Text(name);
+```
+
+### RepaintBoundary
+```dart
+// Isolate expensive widgets
+RepaintBoundary(
+  child: ComplexAnimatedWidget(),
+)
+```
+
+### Image Optimization
+```dart
+// Use cached_network_image
+CachedNetworkImage(
+  imageUrl: url,
+  placeholder: (_, __) => const CircularProgressIndicator(),
+  errorWidget: (_, __, ___) => const Icon(Icons.error),
+)
+
+// Resize images
+Image.network(
+  url,
+  cacheWidth: 200,  // Resize in memory
+  cacheHeight: 200,
+)
+```
+
+### Compute for Heavy Operations
+```dart
+// ❌ Blocks UI thread
+final result = heavyComputation(data);
+
+// ✅ Runs in isolate
+final result = await compute(heavyComputation, data);
+```
+
+## Performance Checklist
+
+| Check | Solution |
+|-------|----------|
+| Unnecessary rebuilds | Add `const`, use `select()` |
+| Large lists | Use `ListView.builder` |
+| Image loading | Use `cached_network_image` |
+| Heavy computation | Use `compute()` |
+| Jank in animations | Use `RepaintBoundary` |
+| Memory leaks | Dispose controllers |
+
+## DevTools Metrics
+
+- **Frame rendering time**: < 16ms for 60fps
+- **Widget rebuilds**: Minimize unnecessary rebuilds
+- **Memory usage**: Watch for leaks
+- **CPU profiler**: Identify bottlenecks

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/project-structure.md

@@ -0,0 +1,77 @@
+# Project Structure
+
+## Feature-Based Structure (Pragmatic Architecture)
+
+```
+lib/
+├── main.dart
+├── app.dart
+├── core/
+│   ├── config/             # Environment config
+│   ├── design_system/      # OneUp Design System (One* components)
+│   ├── network/            # Dio client, interceptors, Result type
+│   ├── providers/          # Session, auth, environment
+│   ├── router/             # GoRouter config, guards
+│   ├── cache/              # Cache service
+│   └── utils/              # Extensions, validators, logger
+├── features/
+│   └── <feature>/
+│       ├── data/
+│       │   ├── <feature>_api.dart          # Retrofit client
+│       │   ├── <feature>_cache.dart        # Local cache (optional)
+│       │   └── <feature>_repository.dart   # Conductor + inline DI provider
+│       ├── models/
+│       │   └── <feature>.dart              # ONE Freezed class (entity + fromJson)
+│       ├── <feature>_controller.dart       # ONE AsyncNotifier — reads + writes
+│       ├── <feature>_state.dart            # Freezed state (optional)
+│       ├── views/                          # Screens
+│       └── widgets/                        # Feature-specific widgets
+├── shared/
+│   ├── widgets/            # Shared UI components
+│   ├── models/             # Shared models
+│   └── utils/              # Shared utilities
+└── routes/
+    └── app_router.dart
+```
+
+## Feature Layer Responsibilities
+
+| Layer | Responsibility |
+|-------|----------------|
+| **data/** | API client, cache, repository (conductor) |
+| **models/** | Freezed models with fromJson (one class, not entity+model) |
+| **controller** | AsyncNotifier — reads + writes, owns feature state |
+| **views/** | UI screens |
+| **widgets/** | Feature-specific UI components |
+
+## Key Rules
+
+- No `domain/` folder unless feature has complex business rules
+- No `usecases/` folder — controller calls repo directly
+- No separate `providers/` folder — DI lives inline in repository file
+- No entity/model split — one Freezed class serves both
+- Each feature is self-contained (earn_point is its own feature, not nested in profile)
+
+## Main Entry Point
+
+```dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  runApp(const ProviderScope(child: MyApp()));
+}
+
+class MyApp extends ConsumerWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final router = ref.watch(routerProvider);
+    return MaterialApp.router(
+      routerConfig: router,
+      theme: AppTheme.light,
+      darkTheme: AppTheme.dark,
+      themeMode: ThemeMode.system,
+    );
+  }
+}
+```