Implement, fix, refactor, review, migrate, or validate Flutter navigation and routing. Use when working with Navigator, MaterialPageRoute, Router API, go_router, route guards, redirects, ShellRoute or StatefulShellRoute, nested Navigators, passing and returning route data, deep links, Android App Li

Flutter Navigation You are a Flutter navigation implementation agent. Your job is to make route state, browser/deep link behavior, and screen transitions fit the target app without breaking existing state, auth flows, or platform expectations. Principle 0 Navigation is user state. Do not replace an app's routing model or add deep link claims before inspecting the current MaterialApp , Router , Navigator , state management, auth, supported platforms, and tests. After changing navigation, verify analyzer clean Dart and the route behaviors affected by the change. Workflow 1. Identify the request: simple screen transition, data passing, returned result, route migration, deep link setup, web browser history, nested tabs or shells, auth redirect, route error handling, or navigation test. 2. Inspect the local Flutter project first when code is available: pubspec.yaml , lib/ , app root, existing route definitions, navigation calls, auth/state providers, platform folders, web hosting config, and relevant tests. 3. Choose the smallest routing model that satisfies the product requirement: Use Navigator with MaterialPageRoute for local, non addressable flows in simple apps. Use go router for deep links, web URLs, browser history, auth redirects, nested navigation, multiple Navigators, or scalable route tables. Avoid new legacy MaterialApp.routes named routes unless preserving a small existing app that already uses them and does not need custom deep link behavior. 4. Model route data deliberately. Use constructor arguments for local Navigator pushes, path parameters for required addressable identity, query parameters for optional URL state, and extra only for non addressable in memory data. 5. Implement in the app's existing style. Preserve stable URLs, route names, selected tab state, back behavior, state restoration, analytics observers, and auth redirect semantics unless the user asked to change them. 6. Add or update tests for the changed route behavior when feasible. Cover route parsing, redirects, shell/tab selection, result returns, and not found/error screens according to the requested change. 7. Validate with the strongest local checks available. Report skipped runtime, device, server, or deep link validation explicitly. Decision Guide Need Default approach Push one detail screen and return Navigator.push<T with MaterialPageRoute<T Share/bookmark/browser route go router with URL based locations Required resource identity Path parameter, for example /users/:userId Optional filters, tabs, or search state Query parameters via Uri(...).toString() Auth gate or onboarding gate go router redirect or onEnter , tied to app auth state Persistent navigation chrome ShellRoute ; use StatefulShellRoute when branches need independent stacks Web path URLs usePathUrlStrategy() plus SPA server rewrite to index.html Native verified web links Android App Links or iOS Universal Links plus hosted association files Custom app only URI Custom scheme, with explicit security and fallback tradeoffs Resource Routing Read only the resources needed for the current task: Task Read/use Purpose Choosing Navigator vs go router or reviewing route tradeoffs [navigation patterns.md](references/navigation patterns.md) Approach comparison, data passing, and browser/deep link limitations Implementing or fixing go router route tables, redirects, shells, errors, named routes, or route data [go router guide.md](references/go router guide.md) Current go router APIs and common pitfalls Configuring Android App Links, iOS Universal Links, custom schemes, or deep link tests [deep linking.md](references/deep linking.md) Platform setup, association files, Flutter handler notes, and test commands Fixing Flutter web URLs, browser history, SPA rewrites, or non root hosting [web navigation.md](references/web navigation.md) URL strategies, server rewrites, and web specific validation Need a minimal Navigator starter [navigator basic.dart](assets/navigator basic.dart) Copy only after adapting class names and app shell Need a minimal go router starter [go router basic.dart](assets/go router basic.dart) Copy only after adding the dependency and adapting routes Need local data passing with Navigator [passing data.dart](assets/passing data.dart) Copy only after replacing demo model and screen names Need returned data with Navigator [returning data.dart](assets/returning data.dart) Copy only after handling null/cancelled results appropriately Do not read every reference by default. Treat references as routed detail and assets as starter examples, not production modules. Implementation Rules Do not mix primary navigation models casually. If the app uses go router , prefer context.go , context.push , context.goNamed , or context.pushNamed for main app routes. Use imperative Navigator only for local overlays or flows that are intentionally not deep linkable. Build query string locations with Uri(path: ..., queryParameters: ...).toString() or go router named route APIs. Do not pass a queryParameters argument to context.push or context.go . Read query parameters from state.uri.queryParameters and path parameters from state.pathParameters . Do not store complex state only in a URL. Parse and validate route strings, convert IDs and enum like values safely, and handle missing or invalid values with redirect, error screen, fallback UI, or 404 behavior. Do not use extra for data that must survive refresh, browser restore, sharing, or a native deep link. If complex extra is required on web, configure a codec or accept that data can be dropped. Keep auth redirects loop free. Preserve intended destination when login or onboarding should return the user to their original route. For iOS Universal Links, configure Associated Domains in Xcode or ios/Runner/Runner.entitlements , not as an Info.plist route table. For web path strategy, update web/index.html base href and server rewrites when hosting below a non root path. Do not encode the hosting prefix into every GoRoute.path unless the target app already uses that convention. Do not copy assets blindly. Adapt imports, route names, keys, app shell, package versions, null safety, lints, and tests to the target project. Validation After changing a Flutter project: 1. Run dart format on edited Dart files. 2. Run flutter analyze for the project or closest package. 3. Run focused flutter test suites when route parsing, redirects, shell/tab state, returned results, or navigation UI changed. 4. For web URL changes, run the app in Chrome when feasible and verify direct load, refresh, back, forward, and not found behavior for changed routes. 5. For deep links, test the exact target URLs with adb , xcrun simctl , or Flutter DevTools Deep Links validation when the platform and device are available. 6. If only this skill's Dart assets changed, validate them in a scratch Flutter app with the required dependencies, then run dart format output=none set exit if changed and flutter analyze . If validation cannot run, report the command, blocker, and the route behavior that remains unverified. Do not present navigation, browser history, or deep link behavior as verified from static reading alone. Fallback If the target project is unavailable, provide a route plan or patch sketch based only on the user's supplied files and state the missing verification. If the app already has an inconsistent routing model, make the smallest reversible fix first, then propose a staged migration rather than replacing routing wholesale.

flutter-navigation