Android Navigation 3

Purpose

Implement or migrate modern Android navigation without breaking screens, route arguments, deep links or back stack behavior.

When to use

• Adding Navigation 3 to an Android app.
• Migrating from Navigation Compose or custom navigation.
• Fixing typed routes, deep links, nested graphs or back stack issues.

Inputs to inspect

• build.gradle.kts and libs.versions.toml
• MainActivity.kt and app entry points
• NavHost, routes and feature navigation files
• AndroidManifest.xml deep links
• screens/* and ViewModel event flow

Required workflow

1. Map current destinations, arguments and deep links.
2. Choose typed routes or preserve the existing route convention.
3. Move navigation decisions to route-level event handling.
4. Add or update navigation tests for critical flows.
5. Validate back behavior, process recreation and deep links.

Rules

• Do not pass large objects as route arguments.
• Do not put business logic inside route definitions.
• Do not create duplicate NavHost owners.
• Preserve existing deep links unless the user approves a migration.
• Prefer typed route patterns when the project already uses them.

Related existing skills

Local skills to invoke

• jetpack-compose
• android-core
• testing
• edge-to-edge-adaptive-ui

External companion skills to use when installed

Do not assume these companion skills are installed. Prefer the local skills above first, then consult [Companion Skills](../../docs/COMPANION_SKILLS.md) for install and verification commands.

• aldefy/compose-skill — use for deeper Jetpack Compose, Material 3, design-to-code, theming or Compose architecture guidance.
• android/skills — use for official Android workflow alignment around edge-to-edge, adaptive UI, Navigation 3, R8, AGP or testing setup.

Files commonly touched

• settings.gradle.kts
• build.gradle.kts
• gradle/libs.versions.toml
• MainActivity.kt
• feature/*/navigation/*
• AndroidManifest.xml
• androidTest/*Navigation*

Commands to validate

./gradlew assembleDebug
./gradlew test
./gradlew connectedDebugAndroidTest

Common mistakes to avoid

• Navigating directly from deep reusable Composables.
• Changing route strings without migration notes.
• Forgetting saved state and process death.
• Testing only happy-path forward navigation.

Checklist

• Destinations and arguments documented.
• Deep links preserved or explicitly migrated.
• Back stack behavior tested.
• Navigation events flow from UI state/events.
• Validation commands provided.

Example prompts

• Use $super-android-kotlin-firebase to migrate this app to Navigation 3.
• Use $super-android-kotlin-firebase to add typed routes and deep links safely.

Expected response style

Respond with: brief diagnosis, change plan, affected files, code or diff summary, validation commands, tests added or recommended, risks, and next step. For review tasks, lead with findings ordered by severity.

References

• ../../docs/audits/FUENTES_LOCALES.md
• references/navigation-3-patterns.md
• references/migration-from-navigation-compose.md
• references/deep-links-and-back-stack.md
• templates/typed-route-template.md
• templates/navigation-host-template.md
• templates/navigation-test-template.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GDvega
• Source: GDvega/super-android-kotlin-firebase-skill
• License: MIT

Install and usage instructions live in the source repository linked above.