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. ## Workflow Resume/template 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.** 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 `microsoft/power-platform-skills/plugins/mobile-apps/template#main` 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 `microsoft/power-platform-skills/plugins/mobile-apps/template#main` 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, `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 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 phase `failed` before you stop.** Every STOP in this skill 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 path. --- ### Step 0 — Resume check + fresh-template gate **Telemetry checkpoint: `validate_fresh_template`** 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 '<name>' at `<dir>`. Steps 1–<N> already completed (last update <date>). 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. **Reopen the build plan on resume.** A resume skips Step 2b, where the plan is created and opened, so open `<working_dir>/docs/create-app-plan.html` in the browser yourself when it exists. If the earlier run stopped on a failure, the plan still says so and has stopped reloading. Run `node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir "<working_dir>" show`, and if it reports a `failedPhase`, reopen that phase before continuing: ```bash node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir "<working_dir>" step --id <failedPhase> --status active ``` - **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 `microsoft/power-platform-skills/plugins/mobile-apps/template#main` 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 `plugins/mobile-apps/template` template may contain placeholder `power.config.json` with an empty `environmentId`; Step 5 removes that placeholder immediately before Step 6 runs `pa app init`. **Resolve the Power Apps CLI** (fresh run or resume) before any CLI command — see [cli-binary.md](${PLUGIN_ROOT}/shared/cli-binary.md). Run every command as `$PA …` (`npx --no-install pa …`), never a bare `pa`; on `power-apps`-only projects, translate per its mapping tables. If `PA_KIND=none`, STOP and ask the user to run `npm install` in the template folder. Record the result in the memory bank's `CLI Binary` row once the bank exists (Step 6.7). ### Step 1 — Prerequisites **Telemetry checkpoint: `validate_development_toolchain`** 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 the Power Apps CLI (`$PA`): | What | Uses | Typical account | |---|---|---| | `npm install` private feed access | npm/Azure Artifacts auth configured outside this skill | Account with feed Reader access | | `pa app init`, Dataverse, deploy | Power Apps CLI 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 the Power Apps CLI. 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: ```bash 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 ```