app-builder

1. Derive a short kebab-case slug from $ARGUMENTS (e.g. "Project Tracker" → project-tracker).
2. Create the directory (mkdir -p <slug> on bash/PowerShell; mkdir <slug> on cmd, which has no -p and errors if it exists) and resolve its absolute path. It holds app-spec.json, model-app-plan.md, and workflow-log.md.

Follow references/authoring-flow.md step by step, running every prompt yourself via AskUserQuestion. In short:

Resolve the interaction mode once before the first authoring question:

node "${PLUGIN_ROOT}/scripts/resolve-interaction-mode.js" [--non-interactive]

POWER_PLATFORM_SKILLS_NONINTERACTIVE=1/true (or the equivalent --non-interactive invocation) means there is no user waiting for prompts. In that mode:

• do not call AskUserQuestion, EnterPlanMode, or ExitPlanMode;
• use explicit requirements and supplied existing specs as authoritative, and use documented defaults only where the request leaves a non-destructive choice open;
• record each skipped gate as Unattended default: <question> → <answer> (<reason>) in workflow-log.md;
• treat the completed lint, preview, rendered design document, and build dry-run as the approved plan, then continue with the normal approved path;
• halt rather than guessing an ambiguous environment, app identity, or destructive structural edit.

Suppressing interaction never authorizes destructive work. An unattended existing-app apply still requires --allow-destructive wherever the build normally requires it; POWER_PLATFORM_SKILLS_NONINTERACTIVE only suppresses prompts.

Carry the resolved mode through subprocesses: when it is unattended, append --non-interactive to every build-model-app.js invocation (dry-run, data pre-build, recovery rerun, and full apply). Do not append --allow-destructive unless destructive authority was supplied independently.

1. Prereqs — node --version, pac help (> 2.10.0, the plugin's minimum).
2. Environment (PAC) — pac auth list. If exactly one / an active profile, confirm it (FYI), don't ask. If several and none active, ask which to use. If none, ask the user to pac auth create. Capture the org URL (pac org who).
3. Detect existing — pac model list-tables --search … (exact-match) and pac model list to find tables/apps already present; build around them.
4. Levelled authoring — first read the App Spec format so you author to the exact shape (do this once; don't go spelunking through scripts): references/app-spec-schema.md and the worked sample samples/app-spec.support-desk.json. That document covers everything an app always has. Additionally read references/app-spec-schema-advanced.md once your design calls for a conditional feature — business rules, a business process flow, command-bar buttons, web resources, global choices, classic dashboards, or roleGrants[]. Its pointer table is in the main schema, and the toolbox above tells you when to reach for each; read the detail only for the ones you are actually using, and never skip a capability just to avoid the read. Phase 1 is design-only: never emit page .tsx here. Each level is confirmed via AskUserQuestion before the next begins, and app-spec.json is persisted after each — full prompts in the playbook.
   • Level (a0) — personas & jobs-to-be-done (personas[]): before proposing any tables, ask who will use the app and what each needs to get done. Jobs drive everything that follows — a table exists because a job needs its data, a surface because a job needs to act on it. Deriving the data model first reliably misses surfaces. Privileges come later; capture the jobs now.
   • Level (a) — data model: entities/columns/relationships derived from those jobs; run the early data-model lint (catches e.g. the relationship-vs-lookup collision before forms are authored on top).
   • Descriptions are part of authoring, not a cleanup pass. Every table, column, view, chart, form, dashboard and business rule takes an optional description, and you should write one as you create the artifact — never as a backfill. A name says what a thing is called; a description says what it is for, and it is the only intent an app carries that an agent can read back later when it inspects an app it did not build. Describe the purpose, not the shape: "Severity 1-5; drives the escalation rule and the SLA clock", not "The priority column". (commands[] and Customer columns accept one but the SDK cannot write it — you'll get a warning; personas[] does not take one at all. See the schema reference for why.) The app itself takes two: app.description is the short tile text, and app.aiDescription is the routing description an orchestrator reads to choose between apps — who the app is for, what it covers and excludes, and how to tell it from a sibling app over the same tables. Write it whenever such a sibling exists or is planned.
   • Level (b) — artifacts + page-intents + design: enumerate every surface each job needs and classify it per the genpage-first policy above — record CRUD → form + view; anything else (overview/landing, dashboard, KPIs, analytics, guided/wizard flow, composite or comparison screen) → a page intent (source: { kind: "intent" }). State each classification out loud; if the app needs no pages, say so and why rather than silently omitting them. Then forms + views
     • charts + sample data and the optional design contract, mapping each job to its surfaces via jobs[].surfaces[]. No page .tsx here. dashboards[] only on explicit request.
   • Level (c) — access (personas[].jobs[].privileges[]): personas and jobs already exist from (a0) and the entities now exist, so only add the privileges each job needs — don't re-ask who the users are. The builder unions them into one role per persona and grants the app to it so it opens for that persona, not just sysadmins. Render the roles + per-entity access as a table in your chat reply (the user can't approve an access model they can't see — see the CRITICAL note above). If they want no roles, tell them jobs live in personas[] so dropping the roles drops the recorded jobs too; offer read-only privileges to keep the record. (Column-level security and access teams are not yet supported — see Notes & limits.)
   • Whole-app preview (design gate for Level (b)): node "${PLUGIN_ROOT}/scripts/preview-app.js" --spec @<working-dir>/app-spec.json renders data-model + sitemap + form wireframes + page-intents + design contract. Reproduce the ENTIRE rendered output verbatim in your chat reply, inside a fenced ``` code block — do NOT leave it in the (collapsed, invisible) tool output, and do NOT just summarize "the preview looks right" (see the CRITICAL note above). The user must be able to SEE each form, the sitemap, and the page intents they are approving. For a single form only: node "${PLUGIN_ROOT}/scripts/preview-form.js" --spec @<working-dir>/app-spec.json.
   • Don't pre-create tables/columns — the build does it idempotently.
5. Guardrail lint (hard gate) — run the full lint on the complete spec; errors block, warnings teach. If it blocks (or warns), paste the findings into your chat reply — tool output is collapsed and invisible to the user (see the CRITICAL note above), so the user can't fix what they can't see:
   Copy

   node "${PLUGIN_ROOT}/scripts/lint-app-spec.js" --spec @<working-dir>/app-spec.json --json

   This runs migration and validateAppSpec — the gates the build itself runs on load — plus the lintAppSpec authoring guardrails, which the builder does not run. It exits non-zero on errors. It validates under the plan profile (which allows not-yet-generated intent pages), matching Step 6's dry run.
6. Plan-mode approval (the single build approval) — present the plan including the build dry-run's phase-grouped plan (run build-model-app.js without --apply, using the plan profile that allows intent pages) inside EnterPlanMode, then ExitPlanMode to get the user's go-ahead. On approval, Phase 1.5 (generate-pages) runs first, then Phase 2 applies directly (no second dry-run/go-ahead). Render the design document — never hand-write it:
   Copy

   node "${PLUGIN_ROOT}/scripts/write-app-spec-doc.js" --spec @<working-dir>/app-spec.json --env <envUrl>

   It writes <working-dir>/model-app-plan.md (jobs → surfaces traceability, data model, every surface, navigation, access model, sample data) and prints { ok, docPath, bytes, warnings }. Surface those warnings — they name design gaps such as a job with no covering surface or an app with no generative pages. Tell the user where the document is; it's theirs to keep, and it's regenerable after any spec edit.

After plan-mode approval (before the full build):

1. Data pre-build — schema-only build so generate-types can resolve real column names:

   Copy

   node "${PLUGIN_ROOT}/scripts/build-model-app.js" \
     --env <envUrl> --spec @<working-dir>/app-spec.json --stage data --apply

   --stage data applies solution + data-model only — no --sample-data (rows are created once in the full build). Only --stage data is apply-safe; all other --stage selectors and legacy --from/--to/--only/--skip selectors are dry-run inspection only.

2. Types — generate Dataverse type bindings for the entities the pages read:

   Copy

   pac model genpage generate-types --data-sources "<entity1,entity2,…>" --output-file <working-dir>/RuntimeTypes.ts

   --data-sources is the union of every intent page's dataSources. Skip this step entirely when every intent page is mock-only. On Windows use forward slashes in the path.

3. Page plan (adapter) — the page worker's input contract is a plan document, not an App Spec, so project the spec into one. This also echoes the per-page dispatch parameters:

   Copy

   node "${PLUGIN_ROOT}/scripts/write-page-plan.js" \
     --spec @<working-dir>/app-spec.json --working-dir <working-dir> --env <envUrl> \
     --app "<app name>" --languages "<languages from the environment probe>"

   It writes <working-dir>/app-builder-page-plan.md and prints { ok, planPath, pages: [{ name, key, file, dataMode, intent }] }. Pass --languages through from the environment probe — omitting it silently defaults every plan to English-only and drops the localization pattern. The command fails (before writing) if the plan would name a sample that doesn't exist, or if a page a worker will write is not a safe target in the working directory — a link at its path, a folder that links outside the directory, or a page already there under another spelling — or if a link, a hard link or a folder is already at the plan's own path. Stop and fix what it names; do not dispatch any worker.

4. Generate — for each page from step 3 with intent: true, dispatch the headless genpage-page-builder worker via Task. Use its documented input contract verbatim — a missing field is why a page silently never becomes .tsx:

   You are the genpage-page-builder agent. Generate the [name from step 3] page.

   • Target file: [file from step 3 — already includes .tsx; do NOT append another]
   • Plan document: [absolute path to the app-builder-page-plan.md written in step 3]
   • Data mode: [dataMode from step 3 — dataverse or mock]
   • Connectors: none
   • Telemetry: disabled
   • RuntimeTypes: [absolute path to RuntimeTypes.ts] ← omit this line when Data mode is mock
   • Working directory: [absolute working-dir path]
   • Plugin root: ${PLUGIN_ROOT}

   Follow the instructions in your agent file. Write [file] and return your result when done.

   The plan's ## Environment carries Mode: app-builder and every page row carries a Key, so the worker emits "PAGEREF_<key>" for cross-page navigation (never a file-derived token — a downloaded page's codeFile is a path, not its identity). Custom nav ids go in data: — never recordId. Connectors: none and Telemetry: disabled are constants here: the App Spec has no connector-binding concept (so the projected plan always says No connector bindings.), and /app-builder never runs the Phase 4.7 custom-telemetry probe. Both are stated explicitly rather than omitted — the page-builder treats a missing line as the same fail-closed value, but an explicit line is what makes the dispatch contract checkable.

5. Validate + commit the transition (transactional) — never flip source by hand, and never flip pages one at a time as workers return. Run:

   Copy

   node "${PLUGIN_ROOT}/scripts/promote-intent-pages.js" \
     --spec @<working-dir>/app-spec.json --working-dir <working-dir>

   It checks every generated page (file written, structurally a module, PAGEREF_ tokens canonical and in exact parity with the spec's navigatesTo edges) and only then flips all of them intent → { kind: "tsx", codeFile } in a single atomic write. On any failure it exits 3 and leaves app-spec.json untouched, printing which page failed and why — regenerate just those pages and re-run. All-or-nothing on purpose: a half-flipped spec would claim a .tsx that was never written, and Phase 2's deploy profile fails fast on any remaining source.kind === "intent".

6. Proceed to Phase 2 (full idempotent build).

⚠️ The interactive author never runs inside a Task subagent. Only pure, headless code-gen workers are dispatched here — all user-facing prompts originate in the main loop.

Always use scripts/build-model-app.js. Never hand-write a builder. It's idempotent (skips existing solution/tables/columns/relationships — so new, existing, and mixed envs all just work), so you don't pre-create anything or special-case existing tables.

The build plan was already presented and approved in plan mode (Phase 1 Step 6 shows the engine's real dry-run plan), so on approval apply directly — one build approval, no second go-ahead. Add --verify so the build self-checks after applying (see Phase 3):

node "${PLUGIN_ROOT}/scripts/build-model-app.js" \
  --env <envUrl> --spec @<working-dir>/app-spec.json --apply --verify [--sample-data] [--publish]

Each step streams its status live ([n/total] ✓ created / ⊘ skipped / ✗ failed — <error>) and a closing ✓ build complete — X created, Y skipped, Z failed summary.

Keep the build's progress visible. A full build runs for several minutes. Let its output stream — do NOT pipe it through Select-Object -First/-Last N or Select-String head-limits, which buffer and hide progress until the run ends (and can truncate a still-running pipe). To capture the log use Tee-Object -FilePath <log> (no head-limit). The build also prints a ▸ live progress: line pointing at <workspace>/.maker-workspace/build-status.json — a snapshot (state, steps, lastPhase, lastLabel) overwritten every step. Read it (or tail build-log.jsonl) any time to report where a long build is, even if stdout is buffered.

(Reaching Phase 2 without a fresh plan-mode approval — resuming a failed build, or a quick edit re-run — do a dry-run first (drop --apply), paste the phase-grouped plan verbatim into your chat reply (tool output is collapsed — see the CRITICAL note above), and get a go-ahead before applying.)

Stage selector (--stage <data|ui|app|publish>) maps to its phase range. On --apply, ONLY --stage data is accepted (solution + data-model, no rows in run 1; run 2 is a full build). All other stages and the legacy --from/--to/--only/--skip selectors are dry-run inspection only — their phase ranges are not dependency-closed and are rejected on --apply.

Language (--language-code / --languageCode <lcid>) — you normally do not pass this. Data-model labels are stamped with the organization's own base language, read once per build. Pass it only to author labels in a different provisioned language, or if the build warns that it could not determine the base language and fell back to 1033.

If you pass an LCID the organization has not provisioned, the build now stops in the data-model phase, before any label is written, and lists the ones it does have. That check exists because Dataverse handles this inconsistently: table and choice labels are accepted (HTTP 204) and silently stored under the organization's base language, while DateTime and Memo columns are rejected with "The language code N is not a valid language for this organization". Without the check a build therefore creates the table with the wrong labels and then dies partway through the columns, phases away from the flag that caused it — which reads like an environment fault. List the provisioned set with node "${PLUGIN_ROOT}/scripts/dataverse-request.js" <envUrl> GET RetrieveProvisionedLanguages. The check is best-effort: if that read fails the build proceeds unchanged.

The App Spec field languageCode pins the same value across runs. It now covers the whole build: data-model labels, and form, dashboard and sitemap labels — the SDK serializers that used to hardcode 1033 take the authoring language as an option.

Narrate progress as it runs. Transient env errors (429 customization-lock, 503 SQL-timeout, a SQL deadlock, concurrent-op guards) are auto-retried with backoff on --apply (the build is idempotent, so a retry reuses what's already created). If the build still halts (BuildHalt) on an unrecoverable error, surface it and ask the user how to proceed via AskUserQuestion (adjust the spec / cancel), then re-run. Everything is scoped to a dedicated unmanaged solution; --publish gates the final bulk publish — edit/finalize paths still publish their one targeted artifact so the change takes effect (see Notes & limits).

Recovery from a failed or halted build: run the full build again. The build is idempotent — every phase re-uses what's already created and only fills the gaps. SDK metadata is persisted under <working-dir>/.maker-workspace/ (override with --workspace). There is no apply-safe --from <phase> shortcut; a full rerun is the correct and safe recovery path. One exception: an already-exists halt recurs on a rerun until that workspace directory is deleted — follow its message.

--apply --verify already reconciled the spec against what deployed (Phase 2) — the build appends a verify PASS / verify FAIL — N missing line and exits non-zero on a silent partial (an artifact created but not wired, or a phase that quietly produced nothing). To re-check later — e.g. after a Maker change, without rebuilding — run the standalone read-only verifier (entities/columns/views/charts/ forms and sitemap subareas + icons; exits non-zero and lists anything missing):

node "${PLUGIN_ROOT}/scripts/verify-model-app.js" --env <envUrl> --spec @<working-dir>/app-spec.json

Then open the app in the browser. Refine app-spec.json and re-run Phase 2 to iterate.

Teardown (cleanup). To remove everything an App Spec built — e.g. a live-verification probe or a failed build — run the classifier-safe teardown. It deletes only the artifacts the spec declares, in dependency order (app module → dashboards → command bars → forms → security roles → charts → views → reset enriched default views to drop parent lookups → relationships → AI row summaries → tables [children-first] → web resources (generated app icon + page manifest + declared) → global choices → solution). Forms/charts/views/relationships are deleted explicitly before tables (a table delete does not reliably cascade cross-references; it does remove the table's own columns). Security roles come after forms because a form assigned to a role names it inside its own formxml, which the platform counts as a dependency, and before relationships/tables because a role holding a table's privileges can block that table's delete. Command teardown removes the whole command bar for any entity the spec authored commands on. Teardown only deletes tables this build created — a system/standard table (account, contact, …) is auto-detected and skipped, and a reused custom table is skipped when its entity is flagged "existing": true, so pre-existing data survives. The same flag protects relationships and global choices — a download sets it on every one it recovers, so tearing down a downloaded spec never removes a lookup column from a retained table or deletes a shared option set. Dashboards are found by name, so teardown deletes only those the app's solution holds, never another app's namesake — and none when the spec has no real solution to ask (the Default a download may leave); it keeps the solution itself while any step failed, so a re-run can still tell, and keeps the page manifest while the generative-pages step failed, so a re-run still finds the pages the app authored. Dry-run by default; add --apply --allow-destructive to actually delete (--clear-workspace also prunes .maker-workspace/). --allow-destructive is required for teardown --apply — without it teardown refuses and touches nothing.

node "${PLUGIN_ROOT}/scripts/teardown-model-app.js" \
  --env <envUrl> --spec @<working-dir>/app-spec.json [--apply] [--allow-destructive] [--clear-workspace]

Safety flags (build + teardown). The apply path is fail-closed against destructive operations:

• --allow-destructive — authorize destructive operations. For build --apply: authorizes overwriting an existing app in unattended mode, and allows explicit-layout form-field removals or sitemap-target drops; also authorizes DETACHING a pages-removed page's nav subarea (the page record is left deployed — it is not deleted). For form and sitemap removals, the authority covers the removals the last refusal or approved run recorded; if live state would lose anything more, the apply halts, lists only the newly destructive removals, and records that new list for review. A field or sitemap target that appears during a run is kept or halted before push, never removed unseen. The record is consumed only after a full successful build that ran the removal phases and kept nothing; it is kept on failures, partial runs, changed-only runs, unreadable records, and failed discovery. For teardown --apply: required — all deletes are destructive by construction, so teardown without this flag halts before touching anything.
• Pages-phase safety HALTs. The build halts on identity or safety violations rather than proceeding with potentially wrong state. Surface the HALT reason and follow the recovery hint:
  • pages-identity-conflict — spec pageId and manifest disagree on a key, or a duplicate id spans two keys. Resolve the conflict manually (re-download or delete the manifest).
  • pages-manifest-corrupt — the manifest cannot be parsed (two keys map to the same id). Delete the manifest web resource and rebuild from scratch.
  • pages-removed — a live page was dropped from the spec. Re-add it, or pass --allow-destructive to detach it from the nav (the page record stays deployed; rebuild finalizes the sitemap).
  • pages-shared-across-apps — the page appears in another app's sitemap. Detach it in Maker. --allow-destructive does not bypass this halt.
  • pages-shared-check-failed / pages-existence-failed / pages-sitemap-read-failed — a prerequisite read failed; the build can't proceed safely. Retry on a transient error; check permissions on a persistent one.
• --non-interactive — suppress interactive prompts (for automation / CI). A non-interactive build that encounters an existing app fails instead of warning-and-proceeding, unless --allow-destructive is also set. Does not grant destructive authority on its own — only --allow-destructive does.
• POWER_PLATFORM_SKILLS_NONINTERACTIVE=1 (or true) — env-var equivalent of --non-interactive. Same semantics: suppresses prompts only, never authorizes destructive ops. Set this in CI job environments to avoid interactive-prompt hangs.
• In autopilot / eval mode (--non-interactive + --allow-destructive), preview-app.js is written to disk as the design artifact before plan execution; interactive consent gates are bypassed and the build is fail-closed against any destructive op not explicitly authorized.

The ai block in the App Spec controls four app-level features and per-table Copilot row summaries. All features are admin-gated: they are enabled only where the environment administrator has turned them on in Power Platform Admin Center (Environments → Settings → Product → Features). The ai-features build phase preflights each setting via the SDK (RetrieveSetting) and, for anything off, skips it with a warning — it never fails the build and cannot flip admin or tenant switches itself.

Preflight (standalone):

node "${PLUGIN_ROOT}/scripts/ai-preflight.js" --env <envUrl> [--app <uniqueName>]

Prints each feature's on/off status and the exact admin action required for anything that is off. Never fails.

App-level features (ai.appFeatures) — formFill (Copilot-assisted form fill), nlSearch (natural-language grid/view search), nlChart (NL chart / AI data visualization), m365 (M365 Copilot). All default to on except m365, which is left at its platform default; false writes an explicit Off for this app (each setting's values: references/app-spec-schema.md → ai).

Per-table row summaries (ai.summaries):

• default: "auto" — the skill auto-selects good-candidate tables (skips lookup-only / config / junction tables and the Dynamics 365-owned incident, lead, opportunity).
• default: "off" — summaries disabled unless a table opts in explicitly.
• Per-table overrides in summaries.tables: set enabled, a tailored instruction, and columns[] (the fields the summary reads). A { "enabled": false } entry opts a specific table out.

Prompt authoring guidelines (for instruction): write for meaningful insights — not field/value repetition; never include record GUIDs; pull in recent activity where relevant; use audience-appropriate tone; aim for an explicit output shape (a short paragraph).

Teardown removes the AI records created by the ai-features phase (summary config rows and published AI models) in addition to the standard artifacts.