create-mobile-app

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` - if it outputs a message, show it to the user before proceeding. **📋 Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/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. For every child skill handoff, pass the invocation-scoped [app-edit-routing.md](../../shared/references/app-edit-routing.md) context: `MOBILE_APP_ORCHESTRATING=1`, `orchestrator: create-mobile-app`, the absolute `working_dir`, current `phase`, and the exact approved scope/answers for implementation. Forward it through routers and native helpers; do not persist it or rely on an earlier shell export. The plan exists before the app is fully built, so children must use this context rather than mistake creation for a standalone edit. Design/configuration children still own any approval explicitly delegated to their phase; this marker never skips those gates. ## Workflow Intent and creation-state checks → prerequisites → requirements (iOS + Android fixed) → rough plan preview → Gate 1 architecture (native capabilities, connectors, then data platform) → Gate 2 Dataverse model when selected → Gates 3 and 4 screen graph/specifications → environment and template preparation → app initialization → design system → conditional Dataverse materialization and sample data → Mobile Offline Profile offer for Dataverse apps → native capabilities and connectors → navigation and screens → validation, preview, and summary. --- ## Fresh-template working-directory mode This skill assumes the user already has a **fresh** `microsoft/power-platform-skills/plugins/mobile-apps/template#main` 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 for creation.** If the working directory is not a fresh template, STOP creation and follow the state-specific routing below. Do not send an existing-app edit request to a new folder. Missing generated markers alone do not prove freshness: if the template is customized or its state is unclear, ask before proceeding. Only a request for a new app requires a fresh template folder. Resolve the original request before classifying project state. Apply this state-routing table once in Step 0, in the order below; file markers are supporting evidence, not user intent or approval. | State | Detection | Action | |---|---|---| | Creation continuation | Explicit creation-continuation intent or a valid current create handoff for this app, not a request to edit an existing app | Use Step 0's continuation path. Require matching unfinished creation progress and confirm the next phase before continuing; missing or conflicting progress requires clarification, not fresh scaffolding. | | Already-created app | Existing-app intent or confirmed app customizations/materialized state, even when generated markers are missing. `memory-bank.md`, `.datamodel-manifest.json`, and `src/generated/services/*.ts` can corroborate state, but do not select creation resume | STOP creation: never re-scaffold it. If the request changes this app, preserve the original request and execute the shared existing-app entry routing; invoke `/edit-app` only after **Full app integration**. If the user wants a separate new app, ask for a fresh template folder. | | Fresh template | Confirmed new-app intent and a confirmed uncustomized starter; `package.json`, `app.config.js`, `auth.config.json`, and `tamagui.config.ts` exist; `node_modules/expo` exists; no materialized app bindings, `memory-bank.md`, `.datamodel-manifest.json`, or generated Dataverse services. An approved creation plan and its planning artifacts are allowed | Proceed to Step 1 only when every condition is satisfied. Missing generated markers alone do not establish freshness. | | Template not installed | Confirmed new-app intent and a confirmed uncustomized starter with the required template files, 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. | | Not template | Confirmed new-app intent in a new/unsupported directory, after excluding existing-app work and creation continuation | STOP: ask user to materialize `microsoft/power-platform-skills/plugins/mobile-apps/template#main` into a new or empty folder with `degit` and run `npm install`; never overwrite existing work. | | Unclear state or intent | New-app versus edit intent, customization, or creation progress cannot be established | Ask before selecting a workflow. Preserve the directory, plan, and history; do not default to fresh creation or resume. | An approved `native-app-plan.md` alone is not a created-app marker. Creation writes it before template preparation, and `assertFreshTemplate` intentionally allows it. A plan alone also does not identify a safe resume phase: use current caller context and saved creation progress, or ask. Do not treat an unrelated or stale plan as approved for this request. `/create-mobile-app` creates from a confirmed fresh starter or continues an explicitly requested unfinished creation. It does not adopt, repair, overwrite, or resume a completed app just because a bank or plan exists. An already-created app is a routing boundary, not a reason to discard the user's edit request. Do not merely suggest `/edit-app` or ask the user to repeat the request. For a current-app feature request, execute [app-edit-routing.md](../../shared/references/app-edit-routing.md), then invoke `/edit-app` with the original request, absolute `working_dir`, and `entry_choice: full-integration` only when that choice is approved. Reported problems still route to `/debug-app`; dependency/template upgrades route to `/check-updates`. --- ## 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, `pa app 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`. --- ## Build documentation protocol This protocol applies after Step 0 selects fresh creation or an approved creation continuation. Routing an existing-app request elsewhere, asking for unclear intent, or declining creation does not create, reopen, or reset the creation plan or change its phase status. The run also writes a plan the user can read while it happens and keep afterwards: `<working_dir>/docs/create-app-plan.html`, rendered by [`scripts/app-docs.js`](${PLUGIN_ROOT}/scripts/app-docs.js) in the same Fluent format the Power Pages `/create-site` plan uses. It is the record of *why* the app looks the way it does, so a teammate opening the repo months later can see the environment, the approved data model, and the screen plan without re-reading a transcript. ```bash node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' <command> ``` | Command | Use | |---|---| | `init --json-file <path>` | Once, at Step 2b, with `{"appName","dataPlatform"}`. Safe to re-run: a resume keeps recorded progress. The display name is user text, so it travels in the file, never as an argument. | | `step --id <phase> --status <pending\|active\|done\|skipped\|failed> [--note "<text>"]` | At every phase boundary. Marking a phase `active` closes any previous one. | | `set --section <name> --json '<object>'` or `--json-file <path>` | When a decision is made. Merges, so a later step can add to a section. | | `step --id <phase> --status failed --note "<what stopped it>"` | Before surfacing any unrecoverable STOP. Best-effort like the rest: if it fails, still stop. | | `phone --stage building\|screens\|qr` | Moves the plan's phone through its three stages: the building animation, the screen carousel at Step 6.75, and the Metro QR at Step 12. | **Open the plan in the user's browser as soon as `init` creates it**, with the host's file opener or `open` / `xdg-open` / `cmd /c start ""` on the quoted path. A plan the user never sees is a plan that only ever existed as terminal text, and terminal text scrolls away during a long run. Opening it once is enough: the page reloads itself as each phase lands. **Phases** (`--id`): `requirements`, `architecture`, `data-model`, `screen-plan`, `scaffold`, `design`, `auth`, `dataverse`, `capabilities`, `screens`, `run`. Any other id is rejected by name. **Write each gated section into the plan *before* asking for approval**, with `--state proposed`, then flip it to `--state approved` once the user says yes. The plan is already open in their browser, so a rendered ER diagram or screen graph is what they answer the gate against. Recording the decision afterwards means approving from terminal text and seeing the picture only once it is too late to change it. Step 3's Architecture gate lists every gate with its phase and section. The Gate 2 calls below are the pattern each one follows: ```bash DOCS="${PLUGIN_ROOT}/scripts/app-docs.js" # 1. propose - the tab shows "Proposed - review this, then answer the prompt in your terminal" node "$DOCS" --working-dir '<working_dir>' set --section dataModel --json-file <tmp>/data-model.json --state proposed node "$DOCS" --working-dir '<working_dir>' step --id data-model --status active --note "Gate 2 — awaiting your approval" # 2. point the user at that tab, then ask the gate question # 3. on approval node "$DOCS" --working-dir '<working_dir>' set --section dataModel --json-file <tmp>/data-model.json --state approved node "$DOCS" --working-dir '<working_dir>' step --id data-model --status done --note "Gate 2 — approved" ``` Pass a fresh `--note` when you close a gate. A note belongs to the status it was written with, so changing status without one clears it rather than leaving "awaiting your approval" under a step the user has already approved. If the user asks for changes, rewrite the section with `--state proposed` again and re-ask. The page reloads itself, so they see the revision without touching anything. **Record each other section as soon as it is known** — not in a batch at the end, or an abort leaves a plan that explains nothing: | Section | Written at | Contents | |---|---|---| | `environment` | Step 1, confirmed Step 4 | `displayName`, `environmentId`, `environmentUrl`, `tenantId`, `publisherPrefix` | | `requirements` | Steps 2 and 2b | `appName`, `slug`, `platforms`, `aesthetic`, `industry`, `brief`, `features[]` | | `architecture` | Gate 1 | `dataPlatform`, `nativeCapabilities[]` and `connectors[]` as `{ name, reason }` — a bare name cannot be approved or rejected, the reason is the decision | | `dataModel` | Gate 2 | `connectorOnly` when there are no tables; otherwise `tables[]` with `logicalName`, `displayName`, `status` (`new`/`reused`/`modified`, or the plan's `create`/`reuse`/`extend`), `purpose` (what it holds), **`reason` (why it is created, reused or extended)**, `columns[]` (`logicalName`, `displayName`, `type`, `key: PK\|FK`), `relationships[]` (`relatedTable`, `name`, `cardinality`) | | `offline` | Gate 2 | `enabled`, `mode`, `tables[]`, `rationale` | | `screens` | Gates 3 and 4 | `navigation`, `list[]` with `name`, `route`, `purpose`, `data`, `capabilities[]` | | `design` | Step 6.75 | `direction`, `headingFont`, `bodyFont`, `darkMode`, `palette[]` (`name`, `value` as `#rrggbb`). Use the real family names from [`typography-and-tone.md`](${PLUGIN_ROOT}/shared/references/typography-and-tone.md) (`Inter`, `JetBrains Mono`, …) — the plan renders each name in the typeface it names, so a label that is not a real family shows as the fallback. | | `auth` | Step 7 | `status` | | `trust` | Step 10, after capabilities and connectors are wired | `permissions[]` (`name`, `status` as one of the acquisition patterns below, **`detail`: when access is requested and why**), `handles[]`, `notCollected[]`, `battery[]` (`name`, `detail`) | The ER diagram is **built from `dataModel.tables`**, so populate the structured fields rather than only a Mermaid string — that is what makes the diagram, the column tables, and the new/reused/extended colouring agree with each other. **Every reuse, create and extend decision needs a `reason`.** "Reusing `account`" is not reviewable; "Reusing `account` — sites are already maintained there by the service desk, and a second Site table would drift" is. Write the reason the architect actually used, including what was rejected, since that is what the user is being asked to approve at Gate 2. **Use `--json-file` for anything the user wrote.** Size is not the test — an app called `Dave's Rounds` is enough. A value interpolated into a single-quoted shell argument ends that quoting at the first apostrophe, which at best corrupts the JSON and at worst leaves whatever follows to the shell. App names, briefs, feature lists, table reasons and design directions are all user-authored, so they are written to a file with the `Write` tool and passed by path. `--json` inline is for values this skill controls end to end, such as a fixed status string. **Every one of these calls is best-effort.** If `app-docs.js` fails, say nothing and carry on: the documentation must never gate, retry, or fail a build. **Mark the active creation phase `failed` before stopping on a creation error.** Step 0 routing exits leave existing creation history untouched. Once creation is underway, a STOP is a terminal state the user has to act on, and the plan is probably still open in their browser. Without this the last phase stays `active`, so the page keeps reloading and keeps reporting work in progress on a run that ended. A failed phase settles the page, so the final thing it shows names what stopped. **No argument switches this protocol off.** `--no-design` suppresses design previews and `--no-preview` does not exist (Step 2c). The plan is how an abandoned or failed run explains itself, so it is written on every creation path after Step 0's routing decision. --- ### Step 0 — Intent routing + creation-state gate **Telemetry checkpoint: `validate_fresh_template`** Before project reads or commands, bind the absolute `working_dir` through [app-working-directory.md](../../shared/references/app-working-directory.md). Apply the state-routing table above once. Classify the original request before considering a creation resume or testing freshness; do not derive the requested operation from the presence or absence of `memory-bank.md`. **Existing-app changes leave this skill before resume handling.** Follow the table's existing-app handoff, preserving the original request and root, then return without entering Step 1 or modifying creation progress. Reported problems and dependency/template upgrades retain their matching workflows. If intent or customization is unclear, ask and wait; do not offer a creation resume merely because a bank exists. Only a confirmed **Fresh template** or explicit **Creation continuation** enters the creation workflow below. All other table outcomes stop or hand off without re-scaffolding, overwriting history, or running template preparation. #### Fresh run Require every condition in the Fresh-template row, including confirmed new-app intent and an uncustomized starter. The template/dependency failure rows apply only after that intent is established. An approved plan from the current creation is allowed; preparation stays in Step 5, not this read-only entry gate. Resolve the CLI below, then continue to Step 1. #### Creation continuation For an explicit request to continue this app's unfinished creation, inspect the matching `memory-bank.md` when present, `docs/.run-plan.json` when present, the approved creation plan, and any valid current create caller context. Establish the unfinished creation phase and corroborate it against current app artifacts. Do not infer the next phase from arbitrary completed entries belonging to edits, deployment, or another workflow. - **Missing or conflicting progress** — ask which creation phase is being continued or ask to restore its records, then stop. Do not guess a phase, restart creation, or classify the app as fresh. - **Completed creation** — report that there is no unfinished creation to resume. Clarify whether the user wants an app edit or a separate new app and use the table's matching route. - **Corrupt records** — report the error and ask to repair/restore them. Do not delete or overwrite history to make the directory pass a freshness check. - **Verified unfinished phase** — show the phase, remaining scope, and target app, then obtain continuation approval unless that exact continuation already has current approval. Reuse only decisions approved for the same current scope; pending or changed decisions keep their owning approval gates. Pre-initialization creation may have an approved plan and saved planning progress without a memory bank. It stays on this continuation path when the phase can be established; the plan's presence does not redirect it to editing. For a post-initialization continuation, resume the verified phase directly; do not rerun the fresh preparation or `pa app init` over the materialized app. **Reopen the build plan only after continuation approval.** When `<working_dir>/docs/create-app-plan.html` exists, reopen it. Inspect the existing plan with the read-only `node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' show` command. If it reports a `failedPhase` matching the approved continuation, reopen that phase before continuing: ```bash