App Intent-First Driven Development

Design features as App Intents first, then reuse those intents across Shortcuts, widgets, and SwiftUI views so automation and UI stay in lockstep.

Core Ideas

Entities first: model the data users act on (events, categories, records) as AppEntity boundary types so intents, widgets, and the app use the same identifiers and display language.
Intent-first feature: build the App Intent + entity/query path before UI; SwiftUI screens call the same action path instead of duplicating service code.
Single action, single intent: keep intents focused; avoid mega-intents that are hard to compose in Shortcuts.
Flat entity graph: keep entities as serializable snapshots: ids, primitive fields, display strings, and icons. Avoid nesting one AppEntity inside another.
Context-scoped choices: when an enum or selected run/profile determines valid values, build those choices from that context; never let Shortcuts offer every historical record by accident.
Predictable UI: supply DisplayRepresentation, typeDisplayRepresentation, dialogs, and icons so Siri/Shortcuts can render useful cards without guessing.
Fast queries: EntityQuery must be quick and cancellable; keep expensive SwiftData or network work out of global suggestions.
Reuse business logic: intents call the same services your views use; do not fork logic inside the intent.
Metadata is behavior: App Intents metadata and Shortcuts caches are part of the feature. Validate them after changing parameter or entity shape.