sdd-full 4.6.2 → 4.8.0

package/skills/.agents/skills/flutter-build-responsive-layout/SKILL.md

@@ -0,0 +1,141 @@
+【claude code调用标识：flutter-build-responsive-layout】【trae调用标识：flutter-build-responsive-layout+Flutter开发】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代】
+
+---
+name: flutter-build-responsive-layout
+description: Use `LayoutBuilder`, `MediaQuery`, or `Expanded/Flexible` to create a layout that adapts to different screen sizes. Use when you need the UI to look good on both mobile and tablet/desktop form factors.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Tue, 21 Apr 2026 20:17:40 GMT
+---
+# Implementing Adaptive Layouts
+
+## Contents
+- [Space Measurement Guidelines](#space-measurement-guidelines)
+- [Widget Sizing and Constraints](#widget-sizing-and-constraints)
+- [Device and Orientation Behaviors](#device-and-orientation-behaviors)
+- [Workflow: Constructing an Adaptive Layout](#workflow-constructing-an-adaptive-layout)
+- [Workflow: Optimizing for Large Screens](#workflow-optimizing-for-large-screens)
+- [Examples](#examples)
+
+## Space Measurement Guidelines
+Determine the available space accurately to ensure layouts adapt to the app window, not just the physical device.
+
+*   **Use `MediaQuery.sizeOf(context)`** to get the size of the entire app window.
+*   **Use `LayoutBuilder`** to make layout decisions based on the parent widget's allocated space. Evaluate `constraints.maxWidth` to determine the appropriate widget tree to return.
+*   **Do not use `MediaQuery.orientationOf` or `OrientationBuilder`** near the top of the widget tree to switch layouts. Device orientation does not accurately reflect the available app window space.
+*   **Do not check for hardware types** (e.g., "phone" vs. "tablet"). Flutter apps run in resizable windows, multi-window modes, and picture-in-picture. Base all layout decisions strictly on available window space.
+
+## Widget Sizing and Constraints
+Understand and apply Flutter's core layout rule: **Constraints go down. Sizes go up. Parent sets position.**
+
+*   **Distribute Space:** Use `Expanded` and `Flexible` within `Row`, `Column`, or `Flex` widgets.
+    *   Use `Expanded` to force a child to fill all remaining available space (equivalent to `Flexible` with `fit: FlexFit.tight` and a `flex` factor of 1.0).
+    *   Use `Flexible` to allow a child to size itself up to a specific limit while still expanding/contracting. Use the `flex` factor to define the ratio of space consumption among siblings.
+*   **Constrain Width:** Prevent widgets from consuming all horizontal space on large screens. Wrap widgets like `GridView` or `ListView` in a `ConstrainedBox` or `Container` and define a `maxWidth` in the `BoxConstraints`.
+*   **Lazy Rendering:** Always use `ListView.builder` or `GridView.builder` when rendering lists with an unknown or large number of items.
+
+## Device and Orientation Behaviors
+Ensure the app behaves correctly across all device form factors and input methods.
+
+*   **Do not lock screen orientation.** Locking orientation causes severe layout issues on foldable devices, often resulting in letterboxing (the app centered with black borders). Android large format tiers require both portrait and landscape support.
+*   **Fallback for Locked Orientation:** If business requirements strictly mandate a locked orientation, use the `Display API` to retrieve physical screen dimensions instead of `MediaQuery`. `MediaQuery` fails to receive the larger window size in compatibility modes.
+*   **Support Multiple Inputs:** Implement support for basic mice, trackpads, and keyboard shortcuts. Ensure touch targets are appropriately sized and keyboard navigation is accessible.
+
+## Workflow: Constructing an Adaptive Layout
+
+Follow this workflow to implement a layout that adapts to the available `BoxConstraints`.
+
+**Task Progress:**
+- [ ] Identify the target widget that requires adaptive behavior.
+- [ ] Wrap the widget tree in a `LayoutBuilder`.
+- [ ] Extract the `constraints.maxWidth` from the builder callback.
+- [ ] Define an adaptive breakpoint (e.g., `largeScreenMinWidth = 600`).
+- [ ] **If `maxWidth > largeScreenMinWidth`:** Return a large-screen layout (e.g., a `Row` placing a navigation sidebar and content area side-by-side).
+- [ ] **If `maxWidth <= largeScreenMinWidth`:** Return a small-screen layout (e.g., a `Column` or standard navigation-style approach).
+- [ ] Run validator -> resize the application window -> review layout transitions -> fix overflow errors.
+
+## Workflow: Optimizing for Large Screens
+
+Follow this workflow to prevent UI elements from stretching unnaturally on large displays.
+
+**Task Progress:**
+- [ ] Identify full-width components (e.g., `ListView`, text blocks, forms).
+- [ ] **If optimizing a list:** Convert `ListView.builder` to `GridView.builder` using `SliverGridDelegateWithMaxCrossAxisExtent` to automatically adjust column counts based on window size.
+- [ ] **If optimizing a form or text block:** Wrap the component in a `ConstrainedBox`.
+- [ ] Apply `BoxConstraints(maxWidth: [optimal_width])` to the `ConstrainedBox`.
+- [ ] Wrap the `ConstrainedBox` in a `Center` widget to keep the constrained content centered on large screens.
+- [ ] Run validator -> test on desktop/tablet target -> review horizontal stretching -> adjust `maxWidth` or grid extents.
+
+## Examples
+
+### Adaptive Layout using LayoutBuilder
+Demonstrates switching between a mobile and desktop layout based on available width.
+
+```dart
+import 'package:flutter/material.dart';
+
+const double largeScreenMinWidth = 600.0;
+
+class AdaptiveLayout extends StatelessWidget {
+  const AdaptiveLayout({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        if (constraints.maxWidth > largeScreenMinWidth) {
+          return _buildLargeScreenLayout();
+        } else {
+          return _buildSmallScreenLayout();
+        }
+      },
+    );
+  }
+
+  Widget _buildLargeScreenLayout() {
+    return Row(
+      children: [
+        const SizedBox(width: 250, child: Placeholder(color: Colors.blue)),
+        const VerticalDivider(width: 1),
+        Expanded(child: const Placeholder(color: Colors.green)),
+      ],
+    );
+  }
+
+  Widget _buildSmallScreenLayout() {
+    return const Placeholder(color: Colors.green);
+  }
+}
+```
+
+### Constraining Width on Large Screens
+Demonstrates preventing a widget from consuming all horizontal space.
+
+```dart
+import 'package:flutter/material.dart';
+
+class ConstrainedContent extends StatelessWidget {
+  const ConstrainedContent({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: ConstrainedBox(
+          constraints: const BoxConstraints(
+            maxWidth: 800.0, // Maximum width for readability
+          ),
+          child: ListView.builder(
+            itemCount: 50,
+            itemBuilder: (context, index) {
+              return ListTile(
+                title: Text('Item $index'),
+              );
+            },
+          ),
+        ),
+      ),
+    );
+  }
+}
+```

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

@@ -0,0 +1,132 @@
+【claude code调用标识：flutter-fix-layout-issues】【trae调用标识：flutter-fix-layout-issues+Flutter开发】【流程场景：4.Bug处理】
+
+---
+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/.agents/skills/flutter-implement-json-serialization/SKILL.md

@@ -0,0 +1,155 @@
+【claude code调用标识：flutter-implement-json-serialization】【trae调用标识：flutter-implement-json-serialization+Flutter开发】【流程场景：1.完整3阶段SDD流程、3.小型功能迭代】
+
+---
+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/.agents/skills/flutter-setup-declarative-routing/SKILL.md

@@ -0,0 +1,257 @@
+【claude code调用标识：flutter-setup-declarative-routing】【trae调用标识：flutter-setup-declarative-routing+Flutter开发】【流程场景：1.完整3阶段SDD流程、2.从零开始新项目】
+
+---
+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();
+```