hz-psdk-integration

name	hz-psdk-integration
license	Apache-2.0
description	For 3P / EXTERNAL developers: guides interactive Horizon Platform SDK (PSDK) integration for Meta Quest and Horizon OS Android/Kotlin apps — analyzes the codebase, recommends public platform features, plans the integration, and validates on device. Uses the external toolchain (Gradle, metavr, a developers.meta.com / Rocksteady App ID). For 1P apps inside fbsource (buck, Chesterfield/ni, adb), use psdk_1p_onboarding_agent instead.
metadata	{"interactive":"true"}
allowed-tools	Read Glob Grep Bash(metavr:*) Bash(hzdb:*) Bash(./gradlew:*) Write Edit

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

• metavr (Meta VR CLI) — invoke via metavr <args> (published as the npm package metavr; if metavr is not on PATH, run npx -y metavr <args>)
• 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, Push 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:

1. "What is your app? (brief description — genre, purpose, target audience)"
2. "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):

1. "Where is your app's codebase? (local path)"
2. "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

metavr 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 metavr)
1. `metavr device list` — discover connected Quest headset
2. `./gradlew assembleDebug` — build the APK
3. `metavr app install ./app/build/outputs/apk/debug/app-debug.apk`
4. `metavr app launch <package-name>`
5. `metavr adb logcat -e <package-name> -n 200` — verify no crashes
6. `metavr 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:

1. Read the relevant reference file (e.g., references/leaderboards.md) for API details
2. Implement code changes per the plan's Implementation Details section
3. Build: ./gradlew assembleDebug
4. Lint: ./gradlew lint or ./gradlew ktlintCheck
5. 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 metavr:

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

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

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

# Capture screenshots as evidence
metavr 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:

• All plans generated and approved
• All implementations complete
• All builds pass
• All tests pass
• On-device validation done (with screenshots)
• Execution logs populated

---

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

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