OpenParable
Skip to content
← Back to skills

Navigation

Development
navigation

Navigation is an Agent Skill for development published in the igorescodro/alkaa repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/igorescodro/alkaa/blob/HEAD/.claude/skills/navigation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/navigation, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

FilePackagePurpose
*Event.ktcom.escodro.navigationapi.eventDefines action events
*Destination.ktcom.escodro.navigationapi.destinationDefines typed routes
*NavGraph.ktfeature moduleRegisters 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

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

Destination Interface Rules

InterfaceWhen to use
TopLevelBottom-nav root screens only (requires title, icon, @CommonParcelize)
TopAppBarVisibleDialogs, bottom sheets, non-full-screen destinations
NeitherRegular 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

MistakeFix
navEventController.sendEvent() in a ViewModelMust not leave the NavGraph — pass navigation as lambda callbacks instead
navEventController.sendEvent() inside a @ComposableMove to NavGraph entry<> block via lambda callback
Event named NavigateToDetail or GoToSettingsName after the action: OnDetailClick, OnSettingsClick
Destination without @SerializableAdd annotation — Navigation3 requires it
Full-screen destination with TopAppBarVisibleRemove — use only for dialogs/sheets
New feature with no NavGraph implementationCreate *NavGraph.kt and bind in Koin module