navigation - SKILL.md Agent Skill

name: navigation description: Use when adding a new screen or modifying navigation in the Alkaa project — triggers on tasks like "add a new screen", "navigate to X", "add destination", "wire up navigation", or "create a navigation event". Also triggers when connecting UI actions to routes in NavGraph.

Alkaa Navigation

Overview

Alkaa uses event-driven navigation: UI components send named action events, and the system resolves where to go. Navigation is never triggered directly from UI or ViewModels — it always flows through NavEventController.

Required Files per Navigation Change

File	Package	Purpose
`*Event.kt`	`com.escodro.navigationapi.event`	Defines action events
`*Destination.kt`	`com.escodro.navigationapi.destination`	Defines typed routes
`*NavGraph.kt`	feature module	Registers entries and sends events

Both *Event.kt and *Destination.kt live in features/navigation-api. → See references/CODE_PATTERNS.md for Kotlin examples of all three files.

Steps

Create the Event — Name after the action, not the destination (OnEditClick, not NavigateToEdit) → see references/CODE_PATTERNS.md
Create the Destination — Add @Serializable; choose interface based on screen type → see references/CODE_PATTERNS.md
Add a NavGraph Entry — entry<Destination> block with appropriate transition spec → see references/CODE_PATTERNS.md
Hoist Navigation — Composables receive lambdas; NavGraph calls navEventController.sendEvent() → see references/CODE_PATTERNS.md

Destination Interface Rules

Interface	When to use
`TopLevel`	Bottom-nav root screens only (requires `title`, `icon`, `@CommonParcelize`)
`TopAppBarVisible`	Dialogs, bottom sheets, non-full-screen destinations
Neither	Regular full-screen push destinations

Also register TopLevel and TopAppBarVisible destinations in the corresponding sets in Destination.kt.

Checklist

Event named after an action (verb phrase: On*Click, On*Save)
Destination annotated with @Serializable
TopLevel only for bottom-nav root screens (with @CommonParcelize, title, icon)
TopAppBarVisible only for dialogs/sheets/non-full-screen
TopLevel/TopAppBarVisible destinations registered in Destination.kt sets
NavGraph entry<> block exists for each new destination
Navigation events sent from within NavGraph lambda, not from composables or ViewModels
Back navigation uses Event.OnBack, not custom events

Common Mistakes

Mistake	Fix
`navEventController.sendEvent()` in a ViewModel	Must not leave the NavGraph — pass navigation as lambda callbacks instead
`navEventController.sendEvent()` inside a `@Composable`	Move to NavGraph `entry<>` block via lambda callback
Event named `NavigateToDetail` or `GoToSettings`	Name after the action: `OnDetailClick`, `OnSettingsClick`
Destination without `@Serializable`	Add annotation — Navigation3 requires it
Full-screen destination with `TopAppBarVisible`	Remove — use only for dialogs/sheets
New feature with no `NavGraph` implementation	Create `*NavGraph.kt` and bind in Koin module