create-mobile-app

name	create-mobile-app
description	Use when the user wants to start a new Power Apps mobile app (Expo / React Native / TypeScript, targeting iOS and Android) from scratch.
user-invocable	true
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Task, EnterPlanMode, ExitPlanMode
model	opus

📋 Shared instructions: shared-instructions.md — read first. Covers safety guardrails, memory bank usage, preferred-environment policy, connector-first rule, Windows CLI compat, command-failure handling.

Create Power Apps Code App (Native)

Top-level orchestrator. Owns the user-visible flow; delegates planning to the native-app-planner agent and per-domain mutation to dedicated /add-* skills.

Workflow

0. Resume check + fresh-template gate → 1. Prerequisites → 2. Gather requirements → 2b. Requirements discovery → 2c. Plan preview (rough cost + abort gate) → 3. Plan (planner agent + 4 gates) → 4. Auth & environment → 5. Prepare existing template → 6. npx power-apps init → 6.5 verify npm install → 6.5b SafeAreaProvider gate (always runs, idempotent) → 6.6 scaffold tsc smoke check → 6.7 seed memory bank → 6.85 Offline profile (always asked) → 7. Auth config → 8. Apply data model → 9. Apply native capabilities → 9b. Design system → 10. Add connectors → 10b. Wire navigation layout → 11. Build screens (parallel) → 11.4 Stylistic fix sweep → 11.5 Dev smoke test → 12. Start dev server (npx expo start) → 13. Summary

---

Fresh-template working-directory mode

This skill assumes the user already has a fresh pa-wrap-tools/templates/expo-app-standalone template materialized with degit in the target working directory and has already run npm install there. The skill turns that fresh template into an app; it does not clone, degit, or copy a template itself.

Fresh template required. If the working directory is not a template, or if it already looks like an app created by this skill, STOP and tell the user to materialize a fresh expo-app-standalone template with degit into a new folder, run npm install, then rerun /create-mobile-app --working-dir <fresh-template-dir>.

Use these markers:

State	Detection	Action
Fresh template	package.json, app.config.js, auth.config.json, tamagui.config.ts exist; node_modules/expo exists; memory-bank.md, native-app-plan.md, .datamodel-manifest.json, and generated Dataverse services are absent	Proceed.
Template not installed	Fresh-template files exist but node_modules/expo is absent	STOP: ask user to run npm install in the template folder, then rerun. Do not provision ADO npm tokens here.
Already-created app	memory-bank.md, native-app-plan.md, .datamodel-manifest.json, or src/generated/services/*.ts exists	STOP: this is not a fresh create target. Ask user to materialize a fresh template folder with degit.
Not template	Required template files are missing	STOP: ask user to materialize pa-wrap-tools/templates/expo-app-standalone into the working directory with degit and run npm install.

This gate is intentionally simple: /create-mobile-app creates a new app from a fresh template. It does not adopt, repair, resume, or overwrite an already-created app.

---

TypeScript Gate Policy — no quality compromise

tsc is a phase gate, not a reflex after every tiny edit. The app may not advance past a gate until TypeScript is clean.

Required gates:

• Scaffold gate: Step 6.6 after existing-template preparation, npx power-apps init, and dependency verification.
• Dataverse/generated-services gate: immediately after Step 8 returns and generated services/models are refreshed.
• Navigation/skeleton gate: after Step 10b layouts and Step 10.8 shared code/skeletons are written, before Step 11 builders launch.
• Screen-wave gate: after each Step 11 screen-builder wave returns, before launching the next wave.
• Final gate: before Step 12 starts the dev server.

When a gate fails:

1. Capture the full tsc --noEmit output once.
2. Classify errors by root cause (for example: generated model names, service option shapes, invalid UI props, typed percentage values, create/update payload typing, missing imports).
3. Repair in a batch.
4. Re-run the same gate once after the batch.
5. Continue only when the gate is clean, or stop/block according to the retry policy.

Do not run full-app tsc after every microscopic local edit inside the same repair pass. That is slower and encourages line-by-line patching. Batch root-cause fixes, then re-run the gate. This is a speed improvement only; it does not lower the quality bar.

Hard stops:

• Do not launch data-source work from a broken scaffold gate.
• Do not launch screen-builders from broken generated services, layouts, shared code, or skeletons.
• Do not launch wave N+1 until wave N passes its tsc gate.
• Do not start the dev server until the final gate is clean.
• Do not hide approved capability failures behind mocks or TODOs just to satisfy tsc.

---

Step 0 — Resume check + fresh-template gate

If $ARGUMENTS includes a --working-dir (or the user names an existing directory), check whether <working_dir>/memory-bank.md exists.

• Bank present → read it. Identify the highest-numbered completed step. Inform the user:

  "Found existing project '' at <dir>. Steps 1– already completed (last update ). Resume from Step <N+1>?" Wait for confirmation. If the user says yes, jump to that step. Skip the wizard (Step 2) and re-use the values stored in the bank.

• Bank absent → fresh project. Continue to Step 1.
• Bank present but corrupted (missing required headings) → surface the parse error, ask the user whether to overwrite (lose history) or fix manually before proceeding.

The bank is the only resume mechanism. Do not infer resume state from package.json or node_modules/ — those can lie.

After the resume check, run the fresh-template gate from the section above. This is a create-only command:

• If memory-bank.md exists and the user confirms resume, resume as documented above.
• If any already-created-app marker exists and there is no approved resume path, STOP and tell the user to materialize a fresh template into a new folder with degit.
• If required template files are missing, STOP and tell the user to materialize pa-wrap-tools/templates/expo-app-standalone into the working directory with degit and run npm install.
• If node_modules/expo is missing, STOP and tell the user to run npm install in that template folder before rerunning this skill.

Do not silently copy a bundled template over the user's folder. A fresh pa-wrap-tools-1 template may contain placeholder power.config.json with an empty environmentId; Step 5 removes that placeholder immediately before Step 6 runs npx power-apps init.

Step 1 — Prerequisites

Run all checks first — no point gathering requirements if the toolchain isn't ready.

Important: npm auth and Power Platform app auth are separate. The account used for npm install can be different from the account used by npx power-apps:

What	Uses	Typical account
npm install private feed access	npm/Azure Artifacts auth configured outside this skill	Account with feed Reader access
npx power-apps init, Dataverse, deploy	npx power-apps browser auth + az login --tenant <env-tenant> for Dataverse helper scripts	Power Platform environment account, often a test-tenant/admin account

Renewing npm feed auth does not sign the user into npx power-apps. If the Power Apps CLI prompts for browser auth later, that is expected and unrelated to the npm/ADO feed token.

Then run the checks:

node --version                                      # v22+
npm  --version                                      # v10+
az account show --query "user.name" -o tsv          # Azure CLI logged in (needed for Dataverse helper scripts)
git --version                                       # optional

Do NOT probe Xcode, Java, Android Studio, or CocoaPods here. This plugin's flow is plan → scaffold → code → local Expo dev server. Build + deploy (npm run build / npx power-apps push) is a separate user-driven step via the /deploy skill. Local native compile is the user's choice and lives outside this skill (run the platform-specific native command directly when needed). See shared/version-check.md — only the Always required tier matters here.

Missing	Action
Node < 22	STOP — instruct nvm install 22 && nvm use 22
az	STOP — instruct az login

Template-only rule: this skill no longer provisions npm feed tokens, PAT fallbacks, vendor fallbacks, or registry rewrites. The user must run npm install in the fresh template folder before invoking /create-mobile-app.

Capture target Power Platform environment for the remaining flow.

Source of truth for env selection: the generated power.config.json first, explicit environment ID second. In the normal template-folder flow, npx power-apps init runs first and writes the selected environment ID into power.config.json; read that ID and pass it to scripts/resolve-environment.js to resolve the Dataverse URL and tenant. If power.config.json is missing or has an empty placeholder environmentId, ask for an environment ID. A Dataverse URL is useful as a resolver fallback for existing apps, but it is not enough for npx power-apps init because init needs --environment-id.

Step	Source	When user is asked
0. power.config.json has environmentId	scripts/resolve-environment.js <environment-id>	Never — automatic after npx power-apps init
1. User supplies env ID	scripts/resolve-environment.js <environment-id>	Ask only if power.config.json is missing/empty or user wants a different env
2. User wants a different account	Follow shared-instructions standalone CLI auth handling	Only if resolution/token acquisition fails or user asks
3. User wants different env	Ask for another env ID and re-run resolver	Only if user selects "use a different environment" at Step 2
4. npx power-apps init --display-name "$DISPLAY_NAME" --environment-id $ACTIVE_ENV_ID --non-interactive	Persists choice into power.config.json	Only when this skill owns the initial init path

TARGET_ENV="<environment-id-or-empty>"
if [ -z "$TARGET_ENV" ] && [ -f power.config.json ]; then
  TARGET_ENV=$(node -e "try { const id=require('./power.config.json').environmentId || ''; console.log(id); } catch { console.log(''); }")
fi
test -n "$TARGET_ENV" || { echo "✗ Environment missing. Provide an environment ID."; exit 2; }
ENV_JSON=$(node "${CLAUDE_SKILL_DIR}/../../scripts/resolve-environment.js" "$TARGET_ENV")
printf '%s\n' "$ENV_JSON" > .resolved-environment.json
ACTIVE_ENV_ID=$(node -e "const j=JSON.parse(process.argv[1]); console.log(j.environmentId || '')" "$ENV_JSON")
ACTIVE_ENV_NAME=$(node -e "const j=JSON.parse(process.argv[1]); console.log(j.displayName || j.environmentUrl || '')" "$ENV_JSON")
ACTIVE_ENV_URL=$(node -e "const j=JSON.parse(process.argv[1]); console.log(j.environmentUrl || '')" "$ENV_JSON")
ACTIVE_TENANT_ID=$(node -e "const j=JSON.parse(process.argv[1]); console.log(j.tenantId || '')" "$ENV_JSON")
test -n "$ACTIVE_ENV_ID" || { echo "✗ Environment ID missing. Provide the environment ID directly."; exit 2; }
echo "✓ Target env: $ACTIVE_ENV_NAME ($ACTIVE_ENV_ID)"
echo "✓ Target env URL: $ACTIVE_ENV_URL"
echo "✓ Target tenant: ${ACTIVE_TENANT_ID:-unknown}"

Orchestrator handling for exit 2: ask the user for their environment ID directly, then re-run the capture block above. Do not run npx power-apps init here; Step 6 owns initialization after the user confirms the target environment.

Stash $ACTIVE_ENV_ID, $ACTIVE_ENV_NAME, $ACTIVE_ENV_URL, and $ACTIVE_TENANT_ID for Step 2 (env confirmation), Step 6 (npx power-apps init), and Step 7 (auth.config.json tenant/environment cache). If parsing fails, ask for an environment ID again.

If resolve-environment.js cannot get tokens, run az login --tenant <env-tenant> in the foreground. If npx power-apps init later uses the wrong account, follow shared-instructions standalone CLI auth handling and retry once.

Step 1.7 — Detect publisher prefix

Detect the publisher prefix for the env's Default solution so the planner uses the correct prefix rather than assuming cr_.

node "${CLAUDE_SKILL_DIR}/../../scripts/detect-publisher-prefix.js" "$ACTIVE_ENV_URL"

Output is one line of JSON, e.g.:

{"prefix": "cr8142a", "source": "detected"}
{"prefix": null, "reason": "no token (run `az login --tenant <env-tenant>`)"}

The script queries the Default solution's publisher via: /api/data/v9.2/solutions?$select=uniquename&$expand=publisherid($select=customizationprefix)&$filter=uniquename eq 'Default'

A second solution name can be passed as a second argument if the env uses a different solution (defaults to 'Default').

Token tenant note: the script's getAuthToken discovers the env's tenant ID from the Dataverse HTTPS auth challenge and passes --tenant <env-tenant> to az, so detection works even when the active az identity is on a DIFFERENT tenant. If the user has not run az login --tenant <env-tenant> at any point, detection may return null.

Stash the result for Step 3 (planner spawn):

Output	Stash as	Behavior at Step 3
{"prefix": "cr8142a", ...}	$DETECTED_PUBLISHER_PREFIX = "cr8142a"	Pass to planner prompt as a fact: "Publisher prefix (detected from env): cr8142a_"
{"prefix": null, ...}	$DETECTED_PUBLISHER_PREFIX = "" (empty)	Pass to planner as: "Publisher prefix: NOT DETECTED — use placeholder cr_ and warn the user that Dataverse will normalize the actual prefix at create time."

Do NOT block on null detection — the user can still proceed; the Power Apps CLI normalizes prefixes when npx power-apps add-data-source runs. The detection step is purely to make the plan output accurate.

If the script exits non-zero (rare — should always exit 0 with prefix: null), treat it as the null case and continue.

Step 2 — Gather requirements

Skip questions the user already answered in $ARGUMENTS.

If the user gave no description, ask one open-ended question first:

"What would you like to build? Describe it in your own words — what it does, who uses it, and what problem it solves."

Then collect with AskUserQuestion (batch where possible):

Question	Default
App display name	derived from description
Target platforms	ios, android (multi-select, default both)
Aesthetic	minimal / playful / professional / matches existing brand
Target environment	Confirm <ACTIVE_ENV_URL> / <ACTIVE_ENV_ID> from Step 1.6, or choose "use a different environment" and provide another environment ID

App slug is auto-derived from the display name (slugify(displayName) — kebab-case, ASCII-only, strip non-alphanumerics). Do NOT ask the user; the derived slug is correct >95% of the time. Show the resolved slug as part of Step 2c's plan preview so the user can override via edit if needed.

Environment override branch: If the user picks "use a different environment", ask for the Power Platform environment ID via AskUserQuestion, then run scripts/resolve-environment.js again and refresh $ACTIVE_ENV_ID / $ACTIVE_ENV_URL / $ACTIVE_TENANT_ID.

App-name collision pre-flight. Once <displayName> is fixed, check the chosen env for a name collision:

npx power-apps list-codeapps --environment-id "$ACTIVE_ENV_ID" --json 2>/dev/null | grep -F "<displayName>" >/dev/null && \
  echo "COLLISION" || echo "OK"

If COLLISION, ask the user via AskUserQuestion:

"An app named <displayName> already exists in <ACTIVE_ENV_NAME>. Choose:

1. Pick a different name (recommended)
2. Delete the existing app in Maker portal — DESTRUCTIVE, asks confirmation outside this skill
3. Continue anyway (bg npx power-apps init will fail; you'll have to rename later — NOT recommended)"

Re-prompt for name if (1). If (2), send the user to Maker portal to delete the existing app, then re-run the collision check. Only proceed once collision is resolved.

If npx power-apps list-codeapps is unavailable in the installed CLI version, skip the pre-flight silently and continue.

Don't enter plan mode here — that's the planner agent's job in Step 3.

Step 2b — Requirements discovery

Goal: Turn the user's thin prompt into a confirmed feature brief before the planner runs. The planner agent receives this brief verbatim — richer input means better data model inference, accurate connector detection, and correct screen specs.

Step 2b.0 — Prompt richness scoring (decides which path to take)

Before asking anything, score the description on four signals. The score decides whether we ask a multi-select feature picker, a single confirmation, or skip the discovery question entirely.

Run this scorer mentally on <description> (the prompt the user gave with /create-mobile-app, plus any clarifying text from Step 2a). Count how many of the four trip:

Signal	Trips when
Word count	description has ≥ 60 words
Distinct nouns	description names ≥ 5 distinct domain nouns (people, things, documents, places — e.g. "inspector", "aircraft", "gate", "defect", "evidence")
Action verbs	description uses ≥ 3 workflow verbs from this set: log, track, submit, assign, notify, scan, upload, approve, verify, complete, capture, override, dispatch, review, sign
Domain phrase	description names a known industry domain — match against the industry table in shared/references/universal-patterns.md (airline, hospital, retail, manufacturing, field-service, finance, logistics, …) OR explicitly says "field operations" / "ground operations" / "site visit" / similar

Tier the result:

Score	Tier	What to do
4 / 4	auto-plan	Skip both questions. Extract the brief silently from <description>, write native-app-plan.md placeholder, fall through to Step 2c. The user's next interaction is the cost-estimate gate.
3 / 4	one-tap	Skip the multi-select. Extract the brief, show it once, ask only "Look right? (yes / adjust)". On yes → Step 2c. On adjust → fall through to walk-through.
≤ 2 / 4	walk-through	Current behaviour. Run the multi-select feature picker described in Step 2b.1, then the brief confirmation.

Print the chosen tier so the user knows which path is running:

"→ Prompt richness: 4/4 — skipping discovery questions, extracting brief and going straight to the plan-cost preview." (or 3/4 / ≤2/4 with the matching path name)

--full-discovery escape hatch: if $ARGUMENTS contains --full-discovery, force walk-through regardless of score. Use this in dogfood runs where you want to exercise the multi-select path.

--no-discovery escape hatch: if $ARGUMENTS contains --no-discovery, force auto-plan regardless of score. Use this for fully-headless runs from the wrapper templates repo.

Step 2b.1 — Walk-through path (only when tier = walk-through)

Read references/requirements-discovery.md. Infer context-aware options from the user's description, ask exactly one structured AskUserQuestion, and never use markdown checkboxes in the question text.

Wait for the user's response. Summarize their answers into a requirements brief — 4–8 bullet points covering what users can do, what data is tracked, and integrations.

Confirm once:

"Here's the brief I'll use for planning: • (bullet 1) • (bullet 2) ... Look right? (yes / adjust)"

Store the confirmed brief as <requirements_brief>. This replaces the thin $ARGUMENTS as the primary input to the planner.

Step 2b.2 — One-tap path (tier = one-tap)

Skip the multi-select question. Extract a 6–10 bullet brief directly from <description> covering: user roles, key entities, primary workflow, severity / status enums if present, integrations / connectors, native capabilities, and any explicit constraints. Show it with a single confirm:

"Your description is detailed enough to skip the feature picker. Here's the brief I extracted: • (bullet 1) • (bullet 2) ... Look right? (yes / adjust / start over)"

• yes → store as <requirements_brief>, fall through to Step 2c.
• adjust → drop to Step 2b.1 (walk-through) so the user can edit via the multi-select.
• start over → return to Step 2a and re-prompt for the description.

Step 2b.3 — Auto-plan path (tier = auto-plan)

Skip both the multi-select AND the brief confirmation. Extract the brief silently and store it as <requirements_brief>. Print it as a transparency log only:

"→ Auto-plan tier (4/4). Extracted brief from your description: • (bullet 1) • (bullet 2) ... → Going straight to the plan-cost preview (Step 2c). The brief above is locked in unless you abort there."

Do not ask for confirmation here — the user agreed to this when their prompt scored 4/4. The plan-preview gate at Step 2c remains in force as the last cheap exit before any side effects.

Step 2b.4 — Common to all paths

Auto-proceed after yes (or after auto-plan transparency log). Fall through directly to Step 2c (plan preview). Do NOT add a separate "Proceed to planning?" prompt — the brief confirmation IS the planning go-ahead. The only abort gate after this is Step 2c's proceed/edit/abort block, which is intentionally distinct because it shows the rough cost estimate.

Design decisions are deferred to Step 6.75 — /design-system (ships with this plugin) handles brand inputs, the style picker, and visual companion preference in one flow after the project is scaffolded. Do NOT ask design questions here.

Set tentative defaults (used by Step 3b before /design-system runs):

• <visual_companion> = yes — open _plan_preview.html in browser at Gate 4 by default. /design-system at Step 6.75 may downgrade this to no (path (d) in its cost picker), persisted to memory-bank for future runs.
• <design_vibe_opt_in> = deferred — Step 6.75 sets the real value. While deferred, the planner does NOT prompt for a direction; it writes a placeholder ## Design Direction: <deferred — set by /design-system> block so screen-planner can still run.

--no-design escape hatch. For headless / token-constrained runs, set --no-design in $ARGUMENTS. It forces <visual_companion> = no, skips the style-picker handoff at Step 3a entirely, and short-circuits Step 6.75 to a no-op (placeholder block stays in native-app-plan.md; screen-builders fall back to industry-inferred defaults).

Step 2c — Plan preview (rough, always shown)

Goal: Give the user a cheap exit before any mutation happens. This is the last point in the flow with zero side effects — no git clone, no npm install, no npx power-apps init, no agent tokens spent on planning. After Step 3 starts, every abort gets more expensive (half-written native-app-plan.md, partial _screens_section.md, architect tokens already burnt).

Always runs. There is no --no-preview flag in v0 — we need calibration data (~10+ runs with recorded estimate-vs-actual) before we can trust the rough estimates enough to let users skip them. Once the data shows estimates are reliably within ±50%, evaluate adding a skip flag for repeat-user workflows.

Compute the estimates from inputs already in hand (no agent spawn — pure heuristics on the confirmed brief and the wizard answers):

Output	Input proxy	Computation	Confidence
Tables	Distinct nouns in confirmed brief	count(unique_nouns) × [0.7, 1.3] rounded	low — architect may merge or split
Connectors	Step 2b inferred connector list	len(inferred) (already exact)	high
Screens	Confirmed features in brief	count(features) × [2, 3]	low — depends on navigation choice
Planning min	Tables + screens	tables × 0.3 + screens × 0.4 + 2	low
Scaffold min	Fixed	1-2 (template preparation + npm install already happened before skill invocation)	high
Build min	Screens, parallel cap of 5	ceil(screens / 5) × 0.6	medium
Extra prompts	<industry_confidence> + <design_vibe_opt_in>	+1 if low-confidence industry; +1 if vibe-opt-in == yes	high

Print the block once, exactly in this format (substitute computed values; ranges as low-high):

─── Plan preview (rough) ─────────────────────────────────
Based on your confirmed brief, before any agent runs:

Scope (proxy estimates — actual numbers come from architects):
  Tables       ~<low>-<high>      ← from <N> nouns in brief; architect may merge/split
  Connectors    <N> inferred      ← <comma-separated names>  (confirm at Gate 3)
  Screens     ~<low>-<high>       ← from <N> features × ~2-3 screens each
  Approval gates  4               ← fixed (data model, native, connectors, screen plan)

Time (rough — agent time only, excludes your approval latency at gates):
  Planning      ~<low>-<high> min ← architects + your gate approvals add to this
  Scaffolding   ~1-2 min          ← validates prepared template + runs power-apps init
  Screen build  ~<low>-<high> min ← parallel, capped at 5 concurrent

Token tier: Opus everywhere in v0 (model routing not yet shipped).

⚠ These are proxies, not measurements:
  • Table count is "noun count in brief" — architect may collapse or split
  • Time excludes your approval latency at the 4 gates
  • If industry inference is low-confidence, +1 picker prompt
  • If you opted into the design vibe picker, +1 prompt + planner re-spawn
  • If any gate is rejected, that section regenerates (~2-3 min each)

Proceed, edit brief, or abort? [proceed/edit/abort]
─────────────────────────────────────────────────────────

Three-option exit:

User answer	Action
proceed (or empty / Enter)	Continue to Step 3. Default.
edit	Jump back to Step 2b. Re-confirm the brief with the user's changes. After 2b re-confirms, return here for a fresh preview. No working dir mutations — Step 2c runs before mkdir -p <working_dir> in Step 3.
abort	Print "Aborted at Step 2c. No files created. Re-run /create-mobile-app when ready." and exit cleanly. No working dir, no memory bank, no scaffold.

Why "always show" is correct in v0 (do not skip without explicit user request):

• Cost when user proceeds: ~30s (read + decide). Token cost ~500/run = ~$0.008.
• Cost when user aborts late (after Step 3 starts): 5-10 min + dirty working dir + frustration.
• Asymmetry: bounded 30s vs unbounded 30 min. Always show the bounded cost.
• Forced calibration: every run produces the <estimate, actual> data we need for v0.x model routing decisions. Skipping drops calibration data.

Set expectations before handing off to the planner:

"Brief locked in. Planning surfaces 4 approval prompts (data model → native capabilities → connectors → screens). Total time is 5–12 minutes: • Gate 1 (data model) — ~60–90s • Gate 2 (native capabilities) — ~10s (quick) • Gate 3 (connectors) — ~30–60s • Gate 4 (screens + design) — 3–8 minutes (this is the heavy one: design vibe picker if opted in, then per-screen specs and HTML preview generation)

Between gates the spinner will sit quiet — sub-agents can't stream their progress to this view. If a gate hasn't surfaced after 12 minutes, something is stuck and you should interrupt."

Step 2d — Template-only mode

No background scaffold pipeline is used. The template is already present in <working_dir> and dependencies are expected to be installed before this skill starts (npm install). Continue directly to Step 3.

Step 3 — Plan (planner agent + 4 approval gates)

First, create the empty working directory so the planner has a place to write:

mkdir -p <working_dir>

Hard rule — planner writes are restricted during Step 3. The planner (and any sub-agents it spawns) is permitted to write to only:

• <working_dir>/native-app-plan.md
• <working_dir>/_screens_section.md
• <working_dir>/.tmp/*

All other paths in <working_dir>/ (notably app/, src/, package.json, power.config.json, tamagui.config.ts, tsconfig.json, node_modules/, memory-bank.md) are owned by the foreground setup phases. Do not mutate them during planning.

If the planner needs to record a DONE_WITH_CONCERNS from a sub-agent (data-model architect, screen-planner), add it to an in-memory queue DEFERRED_CONCERNS[] during Step 3. Do not write memory-bank.md yet. Step 6.7 must always flush DEFERRED_CONCERNS[] into memory-bank.md ## Concerns immediately after the file is created.

Resume-from-draft check. Before spawning, check if <working_dir>/native-app-plan.md already exists with content. If yes, a previous planner run (possibly in a degraded context with no Task/gate tools) already drafted sections. Read it. If it has populated ## Data Model / ## Native Capabilities / ## Connectors but the gates were never run (no ## Approvals block, or the file was authored by an agent that returned BLOCKED: tool surface missing), pass resume_from_draft: true and the existing path to the planner so it loads the draft as baseline instead of regenerating from scratch.

Planner preflight (silent). Before the full Task spawn, do a no-op Task probe for mobile-app:native-app-planner (same pattern as Step 11.0). If the probe fails with Agent type … not found, tool unavailable, or the host clearly cannot route nested agents, fall through to inline-gate mode (described below) without prompting. The orchestrator has the full tool surface itself — it can run the gates directly. Do not retry, do not ask the user.

Announce the handoff before the Task call (so the user isn't staring at a blank screen while the planner spins up):

"→ Spawning planner agent. First prompt (data model) appears in ~60–90 seconds while the data-model architect analyzes your requirements. Later gates take longer — see the timing breakdown above."

Then spawn the mobile-app:native-app-planner agent via Task (the plugin name mobile-app: prefix is required — without it Task returns Agent type not found):

Spawn agent: mobile-app:native-app-planner

Prompt:
  Plan a Power Apps mobile app.

  Requirements brief (confirmed with user):
  <requirements_brief — bullet points from Step 2b>

  Design vibe opt-in: <design_vibe_opt_in — always "deferred" unless `--no-design` is in $ARGUMENTS, in which case use "skip". Never invent yes/no/other values.>
  Visual companion: <visual_companion — "yes" or "no">

  Original prompt: <full $ARGUMENTS verbatim>
  Wizard answers: <Step 2 answers>
  Working directory: <absolute path of <working_dir>>
  Plugin root: ${CLAUDE_SKILL_DIR}/../../
  Publisher prefix (detected from env): <DETECTED_PUBLISHER_PREFIX from Step 1.7, e.g. "cr8142a" — use literally as `<prefix>_<entity>` in all logical names. If empty/NOT DETECTED, fall back to `cr` placeholder and surface a `DONE_WITH_CONCERNS` note that Dataverse will normalize at create time.>

  Follow native-app-planner.md. Run all 4 approval gates. On terminal return, emit one of `DONE` / `DONE_WITH_CONCERNS:` / `NEEDS_CONTEXT:` / `BLOCKED:` as the literal first line per AGENTS.md rule #10.

The planner runs gates internally for data model → native capabilities → connectors → screen plan, and writes <working_dir>/native-app-plan.md. Wait for it to return before continuing — do not proceed on a partially-approved plan.

3.0a — Inline-gate fallback (planner unavailable OR returned BLOCKED: tool surface missing)

When the preflight fails OR the planner returns BLOCKED: tool surface missing <…>, the orchestrator runs the four gates inline. Do NOT re-spawn the planner — it cannot succeed in this host. Print once:

"→ Planner agent unavailable in this host — running approval gates inline. (No action needed; this is automatic.)"

Then execute, in order, using your own EnterPlanMode + AskUserQuestion:

1. If a draft native-app-plan.md exists: read it as baseline. Surface each populated section (## Data Model, ## Native Capabilities, ## Connectors) one at a time via EnterPlanMode, take user feedback inline, edit the file in place. Skip generating sections that are already populated and approved.

2. If no draft exists: spawn mobile-app:data-model-architect directly via Task (single architect, not the orchestrator agent) to draft ## Data Model; then build ## Native Capabilities + ## Connectors inline from the brief; then spawn mobile-app:screen-planner with phase: graph and phase: specs per the two-phase Gate 4 split.

   Before each screen-planner spawn, print a one-line ETA so the user knows the agent is live and roughly how long to wait (the agent's own Bash echo progress markers — see agents/screen-planner.md "Progress streaming" — surface every milestone, but the orchestrator's pre-spawn line gives the wall-clock budget):

   • Before phase: graph: > "→ [Gate 4a] Spawning screen-planner phase=graph (~2 min for ${N} screens)…"
   • Before phase: specs: > "→ [Gate 4b] Spawning screen-planner phase=specs (~1 min/screen, ~${N} min for ${N} screens). Progress markers will appear inline."

MUST forward $DETECTED_PUBLISHER_PREFIX from Step 1.7 in the architect prompt — same line as the planner prompt at Step 3 line 1034: "Publisher prefix (detected from env): <DETECTED_PUBLISHER_PREFIX> — use literally as <prefix>_<entity> in all logical names. If empty/NOT DETECTED, fall back to cr placeholder and surface a DONE_WITH_CONCERNS note that Dataverse will normalize at create time." Without this, the architect defaults to cr_ and the whole plan needs a post-hoc sweep when the real prefix is something else (e.g. cr3e9).

Why this works even though the planner just returned BLOCKED for tool surface: the orchestrator (this skill, running in the user's slash-command session) always has the full tool surface — Task, EnterPlanMode, ExitPlanMode, AskUserQuestion, Read, Write, Bash. What's missing is the surface inside nested agent contexts (the native-app-planner agent runs in a sandbox without EnterPlanMode/AskUserQuestion, which is why its Step 0 preflight returned BLOCKED). The leaf agents data-model-architect and screen-planner only need Read/Write/Bash to draft markdown — they don't need EnterPlanMode/AskUserQuestion themselves. Spawn them; the orchestrator owns the gates.

3. Run the gates yourself — use EnterPlanMode four times (data model → native caps + connectors merged → screen graph 4a → screen specs 4b). Same gate prompts as the planner agent would use. Gate 4 is a markdown screen-graph review only — design picking happens unconditionally at Step 6.75 via /design-system (no separate style-picker handoff at Gate 4 even in inline mode).

4. Write the final approved native-app-plan.md with an ## Approvals block at the bottom listing each gate, who approved (user), and a timestamp.

   HARD RULES for the plan structure (mirror the planner agent's template at agents/native-app-planner.md Step 4):

   • Top-level headings are EXACTLY: ## Overview, ## App Requirements, ## Data Model, ## Native Capabilities, ## Design Direction, ## Connectors, ## Screens, ## Approvals. Do NOT invent a ## Brief super-section that nests the data model under it.
   • ## App Requirements is the user's confirmed brief verbatim (the <requirements_brief> from Step 2b), capped at ~80 lines. No expansion, no rewriting, no embedded preview of the data model.
   • Discovery failure notes (e.g. az login on the wrong tenant, 401 from dataverse-request.js, all entities classified Create) go to <working_dir>/memory-bank.md under ## Discovery Notes, NOT into the plan. Keep at most a single one-line breadcrumb in ## Data Model like > Discovery skipped — see memory-bank.md. if relevant.
   • Sample data notes, immutability plug-in notes, file-column setup notes, dispatch-block server rules go under a single ### Notes subsection in ## Data Model. Cap each at 2 sentences; link to post-deployment-tasks.md for longer write-ups instead of inlining.

If the orchestrator's OWN Task tool is unavailable (rare — would mean even leaf agents can't be spawned), fall further to fully-inline mode: orchestrator drafts the data model from a Dataverse OData probe (resolve-environment.js + table list filter on the brief's domain keywords), drafts native caps + connectors heuristically, drafts the screen graph + specs against shared/references/screen-templates.md, and runs the four gates against the user. This is the last-resort path — functional but slower because the orchestrator does work the architects normally parallelize.

Hard rule: never silently skip a gate just because the planner couldn't run. The user MUST approve each section through EnterPlanMode before any mutation step (Step 8 onwards) executes.

3.0 — Sub-agent return-status switch (canonical)

Use the plugin-wide protocol in AGENTS.md rule #10 for every Task return in this skill: planner, parallel screen-builders, and future agent spawns. Parse the literal first line and branch: DONE continues; DONE_WITH_CONCERNS: surfaces + records in memory-bank.md; NEEDS_CONTEXT: re-dispatches with missing context, capped at 2 retries; BLOCKED: stops and records under ## Blocks. Unknown first lines are malformed and must be treated as BLOCKED.

Planner-only early-return signals are handled before the status switch: INDUSTRY_CONFIRM_REQUESTED: routes to Step 3.0a; DESIGN_VIBE_REQUESTED: routes to Step 3a. After the handoff, re-spawn the planner and process its new first line through this switch.

Step 3.0a — Industry confirmation handoff (orchestrator-owned)

When the planner is uncertain about which industry the app belongs to (no keyword match, ambiguous match, or wizard-aesthetic conflict), it returns early with this single line as its message:

INDUSTRY_CONFIRM_REQUESTED: <inferred-industry>|<reason-code>|<top-3-alternatives-comma-sep>

Example: INDUSTRY_CONFIRM_REQUESTED: productivity|no-keywords|field-ops,healthcare,e-commerce

This fires before Gate 1 — it's not a gate, just a confidence check so the wrong industry doesn't silently lock in the design language for the entire app.

Skip this section if <design_vibe_opt_in> is yes or skip — in those cases the user is either driving design explicitly (yes) or has opted out of design entirely (skip), so industry inference doesn't matter.

When you see INDUSTRY_CONFIRM_REQUESTED: and <design_vibe_opt_in> is no:

1. Parse the three pipe-delimited fields. Map reason codes to a short user-facing explanation:

   • no-keywords → "no clear industry signal in your description"
   • ambiguous-match → "your description matches multiple industries"
   • wizard-conflict → "your aesthetic answer doesn't match the inferred industry"

2. Map each industry slug to a one-line description for the picker (use these exactly):

   Slug	Description
   field-ops	Field/Ops — high contrast, large targets, camera-forward (Uber Driver, ServiceTitan)
   finance	Finance — blue palette, conservative type, generous whitespace (banking apps)
   healthcare	Healthcare — warm palette, friendly type, compassionate copy (patient apps)
   education	Education — bright playful, gamification, streak/progress (Duolingo)
   productivity	Productivity — near-monochrome, dense layout, monospace data (Linear, Notion)
   e-commerce	E-commerce — brand-forward color, product imagery, frictionless CTAs (retail apps)
   tech-iot	Tech/IoT — dark + accent gradients, data-dense cards, real-time indicators (monitoring dashboards)

3. Ask one AskUserQuestion:

   "Quick sanity check before I build the design: I inferred this is a app, but . Confirm or pick another:

   (a) — recommended (b) (c) (d) (e) Other / let me describe — free text

   Which? (a / b / c / d / e — default: a)"

4. Persist the answer:

   echo "<chosen-industry-slug>" > "<working_dir>/.industry-confirmed"
   

   For option (e), let the user free-text a description; map it to the closest slug (or productivity as final fallback) and store that.

5. Re-spawn the planner. Use the same prompt as Step 3, plus an extra line:

   Industry confirmed: <chosen-industry-slug>
   

   The planner will see this on re-spawn, skip its detection + confidence check, and lock the industry to your value. After the re-spawn, re-check the planner's return value — it may now return normally, or it may still return DESIGN_VIBE_REQUESTED: (handled in Step 3a) if the user opted into the vibe picker.

Step 3a — Style-picker handoff (no-op in current plugin layout)

/design-system ships with this plugin and always runs at Step 6.75, so the style-picker handoff at Gate 4 is a no-op. Behavior:

• The planner writes a placeholder ## Design Direction: <deferred — set by /design-system> block into native-app-plan.md at Gate 4 and proceeds without asking the user. Step 6.75 rewrites the placeholder with the real direction.
• If a legacy planner output emits DESIGN_VIBE_REQUESTED: as its first line, write the placeholder block yourself (insert before ## Design, or before ## Screens if ## Design is absent), then re-spawn the planner with Design vibe opt-in: done. Do NOT run a vibe picker here — Step 6.75 owns that.
• If --no-design is in $ARGUMENTS, write the placeholder block, mark <design_vibe_opt_in> = skip, and Step 6.75 also no-ops. Screen-builders fall back to industry-inferred defaults from universal-patterns.md.

If the planner's first return is anything other than DESIGN_VIBE_REQUESTED: — i.e. it ran all gates including Gate 4 normally — skip directly to Step 3b.

Step 3b — Open the plan preview in the user's browser (orchestrator-owned)

The planner emits a line of the form PLAN_PREVIEW_PATH: file://<abs-path>/_plan_preview.html before each Gate 4 plan-mode entry. The planner itself does NOT open the browser — sub-agent shells often lose GUI context, and silent open-failures leave the user staring at the spinner with no preview. The orchestrator owns this step because it has the user's interactive session.

When to run this: every time the planner enters or re-enters Gate 4 (initial pass + each reject loop). Detection: scan the planner's most recent visible output for the PLAN_PREVIEW_PATH: token; the value after the colon is the absolute file:// URL.

What to do:

1. Print the link in a dedicated message so the user always has the fallback (clickable in most terminals):

   "Plan-time visual preview: file:///_plan_preview.html"

2. If <visual_companion> = no, stop here. Do not attempt to open a browser. The user explicitly opted out; the printed link is their handle. Continue immediately to the planner's Gate 4 prompt.

3. Else attempt to open in the user's default browser via the OS-portable chain:

   open "<abs-path>/_plan_preview.html" 2>/dev/null \
     || xdg-open "<abs-path>/_plan_preview.html" 2>/dev/null \
     || powershell.exe -NoProfile -Command "Start-Process '<abs-path>\_plan_preview.html'" 2>/dev/null \
     || echo "Auto-open failed. Use the link above."
   

4. Do NOT block on success. If the chain prints "Auto-open failed", the link from step 1 is the user's fallback. Continue immediately so the planner's plan-mode prompt surfaces without delay.

If the planner returns without emitting a PLAN_PREVIEW_PATH: line, that is expected — the planner passes skip_preview: true to screen-planner since /design-system (always installed) renders the single visual preview at Step 6.75 after brand locks. Print:

"→ Gate 4 reviewed structurally. Visual preview will appear at Step 6.75 after /design-system locks your brand tokens (~5 min from now after scaffold)."

…and continue without attempting any browser open. Do not warn or treat this as an error — it is the documented behavior.

3.9 — Post-plan publisher-prefix gate

Before continuing to Step 4, verify the written native-app-plan.md actually uses $DETECTED_PUBLISHER_PREFIX from Step 1.7. Catches both the inline-fallback path missing the prefix and an architect that ignored the instruction.

if [ -n "$DETECTED_PUBLISHER_PREFIX" ]; then
  WRONG=$(grep -oE 'cr[a-z0-9]*_[a-z][a-z0-9_]*' "$WORKING_DIR/native-app-plan.md" \
    | grep -vE "^${DETECTED_PUBLISHER_PREFIX}_" | sort -u || true)
  if [ -n "$WRONG" ]; then
    echo "PLAN PREFIX MISMATCH — expected ${DETECTED_PUBLISHER_PREFIX}_, found:"
    echo "$WRONG"
  fi
fi

If mismatches are reported, sweep native-app-plan.md (and any auxiliary files like .datamodel-manifest.json if already written) replacing the wrong prefix with ${DETECTED_PUBLISHER_PREFIX}_ before Step 4. Do NOT proceed to Step 5 with a wrong-prefix plan — the sweep cost grows ~500 occurrences once services are generated.

Step 4 — Auth & environment selection

node "${CLAUDE_SKILL_DIR}/../../scripts/resolve-environment.js" "$ACTIVE_ENV_ID"

If the resolved environment doesn't match what the planner used in Step 3, ask the user for the intended environment ID and re-run resolve-environment.js. Capture the environment ID for Step 6.

Step 5 — Prepare existing template

This step is template-only and foreground-only. Do not clone/copy templates, do not run background scaffold jobs, and do not use any legacy fallback path.

Print before starting:

"→ [Step 5/13] Preparing existing Expo standalone template in <working_dir> …"

Required checks:

cd <working_dir>
test -f package.json && test -f app.config.js && test -f auth.config.json && test -f tamagui.config.ts
test -d node_modules/expo

If any required template file is missing, STOP:

"This folder is not a fresh expo-app-standalone template. Materialize a fresh template with degit into a new folder, run npm install, then rerun /create-mobile-app --working-dir <fresh-template-dir>."

If node_modules/expo is missing, STOP:

"Dependencies are not installed. Run npm install in the template folder, then rerun /create-mobile-app --working-dir <fresh-template-dir>."

If already-created markers appear (memory-bank.md, native-app-plan.md, .datamodel-manifest.json, or src/generated/services/*.ts) and Step 0 did not enter the resume path, STOP:

"This folder already looks like a created app. For a new app, materialize a fresh expo-app-standalone template with degit into a new folder and rerun this skill there."

Then apply these safe idempotent prep steps:

1. Update app identity in app.config.js and package.json from Step 2 answers (displayName, slug) using targeted string replacements only.
2. Ensure src/generated/index.ts exists with the empty generated barrel if no generated services exist.
3. Ensure src/components/, src/hooks/, src/utils/, src/tokens/, and src/native/ directories exist.
4. Copy shared helper files from plugin samples only when the destination file is missing. Do not overwrite user-edited files.
5. Merge the six path aliases into tsconfig.json (@/components, @/hooks, @/utils, @/tokens, @/generated, @/native) without deleting existing aliases.
6. Verify app/_layout.tsx imports PowerAppsProvider from @microsoft/power-apps-native-host and imports tamaguiConfig. If either is missing, patch _layout.tsx conservatively; do not rewrite custom navigation or unrelated provider code.
7. Remove placeholder power.config.json if its environmentId is empty or missing. npx power-apps init in Step 6 writes the real file for the selected environment.

Do not preserve placeholder power.config.json from the template. Keeping it would let downstream steps read an empty or stale environment.

After preparation, continue to Step 6.

Fix 1 — App identity in app.config.js and package.json

Substitute the hardcoded template values with wizard answers from Step 2:

Find	Replace with
`const APP_NAME = process.env.APP_DISPLAY_NAME
`const APP_SLUG = process.env.APP_SLUG
"name": "powerapps-standalone-app"	"name": "<slug>"

Bundle ID and scheme are left as template defaults — they are fixed across all dev builds and patched by the wrap pipeline at release time.

Fix 2 — Delete power.config.json

npx power-apps init in Step 6 creates the correct one for the user's environment. Remove the template copy:

rm -f "<working_dir>/power.config.json"

Fix 3 — Clean src/generated/ and src/hooks/ (idempotent)

Newer template snapshots no longer ship the example models / services / hooks (Contacts / Accounts / UserProfile / Office365Users) — src/ only contains app infrastructure files such as global.d.ts and playerConfig.ts. Older snapshots still do. If a copied template includes src/queryClient.ts, remove it: PowerAppsProvider already owns the React Query QueryClientProvider and screen code should use useQueryClient(), not an app-owned singleton. The block below is idempotent — a no-op on the new template, a real cleanup on the old one. Always run it; never assume one snapshot.

# Remove example generated artefacts if present (no error if missing)
rm -rf "<working_dir>/src/generated/models" \
        "<working_dir>/src/generated/services" \
        "<working_dir>/src/generated/index.ts"

# Wipe example React Query hooks and stale app-owned query client if present
rm -f  "<working_dir>/src/hooks/useContacts.ts" \
  "<working_dir>/src/hooks/useAccounts.ts" \
  "<working_dir>/src/hooks/useUserProfile.ts" \
  "<working_dir>/src/queryClient.ts"

# Reset the generated barrel so `import … from '../generated'` resolves to nothing
mkdir -p "<working_dir>/src/generated"
printf '// Populated by npx power-apps add-data-source. Do not edit.\nexport {};\n' \
  > "<working_dir>/src/generated/index.ts"

Do NOT overwrite app/(app)/home.tsx here. The current template ships a minimal RN stub (View + Text from react-native) that compiles cleanly. Our screen-builder replaces it at Step 11. Replacing it with a Tamagui stub before Fix 8 (which threads brand tamaguiConfig into PowerAppsProvider) would render under the upstream default Tamagui config instead of the project's brand tokens.

Keep src/hooks/ itself — screen-builders write new hooks into it.

Fix 3b — Scan for dangling imports referencing deleted files (back-compat only)

Only meaningful on older template snapshots that shipped the example hooks. On the current template the scan returns zero matches and you can skip it. Run it unconditionally — it is fast and self-skipping.

# Scan for any remaining imports of the deleted modules
grep -rn \
  -e "useContacts" \
  -e "useAccounts" \
  -e "useUserProfile" \
  -e "from.*generated/services" \
  -e "from.*generated/models" \
  --include="*.ts" --include="*.tsx" \
  "<working_dir>/app/" "<working_dir>/src/" \
  || true

If matches found:

• For screen files (app/(app)/*.tsx): replace the entire file with the same minimal stub used for home.tsx (screen-builder will overwrite at Step 11).
• For layout files (_layout.tsx): remove only the import lines and any code referencing the deleted symbols. Do NOT replace the whole file — layouts have navigation structure that must be preserved.
• For barrel/index files: remove the re-export lines.

If no matches: Continue — template is clean.

Fix 6 — Schema generation boundary

app/_layout.tsx imports schemaMap from src/generated/connectorSchemas.ts, which is generated by npm run generate-schemas (the generate-connector-schemas binary from the @microsoft/power-apps-cli devDep). Do not generate an empty schema map during initial scaffold: the template's @ts-ignore boundary lets tsc validate the scaffold without that artifact, and schema generation is more useful after a data source exists or immediately before dev/build entry points.

Do NOT hand-write a stub connectorSchemas.ts — the generated output has a specific shape that downstream code depends on; a placeholder will break npx power-apps push.

Why tsc already passes post-clone (current template, PR #30): the template's app/_layout.tsx and src/playerConfig.ts carry // @ts-ignore comments above the power.config.json and connectorSchemas imports specifically so the project type-checks before power.config.json and connectorSchemas.ts exist. Never strip these @ts-ignore lines — Fix 8 below preserves them when patching app/_layout.tsx to thread the project's tamaguiConfig into PowerAppsProvider, and any future Edit to either file MUST keep them. Removing them resurfaces a tsc failure against missing generated files.

Fix 7 — Create src/components/, src/hooks/, src/utils/, src/tokens/

Copy the shared code structure into the project. This gives screen-builders a production-grade layout with path aliases:

mkdir -p "<working_dir>/src/components"
mkdir -p "<working_dir>/src/hooks"
mkdir -p "<working_dir>/src/utils"
mkdir -p "<working_dir>/src/tokens"

cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/components/index.tsx" "<working_dir>/src/components/index.tsx"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/hooks/index.ts" "<working_dir>/src/hooks/index.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/hooks/useCursorListData.ts" "<working_dir>/src/hooks/useCursorListData.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/hooks/useListData.ts" "<working_dir>/src/hooks/useListData.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/hooks/useSearchFilter.ts" "<working_dir>/src/hooks/useSearchFilter.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/utils/index.ts" "<working_dir>/src/utils/index.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/utils/formatters.ts" "<working_dir>/src/utils/formatters.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/utils/text.ts" "<working_dir>/src/utils/text.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/utils/choices.ts" "<working_dir>/src/utils/choices.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/utils/dataverse.ts" "<working_dir>/src/utils/dataverse.ts"
cp "${CLAUDE_SKILL_DIR}/../../shared/samples/src/tokens/index.ts" "<working_dir>/src/tokens/index.ts"

Fix 8 — Thread the project's tamaguiConfig into the host provider (required so screens render under brand tokens, not upstream defaults)

The template ships PowerAppsProvider (composed-tree API, v0.2.0+). Fix 8 adds tamaguiConfig, defaultTheme, theme, and darkTheme props so screens render under brand tokens. Do NOT add an outer <TamaguiProvider> — PowerAppsProvider composes it internally and duplicating triggers "useTheme must be used within a TamaguiProvider" warnings on hot reload.

Write app/_layout.tsx (run AFTER npm install):

import { Slot } from 'expo-router';
import { StatusBar } from 'expo-status-bar';
import { useColorScheme } from 'react-native';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
import { PowerAppsProvider, lightTheme, darkTheme } from 'power-apps-native-host';
import type { ThemeTokens } from 'power-apps-native-host';

import authConfig from '../auth.config.json';
// @ts-ignore - power.config.json is auto-generated at build time
import powerConfig from '../power.config.json';
// @ts-ignore - connectorSchemas is auto-generated at build time
import { schemaMap } from '../src/generated/connectorSchemas';
import tamaguiConfig from '../tamagui.config';

// lightTheme / darkTheme are the built-in defaults from power-apps-native-host.
// When brand/tokens.ts exists, the Brand-token wiring block (Step 9b) replaces
// these props with brand-derived ThemeTokens objects instead.

export default function RootLayout() {
  const colorScheme = useColorScheme();
  return (
    <SafeAreaProvider>
      <PowerAppsProvider
        msalConfig={authConfig.msal}
        powerConfig={powerConfig}
        schemaMap={schemaMap}
        tamaguiConfig={tamaguiConfig}
        defaultTheme={colorScheme === 'dark' ? 'dark' : 'light'}
        theme={lightTheme}
        darkTheme={darkTheme}
      >
        <StatusBar style="auto" />
        <SafeAreaView edges={['top', 'bottom']} style={{ flex: 1 }}>
          <Slot />
        </SafeAreaView>
      </PowerAppsProvider>
    </SafeAreaProvider>
  );
}

Key points:

• Do NOT remove the two // @ts-ignore lines. They keep tsc green pre-npx power-apps init.
• Do NOT add an outer <TamaguiProvider> — PowerAppsProvider composes it internally.
• SafeAreaProvider wraps the tree so child screens can call useSafeAreaInsets() without a context error. SafeAreaView around <Slot /> keeps content out of the status-bar / home-indicator areas — required by validate-screen-quality.js.
• tamaguiConfig is imported from '../tamagui.config' (the default export of tamagui.config.ts at project root).
• defaultTheme flips between light/dark via useColorScheme(). /design-system --add-dark-mode later wires per-token dark variants.

Write the file directly when applying this fix.

Fix 4 — Path aliases in tsconfig.json (idempotent JSON merge)

The upstream template's tsconfig.json only ships paths polyfills for react-native, expo-auth-session, expo-secure-store, expo-web-browser — it does NOT define the @/components, @/hooks, @/utils, @/tokens aliases that screens (and the helpers Fix 7 just copied) import from. Without this fix, every import { lookupName, formattedValue, newId } from '@/utils' at screen-build time fails to resolve at both tsc --noEmit and Metro bundle time. Run this merge script in <working_dir>:

node -e '
  const fs = require("fs");
  const file = "tsconfig.json";
  const json = JSON.parse(fs.readFileSync(file, "utf8"));
  json.compilerOptions = json.compilerOptions || {};
  json.compilerOptions.baseUrl = json.compilerOptions.baseUrl || ".";
  json.compilerOptions.paths = json.compilerOptions.paths || {};
  const aliases = {
    "@/components": ["src/components"],
    "@/hooks":      ["src/hooks"],
    "@/utils":      ["src/utils"],
    "@/tokens":     ["src/tokens"],
    "@/generated":  ["src/generated"],
    "@/native":     ["src/native"],
  };
  for (const [k, v] of Object.entries(aliases)) json.compilerOptions.paths[k] = v;
  fs.writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
'

Key points:

• Idempotent. Re-running the script (e.g. on /create-mobile-app resume) overwrites the six alias keys with the same values — it does NOT touch react-native, expo-auth-session, expo-secure-store, expo-web-browser, or any other existing paths entries.
• Six aliases, not four. @/generated and @/native are pre-wired so npx power-apps add-data-source output (src/generated/services/...) and /add-native output (src/native/camera.ts, etc.) can be imported via the alias too. Costs nothing now and avoids a second tsconfig patch later.
• baseUrl: "." is preserved if already set (the template ships it). The merge script defaults it to "." only if missing.
• Metro auto-resolves paths defined in tsconfig.json for any project running expo-based bundling, so this single edit covers both the type checker AND the bundler. No babel.config.js plugin needed.

<Gradient> (used by components/index.tsx) requires expo-linear-gradient. Assume the upstream template ships it — do NOT edit package.json to add it. If npm install (Step 6.5) later reveals the dep is missing, STOP and ask the user to wait for the next template release; do not work around by adding the dep here (same lockdown rule as /add-native).

Do not run npm install inside Step 5 — in template-only mode dependencies must already be installed before the skill starts.

Install note (current template): The template does not read power.config.json during npm install. The Step 6 → Step 6.5 ordering is kept for predictable checkpoints, but do not run npm run generate-schemas during initial scaffold.

Step 6 — Initialize

Print before starting:

"→ [Step 6/13] Running npx power-apps init to write power.config.json for environment . ~15–30 seconds."

cd <working_dir>
npx power-apps init --display-name '<displayName>' --environment-id <environment-id> --non-interactive

Verify power.config.json was created and environmentId matches Step 4. If npx power-apps init fails, report the exact error and STOP — do not proceed.

Step 6.5 — Verify dependencies

This step verifies dependencies only. The user must have run npm install before invoking the skill.

[ -d "<working_dir>/node_modules/expo" ] && echo "✓ node_modules present" || echo "✗ missing — run npm install in the template folder and rerun"

If node_modules/expo is missing, STOP. Tell the user to run npm install in the template folder. Do not provision ADO tokens or run npm install from this skill.

Step 6.5b — Ensure SafeAreaProvider wraps the root layout (always runs, idempotent)

Why this step exists. This step idempotently ensures safe-area context is present in the root layout so screens do not render under system bars.

Print before starting:

"→ [Step 6.5b/13] Verifying SafeAreaProvider wraps the root layout (idempotent — usually a no-op)…"

cd <working_dir>

if [ -f app/_layout.tsx ] && ! grep -q 'SafeAreaProvider' app/_layout.tsx; then
  echo "→ [6.5b] Patching app/_layout.tsx to add SafeAreaProvider + SafeAreaView"
  node -e '
    const fs = require("fs");
    const FILE = "app/_layout.tsx";
    let src = fs.readFileSync(FILE, "utf8");
    // 1. Add the import if missing — splice in right after the react-native
    //    import; fallback is prepend after the first import line.
    if (!/from\s*["\047]react-native-safe-area-context["\047]/.test(src)) {
      const importLine = "import { SafeAreaProvider, SafeAreaView } from \"react-native-safe-area-context\";\n";
      if (/^import\s*\{[^}]*\}\s*from\s*["\047]react-native["\047];?/m.test(src)) {
        src = src.replace(/(^import\s*\{[^}]*\}\s*from\s*["\047]react-native["\047];?\n)/m, "$1" + importLine);
      } else {
        src = src.replace(/(^import[^\n]*\n)/m, "$1" + importLine);
      }
    }
    // 2. Wrap the outermost <PowerAppsProvider> ... </PowerAppsProvider> with
    //    <SafeAreaProvider> AND wrap the inner <Slot /> with <SafeAreaView>.
    src = src.replace(
      /<PowerAppsProvider([\s\S]*?)>([\s\S]*?)<\/PowerAppsProvider>/,
      "<SafeAreaProvider>\n      <PowerAppsProvider$1>$2</PowerAppsProvider>\n    </SafeAreaProvider>"
    );
    if (!/<SafeAreaView/.test(src)) {
      src = src.replace(
        /<Slot\s*\/>/,
        "<SafeAreaView edges={[\"top\", \"bottom\"]} style={{ flex: 1 }}>\n          <Slot />\n        </SafeAreaView>"
      );
    }
    fs.writeFileSync(FILE, src);
    console.log("  ✓ app/_layout.tsx wrapped with SafeAreaProvider + SafeAreaView");
  ' || { echo "SafeArea patch of app/_layout.tsx failed — see error above"; exit 19; }
elif [ ! -f app/_layout.tsx ]; then
  echo "  ↷ app/_layout.tsx does not exist yet, skipping patch"
else
  echo "  ↷ SafeAreaProvider already present, skipping"
fi

echo "✓ [Step 6.5b] SafeAreaProvider verified"

If the patch fails: the node script exits with an error. The most common cause is an unusual _layout.tsx shape (custom rewrite). Fix manually by importing SafeAreaProvider + SafeAreaView from react-native-safe-area-context, wrapping the outermost provider with <SafeAreaProvider>, and wrapping the inner <Slot /> with <SafeAreaView edges={['top', 'bottom']} style={{ flex: 1 }}>.

Step 6.6 — Scaffold TypeScript gate

Print before starting:

"→ [Step 6.6/13] Running scaffold tsc smoke check (~10–30 seconds)."

With node_modules/ populated, run the scaffold TypeScript gate. Do not run npm run generate-schemas here just to produce an empty connectorSchemas.ts; the template is intentionally type-checkable before that file exists, and the script is already run after data-source changes and again before Step 12 starts the dev server.

npx tsc --noEmit

tsc must pass here. If it doesn't, the post-clone surgery in Step 5 (Fixes 1–7) is incomplete — do not proceed to data sources or screen builders. Re-read the Step 5 fixes against the current working dir contents and reapply any missed edit.

This is the Scaffold gate from the TypeScript Gate Policy. If it fails, capture the full error list once, batch-fix scaffold/template causes, and rerun this gate. Do not continue to Step 6.7 or any app-specific mutation until this gate is clean. If the only failure is a missing generated schema import, preserve the template @ts-ignore boundary rather than generating an empty schema artifact.

Step 6.7 — Seed the memory bank

cp "${CLAUDE_SKILL_DIR}/../../shared/memory-bank.md" "<working_dir>/memory-bank.md"

Fill in the Project facts and Power Platform context sections from Steps 2 and 4. From here on, every step appends to the relevant section of <working_dir>/memory-bank.md immediately after success — not at the end. This is what enables Step 0's resume on a future run.

Immediately after creating memory-bank.md, flush any queued planner concerns from DEFERRED_CONCERNS[] into ## Concerns (append-only). This flush is unconditional: if the queue is non-empty, write it now before continuing to Step 6.75.

Also persist the Visual Companion preference so re-runs (/edit-app, /preview-screens, future /design-system runs) honor it without re-asking. Append to the Project facts section:

visual_companion: <yes|no>   # set in Step 2b — controls whether browser previews open automatically

/preview-screens reads this flag when invoked from inside this project; if no, it prints the file path instead of opening. /edit-app reads it to decide whether to re-open _plan_preview.html after a re-plan. The flag is per-project and does not leak across apps.

Step 6.75 — Design system

Print before starting:

"→ [Step 6.75/13] Locking your design system — source of truth for every screen built next. Takes 5 sec to 3 min depending on path."

Skip this step if --no-design is in $ARGUMENTS — placeholder ## Design Direction: <deferred> block stays in the plan, screen-builders fall back to industry-inferred defaults from universal-patterns.md.

Otherwise, invoke /design-system (ships with this plugin):

Invoke skill: /design-system

Arguments:
  --working-dir <working_dir>

The skill detects orchestrator mode (CODE_APPS_NATIVE_ORCHESTRATING=1), collects brand inputs, presents the cost picker (a/b/c/d), runs the internal style picker, writes brand/design-system.md + brand/tokens.ts, renders brand/design-system.html, and returns with status.

Handle the return per the status protocol (AGENTS.md rule #10):

• DONE → continue to Step 7. Record brand_path, tokens_path, direction in memory-bank.
• DONE_WITH_CONCERNS → surface concerns, ask user, continue.
• NEEDS_CONTEXT → surface question, re-invoke with answer.
• BLOCKED → surface error, STOP.

If the user picked path (c) Skip in the cost picker, the skill returns immediately with DONE and no brand/ files. Screen-builders fall back to ## Design Direction — same as today's behavior. But the user still needs a visual preview before code is written — fall through to the "Skip path preview" block below.

After /design-system returns DONE — two branches:

Branch A — brand/ files exist (user picked path a, b, or d)

This is the FIRST and ONLY HTML preview the user sees in the new flow — Gate 4 was a structural-only review (markdown screen-graph, no HTML). /design-system owns rendering of _plan_preview.html at its Sub-step 6.5 using the locked brand tokens. No re-spawn from the orchestrator is needed; the preview is fresh when the skill returns.

Branch B — Skip path preview (user picked path c — no brand/ files)

The user skipped the design system but still deserves to see their screens before code is written. Render a preview with Field/Ops defaults:

1. Print:

   "→ Design system skipped — rendering screen preview with Field/Ops defaults so you can validate the layout before code is written."

2. Render _plan_preview.html — read the screen specs from native-app-plan.md ## Screens section and render key screens (one List + one Form + one Detail, first match per archetype) using the tamagui-html-mapping.md reference and industry-inferred defaults from ## Design Direction. Write to <working_dir>/_plan_preview.html.

3. Open in browser (if <visual_companion> = yes):

   open "<working_dir>/_plan_preview.html" 2>/dev/null \
     || xdg-open "<working_dir>/_plan_preview.html" 2>/dev/null \
     || powershell.exe -NoProfile -Command "Start-Process '<working_dir>\_plan_preview.html'" 2>/dev/null \
     || true
   

4. Auto-continue — no prompt. The user already approved Gates 1–3 via plan-mode and just looked at the preview. A fourth confirmation here adds friction without adding decision power. Print one line and proceed:

→ Preview rendered with default styling. Continuing to Step 7. (Interrupt and re-run /design-system or /edit-app to revise.)

This ensures every path through the flow gets at least one visual preview before screen-builders write code.

Why this matters: under the OLD two-preview flow, the user saw screens at Gate 4 with default Tamagui colors, mentally committed, then the brand re-rendered later — confusing visual whiplash plus ~3–5 min of wasted token spend on the Gate 4 HTML. Under the NEW flow, Gate 4 is a markdown screen-graph (structural only), and the user only ever sees one HTML preview — at Step 6.75, with the locked brand applied. Single visual decision point, no waste.

Step 6.85 — Offline profile (always asked)

Print before starting:

"→ [Step 6.85/13] Asking whether to set up an offline profile…"

Mobile Offline Profiles let users continue working when their device is disconnected — Dataverse syncs queued changes when connectivity returns. This question must be asked on every run of /create-mobile-app — do NOT skip it based on the initial prompt's wording, the feature picker checkboxes, the requirements brief content, or any keyword heuristic. The user's intent for offline support is not reliably inferrable from any earlier step; the only authoritative signal is an explicit answer here. The plugin owns the setup via /setup-offline-profile.

Pre-conditions — only TWO branches skip this question, both with the explicit print line shown:

Condition	Action
App uses zero Dataverse tables (connectors-only — no .datamodel-manifest.json)	Skip — offline profiles are Dataverse-only. Print: ↷ Step 6.85 skipped — no Dataverse tables in this app. Continue to Step 7.
memory-bank.md ## Offline profile already has status: done OR status: not-applicable from a prior run	Skip — answered previously. Print: ↷ Step 6.85 skipped — offline profile already <done|not-applicable> from a prior run. Continue to Step 7.
Anything else (default — including "user didn't say 'offline' anywhere")	Ask the question below.

Important — do NOT add other skip conditions. Earlier versions of this skill had an "auto-detect / keyword scan" preamble (offline · field · remote · ...) that varied the question default based on whether the initial prompt mentioned offline-indicator keywords. That heuristic was removed because it caused the orchestrator to skip the question entirely when no keywords matched, leaving users with a stale or missing profile on the next sync. The question is now unconditional for any Dataverse-backed app that hasn't already answered.

Ask one AskUserQuestion — phrased neutrally, no implication that the user "should" answer Yes or No based on app type:

Question header: Offline support

Question body: "Mobile Offline Profiles let users continue working when their device is disconnected — Dataverse syncs queued changes when connectivity returns. Set one up now?"

Options (default = Yes):

• Yes — create profile now (recommended) — invokes /setup-offline-profile, walks the 3-gate flow, then continues to Step 7
• Skip — I'll add it later via /setup-offline-profile — continues to Step 7 with no profile (memory-bank status stays unset so the question fires again on the next /create-mobile-app run against this dir)
• Skip — this app doesn't need offline support — continues to Step 7; sets memory-bank.md ## Offline profile status: not-applicable so future re-runs don't re-ask

If the user picks Yes, invoke /setup-offline-profile as a sub-skill. It reads the same .datamodel-manifest.json you just wrote (Step 6 /add-dataverse's Step 6d output) — no need to pass arguments. The sub-skill returns DONE / DONE_WITH_CONCERNS: / BLOCKED: per the agent return-status protocol. On BLOCKED:, propagate up. On DONE_WITH_CONCERNS:, surface concerns to the user inline, then continue.

State transfer: /setup-offline-profile updates memory-bank.md ## Offline profile and writes offline-profile.json to the project root. Step 13 (final summary) reads these for the wrap-up summary.

Hooked into /add-dataverse: Step 6 (just before this step) sets IsAvailableOffline=true + ChangeTrackingEnabled=true on every new custom table (see skills/add-dataverse/SKILL.md Step 5b body skeleton). That means /setup-offline-profile Gate 1 will be a no-op pass-through for fresh scaffolds — saving the user one approval click.

Step 7 — Auth config

Print before starting:

"→ [Step 7/13] Configuring app authentication (Entra ID app registration)…"

The template ships auth.config.json with blank msal.clientId and msal.tenantId. There are no baked-in registration IDs to reuse. Always use the selected Power Platform environment tenant resolved earlier in the flow, then ask the user how they want to provide the Entra app registration client ID.

auth.config.json may also contain a non-secret sibling environment object written by scripts/resolve-environment.js:

{
  "msal": { "clientId": "...", "tenantId": "..." },
  "environment": {
    "environmentId": "<guid>",
    "environmentUrl": "https://orgXXX.crm.dynamics.com",
    "tenantId": "<guid>",
    "cachedAt": "<iso timestamp>"
  }
}

Keep this block when editing auth.config.json. It lets later skills avoid re-running the environment-specific Power Platform API. Do not store tokens, secrets, or current-user Dataverse identity fields there.

7.1 Resolve selected Power Platform tenant

Use the environment selected in Step 4. Prefer $ACTIVE_TENANT_ID, then .resolved-environment.json, then the cached auth.config.json.environment.tenantId. Do not use the old msal.tenantId as an authority source; it may be blank or stale from a previous registration.

TENANT_ID="$ACTIVE_TENANT_ID"
if [ -z "$TENANT_ID" ]; then
  TENANT_ID=$(node -e "const j=require('./.resolved-environment.json'); console.log(j.tenantId || '')" 2>/dev/null || true)
fi
if [ -z "$TENANT_ID" ]; then
  TENANT_ID=$(node -e "const j=require('./auth.config.json'); console.log((j.environment && j.environment.tenantId) || '')" 2>/dev/null || true)
fi
echo "$TENANT_ID"

If TENANT_ID is empty, rerun scripts/resolve-environment.js using the environment ID in power.config.json:

ENV_ID=$(node -e "console.log(require('./power.config.json').environmentId || '')")
node "${PLUGIN_ROOT}/scripts/resolve-environment.js" "$ENV_ID" > .resolved-environment.json
TENANT_ID=$(node -e "const j=require('./.resolved-environment.json'); console.log(j.tenantId || '')")

If TENANT_ID is still empty, STOP and ask the user to fix environment resolution before continuing. Do not guess the tenant and do not copy msal.tenantId from auth.config.json.

7.2 Choose app registration path

Ask one question, using the resolved tenant:

"This app needs an Entra ID app registration in tenant <tenant-guid> to sign in.

Choose one: (a) Paste an existing app registration client ID (b) Create a new app registration from the Power Apps Wrap page, then paste its client ID (c) Skip for now — configure auth later"

Do not default to any option silently. The user must choose because app registration ownership varies by tenant/admin role.

• (a) Paste existing — run the client-ID write path in 7.3.
• (b) Create new manually — print the portal URL and checklist in 7.4, then ask for the client ID and run 7.3. If the user cannot finish creation, allow skip and follow 7.5.
• (c) Skip — run the skip path in 7.5.

7.3 Write client ID into auth.config.json

Ask:

"Paste the Entra ID app registration client ID for tenant <tenant-guid> (GUID format), or type skip to configure auth later:"

If the user types skip, run 7.5. Otherwise validate UUID format. Write auth.config.json using Edit:

• Replace msal.clientId with the user's value
• Replace msal.tenantId with <tenant-guid> from 7.1
• Preserve the existing top-level environment block if present. If it is missing but .resolved-environment.json exists, add that JSON as top-level environment.

Do not create or modify the registration from this skill. The user owns it. Just wire the IDs into auth.config.json.

Print:

"→ Wired app registration into auth.config.json. Client ID: <id> Tenant: <tenant-guid>"

Jump to Step 8.

7.4 Create a new app registration manually

Resolve the selected Power Platform environment ID from $ACTIVE_ENV_ID, then power.config.json. Print the public Power Apps Wrap URL:

"Open the Power Apps Wrap app-registration page for the selected environment: https://make.powerapps.com/environments//wraps#create-app-registration

Create/register the app, then copy the Application (client) ID and paste it here. If you cannot create it now, type skip and run /set-app-registration-native later."

Tell the user the registration must be created/configured from the Power Apps Wrap page for the selected environment.

After the user creates the registration, run 7.3 to capture and write the client ID.

7.5 Skip auth for later

Write auth.config.json using Edit:

• Set msal.tenantId to <tenant-guid> from 7.1
• Leave msal.clientId as ""
• Preserve or add the top-level environment block from .resolved-environment.json if available

Print: