matthias/stackdex_neu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
stackdex_neu/.claude/skills/axiom-ios-integration/SKILL.md
Matthias a60a76b797 Add scan flow MVP and local Axiom skill workspace 
This snapshot establishes the camera-to-result recognition flow and related tests while checking in the project skill/docs assets required for the configured local tooling.
2026-04-19 21:11:32 +02:00

435 lines
20 KiB
Markdown
Raw Permalink Blame History

---
name: axiom-ios-integration
description: Use when integrating ANY iOS system feature - Siri, Shortcuts, widgets, IAP, camera, photo library, audio, ShazamKit, haptics, localization, privacy, alarms, calendar, reminders, contacts. Covers App Intents, WidgetKit, StoreKit, AVFoundation, ShazamKit, Core Haptics, Spotlight, EventKit, Contacts.
license: MIT
---
# iOS System Integration Router
**You MUST use this skill for ANY iOS system integration including Siri, Shortcuts, widgets, in-app purchases, camera, photo library, audio, axiom-haptics, and more.**
## When to Use
Use this router for:
- Siri & Shortcuts (App Intents)
- Apple Intelligence integration
- Widgets & Live Activities
- In-app purchases (StoreKit)
- Camera capture (AVCaptureSession)
- Photo library & pickers (PHPicker, PhotosPicker)
- Audio, haptics, & audio recognition (ShazamKit)
- Localization
- Privacy & permissions
- Spotlight search
- App discoverability
- Alarms (AlarmKit)
- Background processing (BGTaskScheduler)
- Location services (Core Location)
- Maps & MapKit (Map, MKMapView, annotations, search, directions)
- Passkeys & authentication (ASAuthorizationController, WebAuthn)
- App integrity & fraud prevention (App Attest, DeviceCheck)
- Calendar events & reminders (EventKit, EventKitUI)
- Contacts & contact pickers (Contacts, ContactsUI, ContactProvider)
## Cross-Domain Routing
When integration issues overlap with other domains:
**Widget + data sync issues** (widget not showing updated data):
- Widget timeline not refreshing → **stay in ios-integration** (extensions-widgets)
- SwiftData/Core Data not shared with extension → **also invoke ios-data** — App Groups and shared containers are data-layer concerns
- Background refresh timing → **also invoke ios-concurrency** if async patterns are involved
**Live Activity + push notification issues**:
- ActivityKit push token setup, Live Activity not updating → **stay in ios-integration** (extensions-widgets)
- Push notification delivery failures, APNs errors → **also invoke ios-networking** (networking-diag)
- Entitlements/certificates misconfigured → **also invoke ios-build** (xcode-debugging)
**Camera + permissions + privacy**:
- Camera code issues → **stay in ios-integration** (camera-capture)
- Privacy manifest or Info.plist issues → **stay in ios-integration** (privacy-ux)
- Build/entitlement errors → **also invoke ios-build**
**MapKit + location issues** (user location not showing on map):
- Map display, annotations, search → **stay in ios-integration** (mapkit)
- Location authorization, monitoring, background location → **also invoke ios-performance** or **ios-integration** (core-location)
- Map performance with many annotations → **also invoke ios-performance** if profiling needed
**Push notification + Live Activity issues** (push not updating Live Activity):
- Push transport, APNs headers, token management → **stay in ios-integration** (push-notifications, push-notifications-diag)
- ActivityKit UI, attributes, Dynamic Island → **also invoke ios-integration** (extensions-widgets)
- Background execution timing → **also invoke ios-concurrency** if async patterns are involved
**Push notification + background processing** (silent push not triggering background work):
- Push payload and delivery → **stay in ios-integration** (push-notifications-diag)
- Background execution, BGTaskScheduler → **also invoke ios-integration** (background-processing)
**Calendar + data sync issues** (events not syncing, stale calendar data):
- EventKit store changes, EKEventStoreChanged → **stay in ios-integration** (eventkit)
- Shared data with widget via App Groups → **also invoke ios-data** for shared container patterns
- Background refresh for calendar sync → **also invoke ios-integration** (background-processing)
**Contacts + privacy issues** (contact access denied, limited access confusion):
- Contact permission model, Contact Access Button → **stay in ios-integration** (contacts)
- Privacy manifest or Info.plist for contacts → **stay in ios-integration** (privacy-ux)
- Contact Provider extension architecture → **also invoke ios-build** if extension target issues
**ShazamKit + microphone permissions** (no match results, permission denied):
- Microphone NSMicrophoneUsageDescription / Info.plist → **stay in ios-integration** (privacy-ux)
- ShazamKit App Service not enabled → **stay in ios-integration** (shazamkit)
**ShazamKit + AVFoundation** (custom SHSession with AVAudioEngine buffers):
- Audio engine setup, buffer formats, session configuration → **stay in ios-integration** (shazamkit)
- AVAudioEngine pipeline, audio session category, format conversion → **also invoke avfoundation-ref**
**ShazamKit + MusicKit** (play matched song via Apple Music):
- Match result with appleMusicID/appleMusicURL → **stay in ios-integration** (shazamkit)
- MusicKit playback, ApplicationMusicPlayer → **also invoke ios-integration** (now-playing-musickit)
## Routing Logic
### Apple Intelligence & Siri
**App Intents** → `/skill axiom-app-intents-ref`
**App Shortcuts** → `/skill axiom-app-shortcuts-ref`
**App discoverability** → `/skill axiom-app-discoverability`
**Core Spotlight** → `/skill axiom-core-spotlight-ref`
### Widgets & Extensions
**Widgets/Live Activities** → `/skill axiom-extensions-widgets`
**Widget reference** → `/skill axiom-extensions-widgets-ref`
### In-App Purchases
**IAP implementation** → `/skill axiom-in-app-purchases`
**StoreKit 2 reference** → `/skill axiom-storekit-ref`
**IAP audit** → Launch `iap-auditor` agent (missing transaction.finish(), weak receipt validation, missing restore, subscription tracking)
**IAP full implementation** → Launch `iap-implementation` agent (StoreKit config, StoreManager, transaction handling, restore purchases)
### Camera & Photos
**Camera capture implementation** → `/skill axiom-camera-capture`
**Camera API reference** → `/skill axiom-camera-capture-ref`
**Camera debugging** → `/skill axiom-camera-capture-diag`
**Camera audit** → Launch `camera-auditor` agent or `/axiom:audit camera` (deprecated APIs, missing interruption handlers, threading violations, permission anti-patterns)
**Photo pickers & library** → `/skill axiom-photo-library`
**Photo library API reference** → `/skill axiom-photo-library-ref`
### Audio, Haptics & Audio Recognition
**Audio (AVFoundation)** → `/skill axiom-avfoundation-ref`
**Haptics** → `/skill axiom-haptics`
**Now Playing** → `/skill axiom-now-playing`
**CarPlay Now Playing** → `/skill axiom-now-playing-carplay`
**MusicKit integration** → `/skill axiom-now-playing-musickit`
**ShazamKit implementation** → `/skill axiom-shazamkit`
- Song recognition (Shazam catalog), custom audio matching
- SHManagedSession (modern) vs SHSession (legacy) decision
- Custom catalogs, signature generation, Shazam CLI
- Library management (SHLibrary)
**ShazamKit API reference** → `/skill axiom-shazamkit-ref`
- SHManagedSession, SHSession, SHCustomCatalog, SHSignatureGenerator
- SHMediaItem, SHMatchedMediaItem, SHLibrary, SHError
- Complete property keys and error codes
### Localization & Privacy
**Localization** → `/skill axiom-localization`
**Privacy UX** → `/skill axiom-privacy-ux`
### Authentication & Credentials
**Passkeys / WebAuthn sign-in** → `/skill axiom-passkeys`
### App Integrity & Fraud Prevention
**App Attest / DeviceCheck** → `/skill axiom-app-attest`
### Alarms
**AlarmKit (iOS 26+)** → `/skill axiom-alarmkit-ref`
- Alarm scheduling and authorization
- Live Activity integration
- SwiftUI alarm management views
### Calendar & Reminders (EventKit)
**EventKit implementation** → `/skill axiom-eventkit`
- Permission model (no access, write-only, full access)
- Event creation patterns (EventKitUI vs direct EventKit)
- Reminder patterns (DateComponents, EKSource selection)
- Store lifecycle (singleton, change notifications)
- Migration from pre-iOS 17 APIs
**EventKit API reference** → `/skill axiom-eventkit-ref`
- EKEventStore, EKEvent, EKReminder, EKAlarm, EKRecurrenceRule
- EventKitUI view controllers
- Siri Event Suggestions (INReservation donation)
- Virtual conference extensions
- Location-based reminders
### Contacts
**Contacts implementation** → `/skill axiom-contacts`
- Permission model (limited vs full access)
- Contact Access Button (iOS 18+)
- Picker vs store access decisions
- CNContactStore patterns
- Contact Provider extensions
**Contacts API reference** → `/skill axiom-contacts-ref`
- CNContactStore, CNMutableContact, CNSaveRequest
- CNContactFormatter, CNContactVCardSerialization
- CNContactPickerViewController, ContactAccessButton
- ContactProvider framework
- Change history (CNChangeHistoryFetchRequest)
### Background Processing
**BGTaskScheduler implementation** → `/skill axiom-background-processing`
**Background task debugging** → `/skill axiom-background-processing-diag`
**Background task API reference** → `/skill axiom-background-processing-ref`
### Push Notifications
**Push notification implementation** → `/skill axiom-push-notifications`
**Push notification API reference** → `/skill axiom-push-notifications-ref`
**Push notification debugging** → `/skill axiom-push-notifications-diag`
### Location Services
**Implementation patterns** → `/skill axiom-core-location`
**API reference** → `/skill axiom-core-location-ref`
**Debugging location issues** → `/skill axiom-core-location-diag`
### Maps & MapKit
**MapKit implementation patterns** → `/skill axiom-mapkit`
- SwiftUI Map vs MKMapView decision
- Annotation strategies by count
- Search and directions
- 8 anti-patterns
**MapKit API reference** → `/skill axiom-mapkit-ref`
- SwiftUI Map API
- MKMapView delegates
- MKLocalSearch, MKDirections, Look Around
- Platform availability matrix
**MapKit troubleshooting** → `/skill axiom-mapkit-diag`
- Annotations not appearing
- Region jumping / infinite loops
- Clustering issues
- Search failures
## Decision Tree
1. App Intents / Siri / Apple Intelligence? → app-intents-ref
2. App Shortcuts? → app-shortcuts-ref
3. App discoverability / Spotlight? → app-discoverability, core-spotlight-ref
4. Widgets / Live Activities? → extensions-widgets, extensions-widgets-ref
5. In-app purchases / StoreKit? → in-app-purchases, storekit-ref
6. Want IAP audit (missing finish, receipt validation)? → iap-auditor (Agent)
7. Want full IAP implementation? → iap-implementation (Agent)
8. Camera capture? → camera-capture (patterns), camera-capture-diag (debugging), camera-capture-ref (API)
9. Want camera code audit? → camera-auditor (Agent)
10. Photo pickers / library? → photo-library (patterns), photo-library-ref (API)
11. Audio / AVFoundation? → avfoundation-ref
12. Now Playing? → now-playing, now-playing-carplay, now-playing-musickit
13. Haptics? → haptics
14. Audio recognition / ShazamKit / song identification? → shazamkit (patterns), shazamkit-ref (API)
15. Custom audio catalogs / second-screen sync / audio matching? → shazamkit (patterns), shazamkit-ref (API)
16. Localization? → localization
17. Privacy / permissions? → privacy-ux
18. Background processing? → background-processing (patterns), background-processing-diag (debugging), background-processing-ref (API)
19. Push notification implementation, APNs, or remote notification handling? → push-notifications (patterns), push-notifications-ref (API), push-notifications-diag (debugging)
20. Need APNs payload format, headers, or JWT auth details? → push-notifications-ref
21. Push notifications not arriving, token issues, or delivery failures? → push-notifications-diag
22. Location services? → core-location (patterns), core-location-diag (debugging), core-location-ref (API)
23. Maps / MapKit / annotations / directions? → mapkit (patterns), mapkit-ref (API), mapkit-diag (debugging)
24. Alarms / AlarmKit? → alarmkit-ref
25. Passkeys / WebAuthn / replacing passwords / ASAuthorizationController? → passkeys
26. App Attest / DeviceCheck / fraud prevention / app integrity? → app-attest
27. Calendar events / EventKit / EventKitUI / add to calendar? → eventkit (patterns), eventkit-ref (API)
28. Reminders / EKReminder / reminder lists? → eventkit (patterns), eventkit-ref (API)
29. Siri Event Suggestions / INReservation? → eventkit-ref (API, Part 9)
30. Virtual conference extension / EKVirtualConferenceProvider? → eventkit-ref (API, Part 8)
31. Contacts / contact picker / CNContactStore? → contacts (patterns), contacts-ref (API)
32. Contact Access Button / limited access / iOS 18 contacts? → contacts (patterns), contacts-ref (API)
33. Contact Provider extension / expose contacts to system? → contacts-ref (API, Part 10)
## Anti-Rationalization
| Thought | Reality |
|---------|---------|
| "App Intents are just a protocol conformance" | App Intents have parameter validation, entity queries, and background execution. app-intents-ref covers all. |
| "Widgets are simple, I've done them before" | Widgets have timeline, interactivity, and Live Activity patterns that evolve yearly. extensions-widgets is current. |
| "I'll add haptics with a simple API call" | Haptic design has patterns for each interaction type. haptics skill matches HIG guidelines. |
| "Localization is just String Catalogs" | Xcode 26 has type-safe localization, generated symbols, and #bundle macro. localization skill is current. |
| "Camera capture is just AVCaptureSession setup" | Camera has interruption handlers, rotation, and threading requirements. camera-capture covers all. |
| "I'll just use MKMapView, I know it already" | SwiftUI Map is 10x less code for standard map features. mapkit has the decision tree. |
| "MapKit search doesn't work, I'll use Google Maps SDK" | MapKit search needs region bias and resultTypes configuration. mapkit-diag fixes this in 5 minutes. |
| "Alarm scheduling is just UNNotificationRequest" | AlarmKit (iOS 26+) has dedicated alarm UI, authorization, and Live Activity integration. alarmkit-ref covers the framework. |
| "Push notifications are just a payload and a token" | Token lifecycle, Focus interruption levels, service extension gotchas, and sandbox/production mismatch cause 80% of push bugs. push-notifications covers all. |
| "Our users aren't ready for passkeys" | Apple, Google, and Microsoft ship passkeys across all platforms. Users don't need to understand crypto — they just tap. passkeys covers the migration path. |
| "App Attest is overkill for our app" | Any app with server-side value (premium content, virtual currency, user accounts) is a fraud target. app-attest has a gradual rollout strategy. |
| "Just request full Calendar access" | Most apps only need to add events — EventKitUI does that with zero permissions. eventkit has the access tier decision tree. |
| "ShazamKit is just SHSession + a delegate" | iOS 17+ has SHManagedSession which eliminates all AVAudioEngine boilerplate. shazamkit has the era decision tree. |
| "I'll use CNContactStore directly for contact picking" | CNContactPickerViewController needs no authorization and shows all contacts. contacts has the access level decision tree. |
| "Contacts access is simple, just request and fetch" | iOS 18 limited access means your app may only see a subset. ContactAccessButton handles this gracefully. contacts covers the full model. |
## Example Invocations
User: "How do I add Siri support for my app?"
→ Invoke: `/skill axiom-app-intents-ref`
User: "My widget isn't updating"
→ Invoke: `/skill axiom-extensions-widgets`
User: "My widget isn't showing updated SwiftData content"
→ Invoke: `/skill axiom-extensions-widgets` + also invoke `ios-data` router for App Group/shared container setup
User: "My Live Activity isn't updating and I'm getting push notification errors"
→ Invoke: `/skill axiom-extensions-widgets` for ActivityKit + also invoke `ios-networking` router for push delivery
User: "Implement in-app purchases with StoreKit 2"
→ Invoke: `/skill axiom-in-app-purchases`
User: "How do I localize my app strings?"
→ Invoke: `/skill axiom-localization`
User: "Implement haptic feedback for button taps"
→ Invoke: `/skill axiom-haptics`
User: "How do I set up a camera preview?"
→ Invoke: `/skill axiom-camera-capture`
User: "Camera freezes when I get a phone call"
→ Invoke: `/skill axiom-camera-capture-diag`
User: "What is RotationCoordinator?"
→ Invoke: `/skill axiom-camera-capture-ref`
User: "How do I let users pick photos in SwiftUI?"
→ Invoke: `/skill axiom-photo-library`
User: "User can't see their photos after granting access"
→ Invoke: `/skill axiom-photo-library`
User: "How do I save a photo to the camera roll?"
→ Invoke: `/skill axiom-photo-library`
User: "My background task never runs"
→ Invoke: `/skill axiom-background-processing-diag`
User: "How do I implement BGTaskScheduler?"
→ Invoke: `/skill axiom-background-processing`
User: "What's the difference between BGAppRefreshTask and BGProcessingTask?"
→ Invoke: `/skill axiom-background-processing-ref`
User: "How do I implement geofencing?"
→ Invoke: `/skill axiom-core-location`
User: "Location updates not working in background"
→ Invoke: `/skill axiom-core-location-diag`
User: "What is CLServiceSession?"
→ Invoke: `/skill axiom-core-location-ref`
User: "Review my in-app purchase implementation"
→ Invoke: `iap-auditor` agent
User: "Implement in-app purchases for my app"
→ Invoke: `iap-implementation` agent
User: "Check my camera code for issues"
→ Invoke: `camera-auditor` agent
User: "How do I add a map to my SwiftUI app?"
→ Invoke: `/skill axiom-mapkit`
User: "My annotations aren't showing on the map"
→ Invoke: `/skill axiom-mapkit-diag`
User: "How do I implement search with autocomplete on a map?"
→ Invoke: `/skill axiom-mapkit-ref`
User: "My map region keeps jumping when I scroll"
→ Invoke: `/skill axiom-mapkit-diag`
User: "How do I add directions between two points?"
→ Invoke: `/skill axiom-mapkit-ref`
User: "How do I schedule alarms in iOS 26?"
→ Invoke: `/skill axiom-alarmkit-ref`
User: "How do I integrate AlarmKit with Live Activities?"
→ Invoke: `/skill axiom-alarmkit-ref`
User: "How do I implement push notifications?"
→ Invoke: `/skill axiom-push-notifications`
User: "What APNs headers do I need?"
→ Invoke: `/skill axiom-push-notifications-ref`
User: "Push notifications work in dev but not production"
→ Invoke: `/skill axiom-push-notifications-diag`
User: "My Live Activity isn't updating via push"
→ Invoke: `/skill axiom-push-notifications-diag` + `/skill axiom-extensions-widgets`
User: "Should I use FCM or direct APNs?"
→ Invoke: `/skill axiom-push-notifications`
User: "How do I use pushTokenUpdates for Live Activities?"
→ Invoke: `/skill axiom-extensions-widgets` (ActivityKit API owns push token observation)
User: "How do I test push notifications without a real server?"
→ Invoke: `/skill axiom-push-notifications-ref` (command-line testing section)
User: "How do I implement passkey sign-in?"
→ Invoke: `/skill axiom-passkeys`
User: "How do I replace passwords with passkeys?"
→ Invoke: `/skill axiom-passkeys`
User: "How do I verify my app hasn't been tampered with?"
→ Invoke: `/skill axiom-app-attest`
User: "How do I prevent promotional fraud?"
→ Invoke: `/skill axiom-app-attest`
User: "How do I add an event to the user's calendar?"
→ Invoke: `/skill axiom-eventkit`
User: "What's the difference between write-only and full Calendar access?"
→ Invoke: `/skill axiom-eventkit`
User: "How do I create reminders programmatically?"
→ Invoke: `/skill axiom-eventkit`
User: "What is EKEventEditViewController?"
→ Invoke: `/skill axiom-eventkit-ref`
User: "How do I implement Siri Event Suggestions?"
→ Invoke: `/skill axiom-eventkit-ref`
User: "How do I let users pick a contact?"
→ Invoke: `/skill axiom-contacts`
User: "What is the Contact Access Button?"
→ Invoke: `/skill axiom-contacts`
User: "How do I search and fetch contacts?"
→ Invoke: `/skill axiom-contacts-ref`
User: "How do I build a Contact Provider extension?"
→ Invoke: `/skill axiom-contacts-ref`
User: "How do I detect contact changes for sync?"
→ Invoke: `/skill axiom-contacts-ref`
Reference in New Issue View Git Blame Copy Permalink