Flutter Auto Route NavigationSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: flutter-auto-route-navigation
description: Implement typed routing, nested routes, and auth guards using auto_route in Flutter. Use when the task explicitly uses auto_route or its generated router; defer generic deep-link setup and other routing libraries.
metadata:
  triggers:
    files:
    - '**/router.dart'
    - '**/app_router.dart'
    keywords:
    - AutoRoute
    - AutoRouter
    - router
    - guards
    - navigate
    - push
---

# AutoRoute Navigation

## **Priority: P1 (HIGH)**

## Structure

```text
core/router/
├── app_router.dart       # Router configuration
└── app_router.gr.dart    # Generated routes
```

## Implementation Workflow

1. **Annotate pages** — Mark all screen/page widgets with `@RoutePage()`.
2. **Configure router** — Extend `_$AppRouter` and annotate with `@AutoRouterConfig`.
3. **Navigate with types** — Use generated route classes (e.g., `HomeRoute()`). Never use strings.
4. **Add guards** — Implement `AutoRouteGuard` for authentication/authorization logic.
5. **Handle parameters** — Constructors of `@RoutePage` widgets automatically become route parameters.
6. **Prefer declarative calls** — Use `context.pushRoute()` or `context.replaceRoute()`.

### Nested Routes & Tabs

Use `children` in `AutoRoute` for tabs. Pass `children` parameter to define initial active sub-route.

See [implementation examples](references/implementation.md) for nested route navigation and router configuration patterns.

## Reference & Examples

For full Router configuration and Auth Guard implementation:
See [references/REFERENCE.md](references/REFERENCE.md).

## Anti-Patterns

- **No string-based navigation**: Use generated typed route classes (e.g., `OrderDetailRoute(id: 123)`).
- **No protected screen without AutoRouteGuard**: Every protected route must declare guard; don't rely on UI-level checks.
- **No navigation calls from BLoC**: Emit state and let Presentation layer navigate.

## References

- [go-router-navigation](../flutter-navigation/SKILL.md) | [layer-based-clean-architecture](../flutter-layer-based-clean-architecture/SKILL.md)

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- Use generated

- Additional task-grounded exact anchors: generated typed

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.