sdd-full 4.8.0 → 4.8.1

package/skills/flutter-skills/skills/flutter-fix-layout-issues/SKILL.md

@@ -1,130 +0,0 @@
----
-name: flutter-fix-layout-issues
-description: Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 19:45:59 GMT
----
-# Resolving Flutter Layout Errors
-
-## Contents
-- [Constraint Violation Diagnostics](#constraint-violation-diagnostics)
-- [Layout Error Resolution Workflow](#layout-error-resolution-workflow)
-- [Examples](#examples)
-
-## Constraint Violation Diagnostics
-
-Flutter layout operates on a strict rule: **Constraints go down. Sizes go up. Parent sets position.** Layout errors occur when this negotiation fails, typically due to unbounded constraints or unconstrained children. 
-
-Diagnose layout failures using the following error signatures:
-
-*   **"Vertical viewport was given unbounded height"**: Triggered when a scrollable widget (`ListView`, `GridView`) is placed inside an unconstrained vertical parent (`Column`). The parent provides infinite height, and the child attempts to expand infinitely.
-*   **"An InputDecorator...cannot have an unbounded width"**: Triggered when a `TextField` or `TextFormField` is placed inside an unconstrained horizontal parent (`Row`). The text field attempts to determine its width based on infinite available space.
-*   **"RenderFlex overflowed"**: Triggered when a child of a `Row` or `Column` requests a size larger than the parent's allocated constraints. Visually indicated by yellow and black warning stripes.
-*   **"Incorrect use of ParentData widget"**: Triggered when a `ParentDataWidget` is not a direct descendant of its required ancestor. (e.g., `Expanded` outside a `Flex`, `Positioned` outside a `Stack`).
-*   **"RenderBox was not laid out"**: A cascading side-effect error. Ignore this and look further up the stack trace for the primary constraint violation (usually an unbounded height/width error).
-
-## Layout Error Resolution Workflow
-
-Copy and use this checklist to systematically resolve layout constraint violations.
-
-### Task Progress
-- [ ] Run the application in debug mode to capture the exact layout exception in the console.
-- [ ] Identify the primary error message (ignore cascading "RenderBox was not laid out" errors).
-- [ ] Apply the conditional fix based on the specific error type:
-  - **If "Vertical viewport was given unbounded height"**: Wrap the scrollable child (`ListView`, `GridView`) in an `Expanded` widget to consume remaining space, or wrap it in a `SizedBox` to provide an absolute height constraint.
-  - **If "An InputDecorator...cannot have an unbounded width"**: Wrap the `TextField` or `TextFormField` in an `Expanded` or `Flexible` widget.
-  - **If "RenderFlex overflowed"**: Constrain the overflowing child by wrapping it in an `Expanded` widget (to force it to fit) or a `Flexible` widget (to allow it to be smaller than the allocated space).
-  - **If "Incorrect use of ParentData widget"**: Move the `ParentDataWidget` to be a direct child of its required parent. Ensure `Expanded`/`Flexible` are direct children of `Row`/`Column`/`Flex`. Ensure `Positioned` is a direct child of `Stack`.
-- [ ] Execute Flutter hot reload.
-- [ ] Run validator -> review errors -> fix: Inspect the UI to verify the red/grey error screen or yellow/black overflow stripes are resolved. If new layout errors appear, repeat the workflow.
-
-## Examples
-
-### Fixing Unbounded Height (ListView in Column)
-
-**Input (Error State):**
-```dart
-// Throws "Vertical viewport was given unbounded height"
-Column(
-  children: <Widget>[
-    const Text('Header'),
-    ListView(
-      children: const <Widget>[
-        ListTile(title: Text('Item 1')),
-        ListTile(title: Text('Item 2')),
-      ],
-    ),
-  ],
-)
-```
-
-**Output (Resolved State):**
-```dart
-// Wrap ListView in Expanded to constrain its height to the remaining Column space
-Column(
-  children: <Widget>[
-    const Text('Header'),
-    Expanded(
-      child: ListView(
-        children: const <Widget>[
-          ListTile(title: Text('Item 1')),
-          ListTile(title: Text('Item 2')),
-        ],
-      ),
-    ),
-  ],
-)
-```
-
-### Fixing Unbounded Width (TextField in Row)
-
-**Input (Error State):**
-```dart
-// Throws "An InputDecorator...cannot have an unbounded width"
-Row(
-  children: [
-    const Icon(Icons.search),
-    TextField(), 
-  ],
-)
-```
-
-**Output (Resolved State):**
-```dart
-// Wrap TextField in Expanded to constrain its width to the remaining Row space
-Row(
-  children: [
-    const Icon(Icons.search),
-    Expanded(
-      child: TextField(),
-    ),
-  ],
-)
-```
-
-### Fixing RenderFlex Overflow
-
-**Input (Error State):**
-```dart
-// Throws "A RenderFlex overflowed by X pixels on the right"
-Row(
-  children: [
-    const Icon(Icons.info),
-    const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
-  ],
-)
-```
-
-**Output (Resolved State):**
-```dart
-// Wrap the Text widget in Expanded to force it to wrap within the available constraints
-Row(
-  children: [
-    const Icon(Icons.info),
-    Expanded(
-      child: const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
-    ),
-  ],
-)
-```

package/skills/flutter-skills/skills/flutter-implement-json-serialization/SKILL.md

@@ -1,153 +0,0 @@
----
-name: flutter-implement-json-serialization
-description: Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 21:44:50 GMT
----
-# Serializing JSON Manually in Flutter
-
-## Contents
-- [Core Guidelines](#core-guidelines)
-- [Workflow: Implementing a Serializable Model](#workflow-implementing-a-serializable-model)
-- [Workflow: Fetching and Parsing JSON](#workflow-fetching-and-parsing-json)
-- [Examples](#examples)
-
-## Core Guidelines
-
-- **Import `dart:convert`**: Utilize Flutter's built-in `dart:convert` library for manual JSON encoding (`jsonEncode`) and decoding (`jsonDecode`).
-- **Enforce Type Safety**: Always cast the `dynamic` result of `jsonDecode()` to the expected type, typically `Map<String, dynamic>` for objects or `List<dynamic>` for arrays.
-- **Encapsulate Serialization Logic**: Define plain model classes containing properties corresponding to the JSON structure. Implement a `fromJson` factory constructor and a `toJson` method within the model.
-- **Handle Background Parsing**: If parsing large JSON documents (execution time > 16ms), offload the parsing logic to a separate isolate using Flutter's `compute()` function to prevent UI jank.
-- **Throw Exceptions on Failure**: When handling HTTP responses, throw an exception if the status code is not successful (e.g., not 200 OK or 201 Created). Do not return `null`.
-
-## Workflow: Implementing a Serializable Model
-
-Use this checklist to implement manual JSON serialization for a data model.
-
-**Task Progress:**
-- [ ] Define the plain model class with `final` properties.
-- [ ] Implement the `factory Model.fromJson(Map<String, dynamic> json)` constructor.
-- [ ] Implement the `Map<String, dynamic> toJson()` method.
-- [ ] Write unit tests for both serialization methods.
-- [ ] Run validator -> review type mismatch errors -> fix casting logic.
-
-1. **Define the Model**: Create a class with properties matching the JSON keys.
-2. **Implement `fromJson`**: Extract values from the `Map` and cast them to the appropriate Dart types. Use pattern matching or explicit casting.
-3. **Implement `toJson`**: Return a `Map<String, dynamic>` mapping the class properties back to their JSON string keys.
-4. **Validate**: Execute unit tests to ensure type safety, autocompletion, and compile-time exception handling function correctly.
-
-## Workflow: Fetching and Parsing JSON
-
-Use this conditional workflow when retrieving and parsing JSON from a network request.
-
-**Task Progress:**
-- [ ] Execute the HTTP request.
-- [ ] Validate the response status code.
-- [ ] Determine parsing strategy (Synchronous vs. Isolate).
-- [ ] Decode and map the JSON to the model.
-
-1. **Execute Request**: Use the `http` package to perform the network call.
-2. **Validate Response**: 
-   - If `response.statusCode == 200` (or 201 for POST), proceed to parsing.
-   - If the status code indicates failure, throw an `Exception`.
-3. **Determine Parsing Strategy**:
-   - If parsing a **small payload** (e.g., a single object), parse synchronously on the main thread.
-   - If parsing a **large payload** (e.g., an array of thousands of objects), use `compute(parseFunction, response.body)` to parse in a background isolate.
-4. **Decode and Map**: Pass the decoded JSON to your model's `fromJson` constructor.
-
-## Examples
-
-### High-Fidelity Model Implementation
-
-```dart
-import 'dart:convert';
-
-class User {
-  final int id;
-  final String name;
-  final String email;
-
-  const User({
-    required this.id,
-    required this.name,
-    required this.email,
-  });
-
-  // Factory constructor for deserialization
-  factory User.fromJson(Map<String, dynamic> json) {
-    return switch (json) {
-      {
-        'id': int id,
-        'name': String name,
-        'email': String email,
-      } => 
-        User(
-          id: id,
-          name: name,
-          email: email,
-        ),
-      _ => throw const FormatException('Failed to load User.'),
-    };
-  }
-
-  // Method for serialization
-  Map<String, dynamic> toJson() {
-    return {
-      'id': id,
-      'name': name,
-      'email': email,
-    };
-  }
-}
-```
-
-### Synchronous Parsing (Small Payload)
-
-```dart
-import 'dart:convert';
-import 'package:http/http.dart' as http;
-
-Future<User> fetchUser(http.Client client, int userId) async {
-  final response = await client.get(
-    Uri.parse('https://api.example.com/users/$userId'),
-    headers: {'Accept': 'application/json'},
-  );
-
-  if (response.statusCode == 200) {
-    // Decode returns dynamic, cast to Map<String, dynamic>
-    final Map<String, dynamic> jsonMap = jsonDecode(response.body) as Map<String, dynamic>;
-    return User.fromJson(jsonMap);
-  } else {
-    throw Exception('Failed to load user');
-  }
-}
-```
-
-### Background Parsing (Large Payload)
-
-```dart
-import 'dart:convert';
-import 'package:flutter/foundation.dart';
-import 'package:http/http.dart' as http;
-
-// Top-level function required for compute()
-List<User> parseUsers(String responseBody) {
-  final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
-  return parsed.map<User>((json) => User.fromJson(json)).toList();
-}
-
-Future<List<User>> fetchUsers(http.Client client) async {
-  final response = await client.get(
-    Uri.parse('https://api.example.com/users'),
-    headers: {'Accept': 'application/json'},
-  );
-
-  if (response.statusCode == 200) {
-    // Offload expensive parsing to a background isolate
-    return compute(parseUsers, response.body);
-  } else {
-    throw Exception('Failed to load users');
-  }
-}
-```

package/skills/flutter-skills/skills/flutter-setup-declarative-routing/SKILL.md

@@ -1,255 +0,0 @@
----
-name: flutter-setup-declarative-routing
-description: Configure `MaterialApp.router` using a package like `go_router` for advanced URL-based navigation. Use when developing web applications or mobile apps that require specific deep linking and browser history support.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 21:08:03 GMT
----
-# Implementing Routing and Deep Linking
-
-## Contents
-- [Core Concepts](#core-concepts)
-- [Workflow: Initializing the Application and Router](#workflow-initializing-the-application-and-router)
-- [Workflow: Configuring Platform Deep Linking](#workflow-configuring-platform-deep-linking)
-- [Workflow: Implementing Nested Navigation](#workflow-implementing-nested-navigation)
-- [Examples](#examples)
-
-## Core Concepts
-
-Use the `go_router` package for declarative routing in Flutter. It provides a robust API for complex routing scenarios, deep linking, and nested navigation. 
-
-- **GoRouter**: The central configuration object defining the application's route tree.
-- **GoRoute**: A standard route mapping a URL path to a Flutter screen.
-- **ShellRoute / StatefulShellRoute**: Wraps child routes in a persistent UI shell (e.g., a `BottomNavigationBar`). `StatefulShellRoute` maintains the state of parallel navigation branches.
-- **Path URL Strategy**: Removes the default `#` fragment from web URLs, essential for clean deep linking across platforms.
-
-## Workflow: Initializing the Application and Router
-
-Follow this workflow to bootstrap a new Flutter application with `go_router` and configure the root routing mechanism.
-
-### Task Progress
-- [ ] Create the Flutter application.
-- [ ] Add the `go_router` dependency.
-- [ ] Configure the URL strategy for web/deep linking.
-- [ ] Implement the `GoRouter` configuration.
-- [ ] Bind the router to `MaterialApp.router`.
-
-### 1. Scaffold the Application
-Run the following commands to create the app and add the required routing package:
-```bash
-flutter create <app-name>
-cd <app-name>
-flutter pub add go_router
-```
-
-### 2. Configure the Router
-Define a top-level `GoRouter` instance. Handle authentication or state-based routing using the `redirect` parameter.
-
-```dart
-import 'package:flutter/material.dart';
-import 'package:go_router/go_router.dart';
-import 'package:flutter_web_plugins/url_strategy.dart';
-
-void main() {
-  // Use path URL strategy to remove the '#' from web URLs
-  usePathUrlStrategy();
-  runApp(const MyApp());
-}
-
-final GoRouter _router = GoRouter(
-  initialLocation: '/',
-  routes: [
-    GoRoute(
-      path: '/',
-      builder: (context, state) => const HomeScreen(),
-      routes: [
-        GoRoute(
-          path: 'details/:id',
-          builder: (context, state) => DetailsScreen(id: state.pathParameters['id']!),
-        ),
-      ],
-    ),
-  ],
-  errorBuilder: (context, state) => ErrorScreen(error: state.error),
-);
-
-class MyApp extends StatelessWidget {
-  const MyApp({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp.router(
-      routerConfig: _router,
-      title: 'Routing App',
-    );
-  }
-}
-```
-
-## Workflow: Configuring Platform Deep Linking
-
-Configure the native platforms to intercept specific URLs and route them into the Flutter application.
-
-### Task Progress
-- [ ] Determine target platforms (iOS, Android, or both).
-- [ ] Apply conditional configuration for Android (Manifest + Asset Links).
-- [ ] Apply conditional configuration for iOS (Plist + Entitlements + AASA).
-- [ ] Run validator -> review errors -> fix.
-
-### If configuring for Android:
-1. **Modify `AndroidManifest.xml`**: Add the intent filter inside the `<activity>` tag for `.MainActivity`.
-```xml
-<intent-filter android:autoVerify="true">
-    <action android:name="android.intent.action.VIEW" />
-    <category android:name="android.intent.category.DEFAULT" />
-    <category android:name="android.intent.category.BROWSABLE" />
-    <data android:scheme="http" android:host="yourdomain.com" />
-    <data android:scheme="https" />
-</intent-filter>
-```
-2. **Host `assetlinks.json`**: Serve the following JSON at `https://yourdomain.com/.well-known/assetlinks.json`.
-```json
-[{
-  "relation": ["delegate_permission/common.handle_all_urls"],
-  "target": {
-    "namespace": "android_app",
-    "package_name": "com.yourcompany.yourapp",
-    "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
-  }
-}]
-```
-
-### If configuring for iOS:
-1. **Modify `Info.plist`**: Opt-in to Flutter's default deep link handler. 
-*Note: If using a third-party deep linking plugin (e.g., `app_links`), set this to `NO` to prevent conflicts.*
-```xml
-<key>FlutterDeepLinkingEnabled</key>
-<true/>
-```
-2. **Modify `Runner.entitlements`**: Add the associated domain.
-```xml
-<key>com.apple.developer.associated-domains</key>
-<array>
-  <string>applinks:yourdomain.com</string>
-</array>
-```
-3. **Host `apple-app-site-association`**: Serve the following JSON (without a `.json` extension) at `https://yourdomain.com/.well-known/apple-app-site-association`.
-```json
-{
-  "applinks": {
-    "apps": [],
-    "details": [{
-      "appIDs": ["TEAM_ID.com.yourcompany.yourapp"],
-      "paths": ["*"],
-      "components": [{"/": "/*"}]
-    }]
-  }
-}
-```
-
-### Validation Loop
-Run validator -> review errors -> fix.
-- **Android**: Test using ADB.
-  ```bash
-  adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://yourdomain.com/details/123"' com.yourcompany.yourapp
-  ```
-- **iOS**: Test using `xcrun` on a booted simulator.
-  ```bash
-  xcrun simctl openurl booted https://yourdomain.com/details/123
-  ```
-
-## Workflow: Implementing Nested Navigation
-
-Use `StatefulShellRoute` to implement persistent UI shells (like a bottom navigation bar) that maintain the state of their child routes.
-
-### Task Progress
-- [ ] Define `StatefulShellRoute.indexedStack` in the `GoRouter` configuration.
-- [ ] Create `StatefulShellBranch` instances for each navigation tab.
-- [ ] Implement the shell widget using `StatefulNavigationShell`.
-
-```dart
-final GoRouter _router = GoRouter(
-  initialLocation: '/home',
-  routes: [
-    StatefulShellRoute.indexedStack(
-      builder: (context, state, navigationShell) {
-        return ScaffoldWithNavBar(navigationShell: navigationShell);
-      },
-      branches: [
-        StatefulShellBranch(
-          routes: [
-            GoRoute(
-              path: '/home',
-              builder: (context, state) => const HomeScreen(),
-            ),
-          ],
-        ),
-        StatefulShellBranch(
-          routes: [
-            GoRoute(
-              path: '/settings',
-              builder: (context, state) => const SettingsScreen(),
-            ),
-          ],
-        ),
-      ],
-    ),
-  ],
-);
-```
-
-## Examples
-
-### High-Fidelity Shell Widget Implementation
-Implement the UI shell that consumes the `StatefulNavigationShell` to handle branch switching.
-
-```dart
-class ScaffoldWithNavBar extends StatelessWidget {
-  const ScaffoldWithNavBar({
-    required this.navigationShell,
-    super.key,
-  });
-
-  final StatefulNavigationShell navigationShell;
-
-  void _goBranch(int index) {
-    navigationShell.goBranch(
-      index,
-      // Support navigating to the initial location when tapping the active tab.
-      initialLocation: index == navigationShell.currentIndex,
-    );
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      body: navigationShell,
-      bottomNavigationBar: NavigationBar(
-        selectedIndex: navigationShell.currentIndex,
-        onDestinationSelected: _goBranch,
-        destinations: const [
-          NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
-          NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'),
-        ],
-      ),
-    );
-  }
-}
-```
-
-### Programmatic Navigation
-Use the `context.go()` and `context.push()` extension methods provided by `go_router`.
-
-```dart
-// Replaces the current route stack with the target route (Declarative)
-context.go('/details/123');
-
-// Pushes the target route onto the existing stack (Imperative)
-context.push('/details/123');
-
-// Navigates using a named route and path parameters
-context.goNamed('details', pathParameters: {'id': '123'});
-
-// Pops the current route
-context.pop();
-```