App Intents

Write and review Swift code that exposes app functionality through the App Intents framework, ensuring correct protocol conformance, safe data flow, and idiomatic discoverability wiring.

Review process:

1. Check intent fundamentals (protocol, perform(), return types, dialog) using references/fundamentals.md.
2. Validate parameters and parameter options using references/parameters.md.
3. Validate entity types, display representations, and queries using references/entities.md.
4. Check the AppShortcutsProvider registration and discoverability UI using references/shortcuts-and-siri.md.
5. Validate OpenIntent navigation and snippet view return types using references/open-and-snippet-intents.md.
6. Check dependency injection and the data-controller pattern using references/dependencies.md.
7. Validate Spotlight indexing via IndexedEntity, IndexedEntityQuery, and attribute sets using references/spotlight.md.
8. Check @AssistantEntity / @AssistantIntent schema adoption using references/assistant-schemas.md.
9. Validate the Siri / Apple Intelligence integration (finding content, custom responses, donations, confirmation, ownership) using references/siri-intelligence.md.
10. Check on-screen awareness and content transfer (view annotations, IntentValueRepresentation, system-integration annotations) using references/onscreen-awareness.md.
11. For intents that run past 30 seconds, handle cancellation, or target a specific process, use references/long-running-and-execution.md.
12. If writing or reviewing tests for intents, use references/testing-intents.md (covers the new AppIntentsTesting framework).
13. Catch common mistakes using references/anti-patterns.md.

If doing partial work, load only the relevant reference files.

Task-based routing

Match the user's goal to the read order. Load only what you need.

"Create my first App Intent"

1. references/fundamentals.md - protocol, perform(), return types
2. references/shortcuts-and-siri.md - register it so it shows up

"Add a parameter the user picks in Shortcuts"

1. references/parameters.md - @Parameter, prompts, disambiguation
2. references/entities.md - if the parameter is a domain entity

"Make my app's data searchable from Siri / Spotlight"

1. references/entities.md - AppEntity, IndexedEntity, @Property
2. references/spotlight.md - indexing strategies, attribute sets
3. references/shortcuts-and-siri.md - flexible matching, phrase rules

"Show a summary / interactive view when Siri runs my intent"

1. references/open-and-snippet-intents.md - inline vs indirect snippets, SnippetIntent, Button(intent:)
2. references/fundamentals.md - return types and snippet design rules

"Open a specific thing in my app from Siri / Shortcuts"

1. references/open-and-snippet-intents.md - OpenIntent, URLRepresentableIntent, TargetContentProvidingIntent
2. references/dependencies.md - navigator / scene routing

"Bring my app's content and actions to Siri / Apple Intelligence"

1. references/siri-intelligence.md - the integration model, finding content (semantic index / structured search / in-app search), custom responses, donations, confirmation/ownership
2. references/assistant-schemas.md - schema macros, domains, multi-schema requirements, Xcode snippets
3. references/onscreen-awareness.md - view annotations, content transfer, system-integration annotations

"Integrate with Apple Intelligence"

1. references/assistant-schemas.md - schema macros, domains, Use Model action, onscreen content
2. references/entities.md - @Property, Transferable (required for several schemas)

"Let Siri understand what's on screen"

1. references/onscreen-awareness.md - the 4 annotation APIs, content transfer, displayRepresentations fast path, annotations on notifications/Now Playing/AlarmKit
2. references/siri-intelligence.md - how onscreen context fits the larger Siri story

"Make my intent run longer than 30 seconds or target a process"

1. references/long-running-and-execution.md - LongRunningIntent, CancellableIntent, allowedExecutionTargets, background GPU
2. references/fundamentals.md - ProgressReportingIntent, supportedModes

"Handle large numbers of entities efficiently / sync across devices"

1. references/parameters.md - EntityCollection (identifiers-only parameters)
2. references/entities.md - SyncableEntity for cross-device identity, RelevantEntities for proactive suggestions

"Support Visual Intelligence / image search"

1. references/assistant-schemas.md - IntentValueQuery, SemanticContentDescriptor, @UnionValue
2. references/entities.md - Transferable + OpenIntent pairing

"Build an interactive widget or Control Center control"

1. references/open-and-snippet-intents.md - Button(intent:), WidgetConfigurationIntent, ControlConfigurationIntent, ControlWidgetButton
2. references/dependencies.md - App Group shared storage, process boundaries

"Structure my app around App Intents"

1. references/fundamentals.md - intents as canonical action layer
2. references/dependencies.md - @Dependency, cross-module AppIntentsPackage
3. references/entities.md - entity-as-bridge pattern

"Test my App Intents"

1. references/testing-intents.md - the AppIntentsTesting framework (out-of-process integration), direct struct unit tests, mocking @Dependency, test-only intents, what you can't test

"I'm hitting build errors or runtime bugs"

1. references/anti-patterns.md - 35+ catches with before/after fixes

Decision trees

Quick orientation when you know the task but not the right API.

Which intent protocol should I conform to?

Generic action?
  → AppIntent

Opens the app to a specific entity?
  → OpenIntent (+ TargetContentProvidingIntent on iOS)

Renders an interactive view only, no business logic?
  → SnippetIntent

Needs to bring the app forward conditionally?
  → AppIntent with supportedModes (iOS 26+)
  → or ForegroundContinuableIntent (iOS 17-18)

Runs longer than 30 seconds (upload, sync, inference)?
  → LongRunningIntent + performBackgroundTask (iOS 27+)

Needs to clean up gracefully when cancelled (with the reason)?
  → CancellableIntent + withIntentCancellationHandler (iOS 26.4+)

Deletes entities with standard confirmation?
  → DeleteIntent

Routes a search query into the app?
  → ShowInAppSearchResultsIntent

Backs widget configuration?
  → WidgetConfigurationIntent (empty conformance, no perform)

Backs a Control Center control?
  → ControlConfigurationIntent

Has a universal-link URL representation?
  → URLRepresentableIntent + OpenIntent (no perform needed)

Matches an Apple Intelligence domain?
  → AppIntent + @AppIntent(schema: .domain.action)

Which entity type should I use?

Fixed set known at compile time?
  → AppEnum

Dynamic data with a persistent id?
  → AppEntity

Entity must appear in Spotlight?
  → AppEntity + IndexedEntity

Entity IS a file (scan, voice memo, exported image)?
  → FileEntity

Computed / aggregated data with no stable id?
  → TransientAppEntity

Needs Apple Intelligence schema awareness?
  → AppEntity + @AppEntity(schema: .domain.type)

Supports cross-app sharing?
  → AppEntity + Transferable

Which query should my entity use?

Small fixed set, enumerable?
  → EnumerableEntityQuery (also gets a basic Find intent)

Large dataset, searchable by name?
  → EntityQuery + EntityStringQuery

Many queryable properties, user should build predicates?
  → EntityPropertyQuery (auto-generates Find intent with comparators + sort)

Simple id-only lookup, no search?
  → UniqueIDEntityQuery

Indexed in Spotlight and want reindexing support?
  → IndexedEntityQuery (iOS 27+)

Structured Siri search you can't index ahead of time?
  → IntentValueQuery (structured input, returns 1+ entity types via @UnionValue)

Visual intelligence / image search?