agy-superpowers 5.0.8 → 5.0.9

package/template/agent/skills/mobile-developer/references/flutter.md

@@ -0,0 +1,291 @@
+# Flutter + Dart Reference
+
+> **Philosophy:** Everything is a widget. Composition over inheritance. Declarative UI with immutable state.
+> Flutter owns the pixels — no bridge, no compromise.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** `pubspec.yaml` file in project root.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `pubspec.yaml` | Dependencies, assets, metadata |
+| `analysis_options.yaml` | Linter rules and static analysis |
+| `lib/main.dart` | App entry point |
+| `android/` | Android-specific config (Gradle, manifest) |
+| `ios/` | iOS-specific config (Xcode project, Info.plist) |
+| `.dart_tool/` | Generated config (do not edit) |
+
+**Recommended project structure (feature-based):**
+
+```
+lib/
+  app/
+    app.dart                  # MaterialApp / CupertinoApp setup
+    router.dart               # GoRouter configuration
+  features/
+    auth/
+      presentation/
+        login_screen.dart
+        widgets/auth_form.dart
+      domain/
+        auth_repository.dart
+      data/
+        auth_api.dart
+    home/
+      presentation/
+        home_screen.dart
+  shared/
+    widgets/                  # Reusable UI widgets
+    extensions/               # Dart extension methods
+    theme/                    # ThemeData, colors, typography
+    utils/                    # Pure utility functions
+  main.dart                   # Entry point, ProviderScope
+```
+
+---
+
+## Architecture Patterns
+
+### State Management
+
+| Approach | Use When |
+|----------|----------|
+| **Riverpod** (recommended) | Most apps — compile-safe, testable, fine-grained reactivity |
+| **BLoC** | Teams familiar with reactive streams, complex event-driven flows |
+| **Provider** | Simpler apps, legacy codebases (Riverpod supersedes Provider) |
+| **GetX** | Rapid prototyping only — avoid for production (magic, hard to test) |
+
+**Riverpod patterns:**
+- Use `@riverpod` annotation (code generation) for type-safe providers
+- Prefer `AsyncNotifier` over `StateNotifier` (built-in async handling)
+- Keep providers at feature level, not global
+- Use `ref.watch()` for reactive, `ref.read()` for one-shot
+
+### Navigation
+
+**`go_router`** (recommended) — declarative, type-safe routing with deep link support.
+
+```dart
+final router = GoRouter(
+  routes: [
+    GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+    GoRoute(path: '/profile/:id', builder: (_, state) =>
+      ProfileScreen(id: state.pathParameters['id']!)),
+  ],
+);
+```
+
+- Use `ShellRoute` for persistent bottom navigation
+- Use `StatefulShellRoute` for preserving tab state
+- Define routes as constants to avoid typos
+
+### Widget Composition
+
+- **Extract widgets into separate classes** — don't build deeply nested widget trees in a single `build()` method
+- **Use `const` constructors** wherever possible — marks widget subtrees as immutable so Flutter skips rebuilding them
+- **Prefer composition over inheritance** — compose widgets from smaller pieces rather than extending
+- **Keep `build()` methods lean** — if a build method exceeds ~50 lines, extract sub-widgets
+
+---
+
+## Performance Optimization
+
+### Critical Rules
+
+| Metric | Target | Investigate |
+|--------|--------|-------------|
+| App startup | < 2s | > 3s |
+| Frame rendering | 16ms (60fps) | > 16ms (jank) |
+| APK size | < 20MB | > 50MB |
+| Memory (foreground) | < 150MB | > 300MB |
+
+### Key Optimizations
+
+1. **`const` constructors everywhere** — prevents unnecessary rebuilds. A `const` widget is created once and reused.
+
+```dart
+// ❌ Bad: rebuilds every time parent rebuilds
+return Container(color: Colors.blue, child: Text('Hello'));
+
+// ✅ Good: created once, never rebuilt
+return const SizedBox(height: 16);
+```
+
+2. **`RepaintBoundary`** — isolates repaint regions for complex widgets (animations, canvases). Prevents entire subtree from repainting.
+
+3. **`ListView.builder`** over `ListView` — lazy construction, only builds visible items.
+
+```dart
+// ❌ Bad: builds all children immediately
+ListView(children: items.map((i) => ItemCard(i)).toList());
+
+// ✅ Good: lazy, only visible items built
+ListView.builder(
+  itemCount: items.length,
+  itemBuilder: (_, i) => ItemCard(items[i]),
+);
+```
+
+4. **Impeller rendering engine** — Flutter's new graphics engine (default on iOS, opt-in on Android). Eliminates shader compilation jank.
+
+5. **Avoid `setState` in large widget trees** — use fine-grained state solutions (Riverpod, BLoC) to rebuild only affected widgets.
+
+6. **Profile with DevTools** — use the Performance overlay to identify jank, the Widget Inspector for layout issues, and the Memory view for leaks.
+
+### Shader Warmup
+
+For custom shaders, warm them up during a splash screen to avoid first-frame jank:
+
+```dart
+await ShaderConfiguration()
+  .warmupShader('shaders/gradient.frag');
+```
+
+---
+
+## Common Libraries Ecosystem
+
+| Category | Recommended | Alternative |
+|----------|-------------|-------------|
+| **State** | `riverpod` + `riverpod_generator` | `flutter_bloc`, `provider` |
+| **Navigation** | `go_router` | `auto_route` |
+| **HTTP** | `dio` | `http`, `chopper` |
+| **Local Storage** | `shared_preferences` | `hive`, `objectbox` |
+| **Database** | `drift` (SQLite) | `isar`, `floor` |
+| **Secure Storage** | `flutter_secure_storage` | — |
+| **Images** | `cached_network_image` | `extended_image` |
+| **JSON** | `json_serializable` + `freezed` | `built_value` |
+| **Icons** | `flutter_svg` + `hugeicons` | `font_awesome_flutter` |
+| **Forms** | `reactive_forms` | `flutter_form_builder` |
+| **Testing** | `mocktail` | `mockito` |
+| **Linting** | `very_good_analysis` | `flutter_lints` |
+| **Code Gen** | `build_runner` | — |
+| **Deep Links** | `go_router` (built-in) | `uni_links` |
+| **Analytics** | `firebase_analytics` | `amplitude_flutter` |
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| Deeply nested widget trees (10+ levels) | Unreadable, hard to debug, poor perf | Extract into named widget classes |
+| `setState` for global/shared state | Rebuilds entire widget subtree | Riverpod/BLoC for shared state |
+| `FutureBuilder` with inline `Future` | Re-fetches on every rebuild | Cache Future in `initState` or use `AsyncNotifier` |
+| Missing `const` constructors | Unnecessary rebuilds every frame | Add `const` to every eligible constructor |
+| `print()` for debugging | No log levels, clutters output | Use `dart:developer` `log()` or `logger` package |
+| `dynamic` types everywhere | No compile-time safety | Strong typing with generics + `freezed` |
+| Business logic in `build()` | Untestable, mixed concerns | Separate into providers/blocs/services |
+| Ignoring `dispose()` | Memory leaks (streams, controllers) | Always dispose controllers, subscriptions |
+| Platform channels for simple tasks | Complex, error-prone | Use existing plugins (`url_launcher`, etc.) |
+| Single massive `lib/main.dart` | Impossible to navigate or test | Feature-based folder structure |
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | `flutter_test` + `mocktail` | Business logic, providers, repositories |
+| **Widget** | `flutter_test` (widget testing) | Component rendering and interaction |
+| **BLoC** | `bloc_test` | State machine transitions |
+| **Integration** | `integration_test` package | Full app flows on real device/emulator |
+| **Golden** | `golden_toolkit` | Visual regression (screenshot comparison) |
+
+**Testing principles:**
+- Test behavior through public API, not widget internals
+- Use `pumpWidget` + `pumpAndSettle` for async widget tests
+- Mock dependencies at the repository/service boundary
+- Golden tests for design-system components (catch visual regressions)
+
+```dart
+testWidgets('shows login button', (tester) async {
+  await tester.pumpWidget(const MaterialApp(home: LoginScreen()));
+  expect(find.text('Log In'), findsOneWidget);
+});
+```
+
+---
+
+## Deployment & Distribution
+
+### Build Commands
+
+```bash
+# Debug (hot reload enabled)
+flutter run
+
+# Release build
+flutter build apk --release          # Android APK
+flutter build appbundle --release     # Android App Bundle (Play Store)
+flutter build ipa --release           # iOS (requires Xcode)
+
+# Analyze app size
+flutter build apk --analyze-size
+```
+
+### CI/CD Options
+
+| Tool | Strength |
+|------|----------|
+| **Codemagic** | Flutter-first CI/CD, code signing built-in |
+| **Fastlane** | Flexible, widely adopted, multi-platform |
+| **GitHub Actions** | Free for open source, custom workflows |
+| **Bitrise** | Mobile-focused, visual workflow builder |
+
+### OTA Code Push
+
+**Shorebird** — Flutter's code push solution. Push Dart code updates without app store review.
+
+```bash
+# Initialize Shorebird
+shorebird init
+
+# Create a release
+shorebird release android
+shorebird release ios
+
+# Push a patch
+shorebird patch android
+shorebird patch ios
+```
+
+**Limitations:** Dart code only — native code changes still require full build + store submission.
+
+### App Size Optimization
+- Use `--split-per-abi` for Android to reduce per-device APK size
+- Enable `--obfuscate --split-debug-info=symbols/` for release builds
+- Use deferred components for large features (lazy loading)
+- Audit unused packages with `dart pub outdated`
+
+---
+
+## Quick Reference — Granular Rules
+
+Individual Dart skill files in `flutter-rules/` with detailed patterns and
+best practices for the Dart language foundation that underpins Flutter development.
+
+> Source: [kevmoo/dash_skills](https://github.com/kevmoo/dash_skills) — Agent Skills for Dart & Flutter ecosystem
+
+### Dart Language & Best Practices
+
+- [dart-best-practices.md](flutter-rules/dart-best-practices.md) — Dart coding best practices
+- [dart-modern-features.md](flutter-rules/dart-modern-features.md) — Modern Dart features (patterns, records, sealed classes)
+- [dart-cli-app-best-practices.md](flutter-rules/dart-cli-app-best-practices.md) — CLI app patterns
+
+### Testing & Quality
+
+- [dart-test-fundamentals.md](flutter-rules/dart-test-fundamentals.md) — Test patterns with `package:test`
+- [dart-matcher-best-practices.md](flutter-rules/dart-matcher-best-practices.md) — Matcher expressions (expect, isA)
+- [dart-checks-migration.md](flutter-rules/dart-checks-migration.md) — Migrating from `package:matcher` to `package:checks`
+
+### Documentation & Maintenance
+
+- [dart-doc-validation.md](flutter-rules/dart-doc-validation.md) — Doc comment validation
+- [dart-package-maintenance.md](flutter-rules/dart-package-maintenance.md) — Package maintenance standards
+

package/template/agent/skills/mobile-developer/references/ios-native.md

@@ -0,0 +1,358 @@
+# iOS Native (SwiftUI / UIKit) Reference
+
+> **Philosophy:** Platform-native, human-interface-first. Respect Apple's design language.
+> SwiftUI for new code, UIKit for legacy and complex custom views.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** `*.xcodeproj`, `*.xcworkspace`, `Package.swift`, or `*.swift` files.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `*.xcodeproj` / `*.xcworkspace` | Xcode project/workspace configuration |
+| `Info.plist` | App metadata, permissions, capabilities |
+| `Package.swift` | Swift Package Manager dependencies |
+| `Podfile` | CocoaPods dependencies (legacy) |
+| `*.entitlements` | App capabilities (push, iCloud, etc.) |
+| `Assets.xcassets` | App icons, images, colors |
+
+**Recommended project structure:**
+
+```
+MyApp/
+  App/
+    MyAppApp.swift              # @main entry point
+    ContentView.swift           # Root view
+  Features/
+    Auth/
+      Views/LoginView.swift
+      ViewModels/AuthViewModel.swift
+      Models/User.swift
+      Services/AuthService.swift
+    Home/
+      Views/HomeView.swift
+      ViewModels/HomeViewModel.swift
+  Shared/
+    Components/                 # Reusable SwiftUI views
+    Extensions/                 # Swift extensions
+    Services/                   # Networking, storage
+    Utilities/                  # Helpers
+  Resources/
+    Assets.xcassets
+    Localizable.xcstrings
+```
+
+---
+
+## Architecture Patterns
+
+### MVVM (Recommended for SwiftUI)
+
+```swift
+// ViewModel
+@Observable
+class ProfileViewModel {
+    var user: User?
+    var isLoading = false
+    var error: Error?
+
+    func loadProfile() async {
+        isLoading = true
+        defer { isLoading = false }
+        do {
+            user = try await userService.fetchProfile()
+        } catch {
+            self.error = error
+        }
+    }
+}
+
+// View
+struct ProfileView: View {
+    @State private var viewModel = ProfileViewModel()
+
+    var body: some View {
+        Group {
+            if viewModel.isLoading {
+                ProgressView()
+            } else if let user = viewModel.user {
+                UserProfileContent(user: user)
+            }
+        }
+        .task { await viewModel.loadProfile() }
+    }
+}
+```
+
+### State Management
+
+| Property Wrapper | Use When |
+|-----------------|----------|
+| `@State` | View-local value types (toggles, text input) |
+| `@Binding` | Pass write access to a child view |
+| `@Observable` (iOS 17+) | ViewModel or shared model classes |
+| `@Environment` | Inject dependencies or system values |
+| `@AppStorage` | Persist simple values to UserDefaults |
+
+**SwiftData** (iOS 17+) replaces Core Data for persistence:
+
+```swift
+@Model
+class Task {
+    var title: String
+    var isComplete: Bool
+    var createdAt: Date
+
+    init(title: String) {
+        self.title = title
+        self.isComplete = false
+        self.createdAt = .now
+    }
+}
+```
+
+### The Composable Architecture (TCA)
+
+For complex apps needing predictable state, testable effects, and feature composition:
+- Centralized state tree with reducers
+- Side effects managed through `Effect` type
+- Built-in testing with `TestStore`
+- Steep learning curve but excellent testability
+
+### Navigation
+
+**NavigationStack** (iOS 16+) — type-safe, value-driven navigation:
+
+```swift
+NavigationStack(path: $path) {
+    HomeView()
+        .navigationDestination(for: Item.self) { item in
+            ItemDetailView(item: item)
+        }
+}
+```
+
+- Use `NavigationSplitView` for iPad/Mac adaptive layouts
+- Use `sheet()` and `fullScreenCover()` for modals
+- Deep link handling through `.onOpenURL`
+
+---
+
+## Performance Optimization
+
+### Critical Thresholds
+
+| Metric | Target | Investigate |
+|--------|--------|-------------|
+| App launch (time to first frame) | < 1s | > 2s |
+| Memory (foreground) | < 100MB | > 200MB |
+| UI frame rate | 60fps / 120fps (ProMotion) | < 60fps |
+| Binary size | < 30MB | > 100MB |
+
+### Key Optimizations
+
+1. **`LazyVStack` / `LazyHStack`** — only creates views when they scroll into the visible area.
+
+```swift
+// ❌ Bad: creates all rows immediately
+VStack { ForEach(items) { ItemRow(item: $0) } }
+
+// ✅ Good: lazy, only visible rows created
+LazyVStack { ForEach(items) { ItemRow(item: $0) } }
+```
+
+2. **Avoid recomputing views** — extract subviews, use `@Observable` fine-grained tracking.
+
+3. **Background tasks** — use `BGTaskScheduler` for deferred work (push refresh, data sync). Minimize wake-ups for battery.
+
+4. **Network monitoring** — use `NWPathMonitor` to detect connectivity changes and adapt behavior.
+
+5. **Instruments profiling:**
+   - **Time Profiler** — find slow functions
+   - **Allocations** — track memory leaks
+   - **SwiftUI** instrument — identify excessive view body evaluations
+   - **Energy Log** — battery impact analysis
+
+---
+
+## Common Libraries Ecosystem
+
+| Category | Recommended | Alternative |
+|----------|-------------|-------------|
+| **Networking** | `URLSession` (built-in) | `Alamofire` |
+| **JSON** | `Codable` (built-in) | — |
+| **Storage (simple)** | `UserDefaults` / `@AppStorage` | — |
+| **Storage (encrypted)** | `Keychain Services` | `KeychainAccess` |
+| **Database** | `SwiftData` (iOS 17+) | `Core Data`, `GRDB`, `Realm` |
+| **Images** | `AsyncImage` (built-in) | `Kingfisher`, `Nuke` |
+| **DI** | `@Environment` / manual | `Factory`, `Swinject` |
+| **Analytics** | `Firebase Analytics` | `Mixpanel`, `Amplitude` |
+| **Testing** | `Swift Testing` + `XCTest` | — |
+| **Linting** | `SwiftLint` | `swift-format` |
+| **Package Manager** | Swift Package Manager | CocoaPods (legacy) |
+
+**Prefer built-in frameworks** — Apple provides excellent APIs. Only add third-party dependencies when built-in solutions are insufficient.
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| Massive `body` properties (100+ lines) | SwiftUI compiles slow, unreadable | Extract into named subviews |
+| Force unwrapping (`!`) | Crash at runtime | `guard let`, `if let`, or `??` with default |
+| Missing `@MainActor` on UI updates | Crash from background thread | Annotate ViewModels with `@MainActor` |
+| Synchronous network calls | Blocks main thread, UI freezes | `async/await` with `Task {}` |
+| Ignoring `Sendable` (Swift 6) | Concurrency warnings → errors in Swift 6 | Mark types `Sendable`, use actors for mutable state |
+| Core Data for new projects | Complex, boilerplate-heavy | SwiftData (iOS 17+) for new code |
+| `ObservableObject` (legacy) | Less efficient than `@Observable` | Use `@Observable` macro (iOS 17+) |
+| `AnyView` for type erasure | Breaks SwiftUI diffing, poor performance | Use `@ViewBuilder`, generics, or concrete types |
+| Navigation via state booleans | Unscalable, unmaintainable | `NavigationStack` with value-based navigation |
+| Tight coupling to UIKit | Limits SwiftUI adoption | Use `UIViewRepresentable` only when needed |
+
+### Swift 6 Concurrency
+
+Swift 6 enforces strict concurrency checking:
+- All mutable shared state must be in `actor` or `@MainActor`
+- Types crossing concurrency boundaries must conform to `Sendable`
+- Enable strict concurrency checking early: `SWIFT_STRICT_CONCURRENCY = complete`
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | `Swift Testing` (new) / `XCTest` | Logic, ViewModels, services |
+| **UI** | `XCUITest` | Full UI flow automation |
+| **Snapshot** | `swift-snapshot-testing` | Visual regression |
+| **Performance** | `XCTest` + `measure {}` | Execution time benchmarks |
+
+**Swift Testing** (Xcode 16+) replaces XCTest with modern syntax:
+
+```swift
+import Testing
+
+@Test func userDisplayName() {
+    let user = User(first: "John", last: "Doe")
+    #expect(user.displayName == "John Doe")
+}
+
+@Test(arguments: ["", " ", "   "])
+func rejectsBlankNames(name: String) {
+    #expect(throws: ValidationError.self) {
+        try User(name: name)
+    }
+}
+```
+
+- Use `@MainActor` on tests that touch UI state
+- Mock network with `URLProtocol` subclass — no third-party mock library needed
+- Golden/snapshot testing for design-system components
+
+---
+
+## Deployment & Distribution
+
+### Build & Release
+
+```bash
+# Archive for distribution
+xcodebuild archive -scheme MyApp -archivePath build/MyApp.xcarchive
+
+# Export IPA
+xcodebuild -exportArchive -archivePath build/MyApp.xcarchive \
+  -exportOptionsPlist ExportOptions.plist -exportPath build/
+```
+
+### Distribution Channels
+
+| Channel | Use When |
+|---------|----------|
+| **TestFlight** | Internal + external beta testing (up to 10,000 testers) |
+| **App Store Connect** | Production release |
+| **Ad Hoc** | Direct install for registered devices |
+| **Enterprise** | In-house apps (requires Enterprise Program) |
+
+### CI/CD
+
+| Tool | Strength |
+|------|----------|
+| **Xcode Cloud** | Apple-native, integrated with App Store Connect |
+| **Fastlane** | Community standard, `match` for code signing |
+| **GitHub Actions** + `macos-latest` | Free for open source |
+
+### Fastlane essentials
+
+```bash
+# Install
+gem install fastlane
+
+# Beta release
+fastlane beta    # build + upload to TestFlight
+
+# Production release
+fastlane release # build + upload to App Store
+```
+
+### Entitlements & Capabilities
+- Configure in Xcode → Signing & Capabilities
+- Push Notifications, In-App Purchase, iCloud, HealthKit each require specific entitlements
+- App Groups for sharing data between app and extensions (widgets, intents)
+
+---
+
+## Quick Reference — Granular Rules
+
+Individual SwiftUI reference files in `ios-rules/` with detailed patterns,
+code examples, and best practices for modern iOS/macOS development.
+
+> Source: [AvdLee/SwiftUI-Agent-Skill](https://github.com/AvdLee/SwiftUI-Agent-Skill) — SwiftUI Expert Skill by Antoine van der Lee
+
+### State & Architecture
+
+- [state-management.md](ios-rules/state-management.md) — Property wrappers, @Observable, data flow patterns
+- [view-structure.md](ios-rules/view-structure.md) — View extraction, composition, identity stability
+
+### View Composition & Layout
+
+- [layout-best-practices.md](ios-rules/layout-best-practices.md) — Layout patterns, GeometryReader alternatives
+- [scroll-patterns.md](ios-rules/scroll-patterns.md) — ScrollViewReader, programmatic scrolling
+- [image-optimization.md](ios-rules/image-optimization.md) — AsyncImage, downsampling, caching
+
+### Performance & Lists
+
+- [performance-patterns.md](ios-rules/performance-patterns.md) — Hot-path optimizations, update control
+- [list-patterns.md](ios-rules/list-patterns.md) — ForEach identity, list performance
+
+### Animation
+
+- [animation-basics.md](ios-rules/animation-basics.md) — Core concepts, implicit/explicit, timing
+- [animation-advanced.md](ios-rules/animation-advanced.md) — Performance, interpolation, complex chains
+- [animation-transitions.md](ios-rules/animation-transitions.md) — View transitions, matchedGeometryEffect
+
+### Navigation & Sheets
+
+- [sheet-navigation-patterns.md](ios-rules/sheet-navigation-patterns.md) — Sheets, type-safe navigation state
+
+### Swift Charts
+
+- [charts.md](ios-rules/charts.md) — Marks, axes, selection, styling, Chart3D
+- [charts-accessibility.md](ios-rules/charts-accessibility.md) — Charts accessibility, fallback strategies
+
+### macOS
+
+- [macos-scenes.md](ios-rules/macos-scenes.md) — Scene lifecycle, multi-window, menu bar
+- [macos-views.md](ios-rules/macos-views.md) — macOS-specific views, platform differences
+- [macos-window-styling.md](ios-rules/macos-window-styling.md) — Window chrome, toolbar, title bar styling
+
+### Modern APIs
+
+- [liquid-glass.md](ios-rules/liquid-glass.md) — iOS 26+ glass effects, fallback patterns
+- [latest-apis.md](ios-rules/latest-apis.md) — Deprecated-to-modern migration (iOS 15–26+)
+- [accessibility-patterns.md](ios-rules/accessibility-patterns.md) — VoiceOver, Dynamic Type, traits
+