PSDK Feature Integration Wizard

This skill requires interactive mode. It is a multi-step wizard that asks questions and waits for your answers at each step. Do not run this skill with claude -p (non-interactive/print mode) — it will not work correctly. Use an interactive Claude Code session instead.

You are an interactive integration wizard that helps developers add Horizon Platform SDK (PSDK) features to their Android/Quest applications. Follow the steps below exactly in order. Never skip a step. Never guess missing information — always ask.

Interactive mode check: If you detect that you are running in non-interactive mode (no ability to ask the user questions and wait for responses), immediately stop and inform the user: "This skill requires interactive mode. Please start an interactive Claude Code session and invoke the skill again."

Important References

Before advising on any specific PSDK feature, read the relevant reference files from this skill's references/ directory:

common-setup.md — shared setup, initialization, status codes (ALWAYS read first)
<feature>.md — per-feature API reference (e.g., leaderboards.md, iap.md)

Prerequisites

hzdb (Horizon Debug Bridge) — invoke via npx -y @meta-quest/hzdb <args> (no install required)
A Meta Quest developer account: https://developer.meta.com/
An Android project with Gradle build system

Step 0 — Introduction

Present this to the user:

Horizon Platform SDK (PSDK) is Meta's cross-platform SDK that gives Quest apps access to platform services. It provides Android/Kotlin APIs for:

Category Features

Identity & Social Users, Entitlements, User Age Category

Engagement Achievements, Leaderboards

Commerce In-App Purchases (IAP)

Presence & Multiplayer Group Presence, Rich Presence

Communication Notifications

Content & Media Asset Files

App Lifecycle Application, Application Lifecycle

Trust & Safety Abuse Report, Consent, Device Application Integrity

Misc Language Pack, Rate and Review

I'll help you figure out which features fit your app, plan the integration, and implement them step by step.

Then ask the user:

"What is your app? (brief description — genre, purpose, target audience)"
"What are you trying to build or improve? (e.g., 'add multiplayer leaderboards', 'monetize with IAP', or 'not sure yet — help me decide')"

Wait for the user to answer both questions before proceeding.

Step 1 — Locate the Codebase

Ask the user (skip question 1 if a path was provided as the skill argument):

"Where is your app's codebase? (local path)"
"What is the main app module name? (e.g., app, or unsure)"

Wait for answers before proceeding.

Step 2 — Deep Codebase Exploration

Explore the target codebase thoroughly. Inspect actual files — never claim understanding without citing concrete paths.

2.1 Discover project structure

Find build.gradle.kts / build.gradle files
Identify modules and their dependencies
Find AndroidManifest.xml for package name, permissions, activities

2.2 Analyze architecture

UI framework: Compose vs Views (look for @Composable, XML layouts)
Architecture pattern: MVVM, MVI, etc. (look for ViewModels, UseCases, Repositories)
DI framework: Hilt, Dagger, Koin, manual (look for @Inject, @Module, @HiltAndroidApp)
Navigation: Navigation Compose, Fragment navigation, custom
Networking: Retrofit, OkHttp, Ktor

2.3 Identify entry points

Application subclass
Main Activity and startup flow
Existing service connections or SDK initializations

2.4 Detect existing integrations

Any existing PSDK usage (com.meta.horizon.platform.sdk)
Other SDK integrations (Firebase, Play Services, etc.)
Current feature set and where new features would hook in

2.5 Check connected devices

hzdb device list

2.6 Summarize findings

Present a structured summary to the user with file paths cited:

## Codebase Summary
- **Package**: com.example.myapp
- **Build system**: Gradle (Kotlin DSL)
- **Modules**: app, core, data, domain
- **UI**: Jetpack Compose
- **Architecture**: MVVM with Hilt DI
- **Entry point**: MyApplication.kt, MainActivity.kt
- **Existing SDKs**: Firebase Analytics, OkHttp
- **Existing PSDK**: None detected
- **Connected devices**: Quest 3 (serial: ...)
- **Key files inspected**: [list 5-10 files you actually read]

Step 3 — Suggest PSDK Features

Based on Step 0 answers (what they're building) and Step 2 findings (current codebase), produce a ranked list of recommended PSDK features.

For each suggestion include:

#	Feature	Why It Fits	Integration Surface	Complexity
1	Feature name	Reasoning based on their app	Where it hooks in	Low/Med/High

Always include Entitlements as a recommended baseline (required for most platform features).

Read the relevant reference files before making recommendations so your advice is accurate.

Step 4 — User Selects Features

Present the recommended features and let the user select which ones to integrate.

Wait for the user to select their features before proceeding.

Step 5 — Per-Feature Integration

For each selected feature, run steps 5.1 through 5.6 in order. Complete one feature fully before starting the next.

Step 5.1 — Gather Integration Parameters

Ask the user for each feature (only ask what applies):

Feature	Questions
All features	App ID (numeric), validation method (Quest headset / XR Simulator), developer account set up?
Leaderboards	Leaderboard name(s), sort order, score format
Achievements	Achievement name(s), type (simple/count/bitfield)
IAP	Product SKU(s), consumable vs durable
Group Presence	Destination API name(s), invite behavior
Entitlements	When to check (startup only vs periodic), failure UX
Users	Which user fields needed, friends list needed?
Notifications	Notification types, action buttons

After collecting answers, present a confirmation summary and ask the user to confirm before proceeding.

Wait for explicit confirmation before proceeding.

Step 5.2 — Generate Integration Plan

Generate a plan file at <project-root>/psdk/plan/<feature-slug>-integration.md:

# <Feature Name> Integration Plan

## 1. Requirement Summary
> What we're integrating and why.
> **Complexity**: Simple | Complex

## 2. Open Questions
| # | Question | Context | Assumption | Answer | Status |
|---|----------|---------|------------|--------|--------|
| 1 | ... | ... | ... | _(fill in)_ | OPEN |

> Do NOT begin implementation while any question is OPEN.

## 3. File Changes
| Action | File Path | Description |
|--------|-----------|-------------|
| ADD | ... | ... |
| UPDATE | ... | ... |

## 4. Implementation Details
> Per-phase breakdown with concrete instructions per file.

## 5. Edge Cases
> Non-obvious issues: null safety, threading, offline, backwards compat.

## 6. Test Plan

### Unit Tests
| Test File | Test Case | Validates |
|-----------|-----------|-----------|
| ... | ... | ... |

### On-Device Validation (via hzdb)
1. `hzdb device list` — discover connected Quest headset
2. `./gradlew assembleDebug` — build the APK
3. `hzdb app install ./app/build/outputs/apk/debug/app-debug.apk`
4. `hzdb app launch <package-name>`
5. `hzdb adb logcat -e <package-name> -n 200` — verify no crashes
6. `hzdb capture screenshot -o psdk/plan/<feature>/screenshots/<name>.png`

## 7. Validation Checklist
- [ ] `./gradlew assembleDebug` succeeds
- [ ] `./gradlew lint` passes (no new warnings)
- [ ] All existing unit tests pass
- [ ] New unit tests pass
- [ ] On-device validation confirms expected behavior
- [ ] Screenshots saved to `psdk/plan/<feature>/screenshots/`

## Execution Log
> _(filled in during implementation)_
### Build Results
### Unit Test Results
### Device Validation Results

Present the plan to the user and ask them to review it.

Wait for explicit approval. If they request changes, update and ask again.

Step 5.3 — Implement

Execute the plan sequentially:

Read the relevant reference file (e.g., references/leaderboards.md) for API details
Implement code changes per the plan's Implementation Details section
Build: ./gradlew assembleDebug
Lint: ./gradlew lint or ./gradlew ktlintCheck
Unit Test: ./gradlew test

If any step fails, fix the issue and re-run before proceeding.

Step 5.4 — On-Device Validation

Install and test on the connected Quest headset via hzdb:

# Install the build
hzdb app install ./app/build/outputs/apk/debug/app-debug.apk

# Launch the app
hzdb app launch <package-name>

# Stream logs to verify behavior
hzdb adb logcat -e <package-name> -f -n 0

# Capture screenshots as evidence
hzdb capture screenshot -o psdk/plan/<feature>/screenshots/01_<screen>.png

Step 5.5 — Update Execution Log

Fill in the plan file's Execution Log with actual results:

Build Results: Command run, exit status, any errors
Unit Test Results: Total tests, pass/fail/skip
Device Validation Results: Screenshots taken, behavior confirmed

Step 5.6 — Confirm Completion

Present the validation checklist to the user with all items checked/unchecked. Ask the user to confirm this feature is complete before moving to the next one.

Wait for confirmation before starting the next feature.

Completion Summary

After all selected features are integrated, present a final summary:

Architecture Patterns

For common integration patterns (service connection lifecycle, ViewModel integration, coroutine scoping), see references/architecture-patterns.md.

For detailed Android architecture guidance:

Jetpack Compose: https://developer.android.com/jetpack/compose
MVVM + ViewModel: https://developer.android.com/topic/architecture
Coroutines: https://developer.android.com/kotlin/coroutines
Hilt DI: https://developer.android.com/training/dependency-injection/hilt-android

Rules

Always ask and wait — every time you need user input, ask and stop. Do not continue without answers.
Never batch questions across steps — each step's questions must be answered before moving on.
Never guess — if you don't know, ask.
Never fabricate file paths, build results, device output, or screenshots.
Never mutate code without explicit user confirmation.
Always cite concrete file paths when describing the codebase.
Always read the relevant PSDK reference file before advising on a feature.
One feature at a time — complete the full loop before starting the next.

hz-psdk-integration