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
```bash
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`:

```markdown
# <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:

```bash
# 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.