/design-native-extension-feature

name: design-native-extension-feature
description: Capture a 2-3 line pitch from the user, draft a product overview (PRD.md) and a technical design (ARCHITECTURE.md) for a third-party `.ppmplugin` native control, then walk through every operation's iOS + Android implementation strategy with opinionated recommendations (library choice, hosting, key APIs, edge cases) and capture the agreed spec in ARCHITECTURE.md §3.<n>. The depth of ARCHITECTURE.md is what lets the scaffold skill generate complete working code instead of TODO placeholders. Iterates with the user until they approve both docs. Optionally seeds from a design doc / FRD URL. PRD.md + ARCHITECTURE.md are the source of truth for every downstream skill (generate, build, assemble). Run this BEFORE any code is generated.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, AskUserQuestion, Skill
model: opus

/design-native-extension-feature

You produce `PRD.md` — the source of truth that downstream skills (`/generate-native-extension`, `/generate-ppmplugin`) read verbatim.

**Flow shape:** pitch-first extraction with iterative review. Not a form. The user describes what they want; you draft the full PRD; you ask **only** for what you couldn't infer; you iterate with the user until they explicitly approve.

The output is a single file: `PRD.md` in the user's current working directory.

---

Step 1 — Read the shared docs

Before anything else, read:

1. [`shared/shared-instructions.md`](../../shared/shared-instructions.md) — read-first protocol, safety rules, OS-aware invocation. 2. [`shared/prereq-check.md`](../../shared/prereq-check.md) — per `shared-instructions.md §1.5` (per-skill minimal prereq policy), this skill needs **no** toolchain checks: it writes two markdown docs and nothing else. There is no SDK fetch, no Node, no native build. **When in doubt, run less** — a downstream skill (`/generate-ppmplugin-manifest`, `/build-android-binary`, `/build-ios-binary`) runs its own check at the point it needs the toolchain.

**Print a one-line note per `shared-instructions.md §9.2`** before continuing:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Prereq check — /design-native-extension-feature
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    🟢 No prerequisites — this skill only authors markdown. Ready to proceed.

Do NOT pre-check Node, JDK, Android SDK, or Xcode. Design uses none of them. If a downstream skill needs them, that skill's own Step 1 will check. 3. [`shared/naming-conventions.md`](../../shared/naming-conventions.md) — the capability vs class distinction and the full derived-identifier table. 4. [`shared/ppmplugin-format.md`](../../shared/ppmplugin-format.md) — the `.ppmplugin` bundle format, the manifest/`receivers[]` dispatch contract, the native module symbol + canonical-prefix + reserved-name rules, and recommended error codes. This is the contract the design must ground against (see Step 3). 5. [`shared/error-codes.md`](../../shared/error-codes.md) — the **canonical error-code catalog** (module-layer + transport/PCF codes, their meanings, and the message-quality rules). When ARCHITECTURE §5 enumerates the operation's error codes, draw from this catalog first; only mint a new code when no catalog code fits, and add it here when you do.

If any read fails, STOP.

---

Step 2 — Detect existing state

Before opening a fresh pitch:

1. If `./PRD.md` exists:

• Read it. Read `./.extension-state.md` if present.
• Tell the user it exists and ask whether to **edit it iteratively** (jump into the review loop in Step 6 with the existing draft loaded), **discard and start over**, or **abort**.

2. If only `.extension-state.md` exists: warn the user, treat as fresh start. 3. Otherwise: continue to Step 3.

---

Step 3 — Ground in the `.ppmplugin` format

A third-party control ships a **native-only `.ppmplugin` binary bundle** — there is no `INativeExtension` SDK to fetch or version-pin. The contract you ground against is the bundle format and its manifest/`receivers[]` dispatch rules, which live in-repo at [`shared/ppmplugin-format.md`](../../shared/ppmplugin-format.md). Re-read it now (you already read it in Step 1) and hold these facts in working memory for the drafting step:

• The **bundle** is `manifest.json` + per-platform native binaries (Android DEX, flat iOS `.framework`) — **no TypeScript / JavaScript layer inside the bundle**. Dispatch routes straight to `NativeModules.<nativeModule>.<method>` via the wrap proxy (ppmplugin-format §2 *Runtime dispatch contract*). (The **companion PCF**, deployed separately, calls the host `window.PowerApps.NativeExtension.sendAsync` global to reach that dispatch — see §6.2 — but that transport layer is NOT part of the bundle.)
• The native module symbol, the manifest `name`, and the `receivers[].nativeModule` are mechanically derived from the **class name** and gated by the validator's canonical-prefix + reserved-name rules (ppmplugin-format §3 + §4). The design must pick a class name that survives those rules — Step 5's identity gap-check enforces this.
• The recommended error-code baseline lives in `ppmplugin-format` — branch domain-specific codes off it in ARCHITECTURE §5.

There is no live fetch and no version pin to resolve. Unlike the first-party path (which pins an SDK version into ARCHITECTURE §1.1), the third-party bundle pins an **ABI compatibility range** (`compatibleShells` / `builtAgainst`) — that lives in the manifest, authored later by `/generate-ppmplugin-manifest`, not here.

---

Step 4 — The pitch

Open with one prompt:

> Tell me in 2–3 lines what you're trying to build. Include the device capability it surfaces and what a maker would do with it in a Canvas app. > > If you have a design doc, FRD, wiki page, or any existing spec, paste the URL or local path — I'll read it before asking anything.

Capture the pitch and the doc reference (if any). Don't ask follow-ups yet.

4a —