Plugin check: Run
node "${PLUGIN_ROOT}/scripts/check-version.js"— if it outputs a message, show it to the user before proceeding.
Model check (lightweight models only): If you are a lightweight model optimized for fast, simple tasks, tell the user in your first message that
/app-builderworks best on a general-purpose coding model or an advanced reasoning model — designing the App Spec, reasoning about the dependencies between tables, relationships and artifacts, orchestrating the build and reconciling what already exists take multistep planning, tool use and validation — and recommend switching; then continue. On any other model, skip this note and say nothing about it.
app-builder — intent → model-driven app
Turn a natural-language intent into a deployed model-driven app. You author a reviewable App Spec
(JSON) with the user across confirmed turns, then a deterministic engine (cds-maker-sdk, vendored)
builds it — tables/columns/relationships, sample data, views, Choice-column charts, adaptive forms
with sub-grids, generative pages for overview/dashboard surfaces, and the app module + sitemap.
The same spec drives create and edit: download a deployed app back into a spec, change it, and
re-run the build (it's idempotent).
CRITICAL — run the interactive flow in THIS conversation (the main loop)
You MUST run the authoring questions and the build narration yourself, in the main conversation. Do NOT dispatch a subagent (
Task) for the interactive steps.A subagent is headless —
AskUserQuestionand plan mode do not reach the user from inside one (its only output is its final message). The whole point of this skill is the multi-turn, propose-then-confirm experience, so everyAskUserQuestion,EnterPlanMode, and live build status line must originate here, in the main loop.
CRITICAL — the user sees your chat message, NOT tool output
Shell/tool output — the result of running
preview-app.js, a dry-run plan, or a lint — is COLLAPSED BY DEFAULT in the UI. The user does NOT see it unless they manually expand the tool panel. Running the command is therefore NOT the same as showing the user. Every artifact the user must read, review, or approve — the whole-app preview wireframes, the dry-run build plan, and blocking lint findings — MUST be reproduced verbatim in your chat reply, inside a fenced```code block. Never say "the preview looks right" and leave the content buried in a collapsed panel: paste it into your message. This is the #1 cause of "the wireframes aren't visible" — the preview ran, but its output stayed hidden.
Capabilities — the full toolbox (pick best-fit per requirement)
You are a complete model-driven app builder, not a single-surface tool. Everything below ships in one App Spec and one build — choose what best serves the user's requirement to make a useful, prod-ready app; don't under-build (a bare table list) or over-build (surfaces nobody asked for):
Data model — tables (give each custom table a meaningful Fluent-style SVG table icon by default; propose what the glyph will depict in words — never a Fluent token name — and record it as
iconDescriptionbefore drawing the SVG — seereferences/authoring-flow.md→ Table icons), columns (all types), relationships (1:N / N:N + junctions), sample dataRecord UI — forms (sub-grids, quick-create / quick-view), views (with enriched default columns), charts
Custom grid rendering (preview) —
entities[].columns[].visualization: render a column as aRadialDial,LineChart,HeatMaporStarRatingin every grid and view that shows it, instead of plain text. Reach for it when a column is a magnitude a user scans (a score, a utilization %, a rating, a priority) rather than a value they read exactly — it makes a list scannable at a glance for one line of spec. It is per-column, so set it once on the column, not on each view. Preview: on an environment where it is not provisioned the build skips it and everything else still deploys, so it is always safe to include.Actions — modern command-bar buttons (incl. flyout / split menus), web resources (form JS / HTML / CSS). Two rules when writing that JS, both learned from buttons that deployed perfectly and then did nothing: a command handler is handed the record (
function doThing(primaryControl)) — the build supplies the parameter, so write that signature; and never hardcode Choice values like100000003, because they are assigned per publisher. Resolve by label viagetOptions()(seereferences/app-spec-schema-advanced.md→ webResources). Note also that command and web-resource edits do not redeploy on rebuild — the phases reuse what exists, so changing a button or a script means deleting it first (only a button's hidden / disabled state can be set in place, withcommandStates[]below; the build warns, and verify fails, when a web resource's deployed content differs from the spec's). This does not apply to recovery of the build's ownWEB_RESOURCE_UNVERIFIEDrow: keep that row and the same build workspace, then follow its halt. When the maker wants a rebuild to keep a web resource's content in step with the spec, mark that resourcereconcile: "declared"instead (minimumPluginVersion: "2.21.0") — only when asked, one resource at a time, never a shared (external) one, and never every resource of a downloaded or older spec. A rebuild that would change one that exists stops before writing and names its approval (--authorize adopt:webresource:<web resource name>) with the components that depend on it: show them to the maker and let them choose. Emptying its content also needs--allow-destructive; the halt says so.Show or hide an existing button —
commandStates[](minimumPluginVersion: "2.24.0",app.uniqueName): only when the maker asks to show, hide, enable or disable a modern button that already exists. Never invent a row id: runnode scripts/list-command-states.js --env <envUrl> --app <uniqueName>and pick the row byrowId(never by caption) amongcandidate: truerows; writescope: "table"only (app-scoped buttons are refused in this version) and onlyhidden/disabled— a normal emptyvisibilitytypeon a buttoncommands[]built is static and is never a reason to change it. Never write a commandkeyin the same spec, and never create a button withcommands[]and set its state in the same build: create it in one build, add the state in the next. The apply is a full build with--publish. Run a dry run first and show the maker every--authorize overwrite:command-state:…(one per row change) and--authorize publish:command-state-table:…token it prints — the table one publishes all saved customizations on that table, for every app that shows it — and pass them exactly as printed. Never replay a row write by hand: oncommand-state-write-unknownorcommand-state-version-conflict, list the row again, dry-run again and get the new approval (an ordinary phase retry of the build re-plans from a fresh read). Report three things separately: the rows saved, the table publication confirmed — orcommand-state-publish-unconfirmed("saved, not published") — and what the maker sees in the app, which neither the build nor--verify(stored flags only) checks. A table publish that was sent can still complete after a halt or after the entry is removed; this release keeps no record of it across runs, and a later publishing run requests the table again only because the spec still names it.Form logic without code —
businessRules[]: show/hide, lock/unlock, set-required and set-value, driven by a condition on the record. Reach for a business rule before form JS when the requirement is field-level and declarative — it is visible in the maker, survives solution export, and needs no web resource. Use form JS when the logic needs a real API call, cross-record work, or anything beyond the four supported actions.Guided processes —
businessProcessFlows[]: the staged bar across the top of a record (ordered stages, each with steps bound to that table's columns — every step must bind afield; the platform rejects one without, so use a Boolean flag for a manual check-off). Reach for one when the user describes work moving through phases — "triage → investigate → resolve", "lead → qualify → close". Author itActive(the default) or the stage bar does not appear at all. Who may run a flow issecurityRoles: { "personas": [...] }(Active flows only). v1 is single-entity and linear: cross-entity stages, branching and stage actions are rejected by the spec gate, so offer Maker for those rather than writing them into the spec.Surfaces — generative pages (modern dashboards / overviews / analytics / landing — the default), classic dashboards (opt-in), external URLs
App shell — the app module + sitemap, with per-subarea icons. Turn on the modern shell with
app.newLook: trueunless the user asks for the classic one; it is opt-in and best-effort, so a tenant without the setting still gets a working app.app.headerNavigationRefreshcontrols the Wave 2 header/navigation refresh — a separate, independent setting whose platform default is ON, so set it tofalseonly when the user explicitly wants the classic header.App theme and header logo (Preview, 2.21.0) —
app.theme. Add it only when the maker explicitly asks for branding (brand colours, a header colour, a logo) or says yes to the branding question you ask of every new app at the personas step (authoring-flow Level (a0)); an ordinary app gets noapp.themewithout one of those, and you never invent a palette, a font or a logo. Offer the choices: abasePaletteColor(or explicitpaletteslots), theappHeadercolours, afontonly if they name one, and alogothat is an existing image web resource (or one you also declare inwebResources[]), never a URL. Say before the build that the theme is published with the app, and that an app publication publishes every pending change of the app, not only the theme. The theme does not change thenewLook/ header choices above — do not switch them to fit a theme. Omit the key to leave the app's theme alone;nullremoves the app's override (the environment theme applies again). Theme versions are never deleted, and a logo the theme only references is never touched by teardown.--verifyreports the theme's API state (saved, pending publish, live) — tell the maker to check the header in the app itself.App membership — which forms, views and charts the app offers (
app.mainForms,app.tables). Only these forms on an existing app.app.mainFormsadds the forms you list. To also take the table's other Main forms out of the app on an update, set"mainFormsOnUpdate": "exact"— ask the maker first, it is a removal from the app's membership (no form is deleted). It needs an unmanaged, published app; the build publishes only once Dataverse reads back exactly your list, and otherwise stops with the change saved and the app's publication owed.Pin the artifacts the spec declares.
"pinDeclaredArtifacts": trueadds the spec's own forms, views, charts and dashboards to the app explicitly — use it for a chart or view of a table that is not in the navigation. It only adds. When to use them:"exact"only on an explicit "only these forms" / "remove the other forms" ask, after showing the maker which tables it covers (the build refuses it on an existing app without--allow-destructive); never for "add the Summary form", whichapp.mainFormsalone does. SuggestpinDeclaredArtifacts: truefor a new app whose spec declares a chart, view or dashboard of a table that is not in its navigation. Never turn either on by yourself for an existing app. Both needminimumPluginVersion: "2.21.0".Security & access — one security role per persona, sized from that persona's jobs-to-be-done (the entity access each job needs, unioned into the role), so the app opens for non-admins.
Confidential columns —
isSecured+fieldSecurityProfiles[]. Reach for them when the design names a value only some people may see or change (salary, medical notes, an identifier, private comments): a security role cannot hide one column, a profile can. Name who gets each profile (assignTousers or teams, by id) — never infer them from a persona — and say in the preview who gains access, or that no assignment was requested. Tell the maker that System Administrators see every secured column (test as a non-admin), that an open app may need a reload, to grantreadunlessupdateis needed, that unsecuring a column deletes its permissions (--authorize isSecured:<table>.<column>), and that a teardown keeps each declared profile and names it.Portable schema —
{ "value", "label" }options when an integration or another environment depends on the option numbers;dateTimeBehavior: "DateOnly"for birthdays, due and renewal dates,"TimeZoneIndependent"for a time that means the same clock everywhere (omit it for timestamps); tablesearchEnabled/duplicateDetectionEnabledonly when the maker asks. Never change an existing column's date behaviour or turn duplicate detection off unasked: both need--authorize. All needminimumPluginVersion: "2.21.0"— seereferences/app-spec-schema-advanced.md.Declared views, charts and search columns (
minimumPluginVersion: "2.21.0") — writereconcile: "declared"on each view or chart you author for a new app, and, when editing, on the one existing view or chart the maker asks to change: a rebuild then applies its columns, filters, sort and joins (linkEntities) instead of only adding columns. Never settitleon a new declared chart, and give a declared view its own name — not the stockActive <plural>orInactive <plural>, which every table already has, so changing one is an adoption. Two declared charts on one table need different names, and so do two declared views unless each has its ownkey: aviewIdpin does not tell them apart, and the build refuses the pair (see Approvals in the advanced reference). For a new table you create, proposeentities[].quickFind.findColumns(the primary name plus what a user types in the search box: a number, an email, a code) and confirm it with the maker; on an existing table, only when the maker names what search should match. A change to a view or chart that already exists stops the build with nothing written and names its approval (--authorize adopt:view:<table>/<name>oradopt:chart:,overwrite:for changes made elsewhere,--allow-destructiveto remove columns): explain it and let the maker choose; never edit the spec to avoid it. A local copy that differs from the server's stops it the same way (workspace-copy-unsent-edits) and is kept: ask whether to put that change into the spec and refresh the local copy, or approve theoverwrite:key it prints (overwrite:quickfind:<table>for search columns); pass a key exactly as printed. Never writereconcileon a web resource except as the web-resource bullet above says, on a form, a dashboard, a business rule or a business process flow except as their bullets below say, and never write a commandkey(keyed command bars are refused in this version). Leave a downloaded or older spec without these fields as it is — see the advanced reference.Declared form layouts (
minimumPluginVersion: "2.21.0") — writereconcile: "declared"on a form only when the maker asked its layout to follow the spec (fields, spans, sections, field options, sub-grids, handlers) or said yes when you offered it at Level (b); not for "add a form" or "add a field" with no layout. Tell the maker: controls the spec does not declare stay where they are and nothing is deleted (so no--allow-destructiveis needed for them); a layout the build cannot place safely stops before any write; a table publish puts live every saved change on that table, not only this form, with or without--publish(a declared dashboard is published after its write either way); and Dataverse does not provide a working conditional-write guard for a form's saved layer, so the build re-checks it just before writing, but an edit made in Maker at that instant cannot be detected. Never writegenPages,prune,isDefault,deactivateOtherMainForms,securityRolesor amainFormOrderplace on a declared form (refused). An existing form is bound only with--authorize "adopt:form:<table>/<formtype>/<name>"(lower case;overwrite:form:for changes made elsewhere): explain it and let the maker choose.--verifychecks a declared form against the spec, sub-grid views included (a form whose publish is unconfirmed is unverified, not passed). A download brings declared forms back only with--include-managed --managed-manifest <store file>(one with an event handler comes back with its handler library as anexternalweb resource when that library is this publisher's own unmanaged script; otherwise it is left out and named inmanagedForms.stale, and its declaration is written ready to paste in the new filemanagedFragments.filenames (.maker-workspace/managed-fragments-<time>-<random>.json) with the library it needs, so tell the maker to add both from the spec it was built from); it carries no binding, so the first build that binds each form from the downloaded folder needsadopt:form:<key>(a rebuild that writes nothing may leave it unbound). A form removed from the spec and then deleted in Maker is released by the next build, which names it (managed-root-retired); until then--verifyfails it. One whose publish is unconfirmed is not released (see the unconfirmed publish below). A build that warns a form's or dashboard's retirement could not be confirmed stops before it writes anything (managed-not-settled) and sends nothing more in that run, not even an earlier attempt's deferred publish; running it again reads it afresh and publishes that. A plain form (by its name,<table> formwhen it has none, or itsformId) that replaces a removed declared form with unfinished work (a lost create, an owed or unconfirmed publish) is refused (managed-form-unsettled): restore the declaration and let it settle, or run the build again later.Declared dashboards (
minimumPluginVersion: "2.21.0") — writereconcile: "declared"on a global dashboard only when the maker asked its tiles to follow the spec on rebuilds, or said yes when you offered it at Level (b); give it and every tile akey. Tell the maker: tiles the spec omits stay (nothing is deleted), and settings a tile does not state are kept; a new tile is added after the last row; in an environment with more than one language a new tile gets its caption, with the same text, in every language the environment has (if the build cannot read those languages, it stops before it writes the dashboard:dashboard-languages-unreadable, so run it again; the platform keeps some of those captions and drops others, an iframe tile's for one, and a dropped one other than the base-language caption is no change); an unfinished dashboard of the same name is not taken over and not deleted; a dashboard this build cannot finish is not published, including by the app publish; a dashboard the build created and could not prove is named by id in the stop: when the build knows it created it, delete it and run the build again, which creates it anew; when the stop says the build cannot tell who created it, have the maker inspect it and do not delete it;dashboard-languages-unreadableafter a lost answer means run the build again; and Dataverse does not version a dashboard's saved layer, so an edit made in Maker at the instant of the write cannot be detected. An existing dashboard is bound only with--authorize adopt:dashboard:<key>(overwrite:dashboard:<key>oroverwrite:dashboard:<key>/<tile>for changes made elsewhere,--allow-destructiveto clear its description with""): explain it and let the maker choose.--verifyholds a declared dashboard to its last build (a dashboard changed in Maker since fails until a build settles it; one whose publish is unconfirmed is unverified, not passed). A download brings it back declared only with--include-managed --managed-manifest <store file>(otherwise it is an undeclared entry), with the dashboard and tile ids it was proved on; its first binding needsadopt:dashboard:<key>, because the downloaded folder has no store.Declared business rules (
minimumPluginVersion: "2.21.0") — writereconcile: "declared"on a rule only when the maker accepts that the build manages the WHOLE rule (the offer at the personas step, or their own ask); give every condition, action and apply-action akey. Tell the maker: conditions and actions are never matched by their text; a new rule is created Draft and activated only if nobody changed it in between; a rule that already exists is never edited by the build (change it in Maker, then re-adopt it); a rule changed outside the spec stops the build until it is re-adopted whole with--authorize adopt:rule:<table>/<name>and a declaration naming its whole body; and an environment that cannot host business rules skips them. Explain the approval and let the maker choose.--verifyholds a declared rule to its last build (a rule changed in Maker since fails until it is re-adopted). A download brings it back declared only with--include-managed --managed-manifest <store file>(otherwise it is left out, as every business rule is); the first build that binds a rule that already exists needsadopt:rule:<table>/<name>, because the downloaded folder has no store.Declared business process flows (
minimumPluginVersion: "2.21.0") — writereconcile: "declared"on a flow only when the maker accepts that the build manages the WHOLE flow (the offer at the personas step, or their own ask); give every stage and step akey. Tell the maker: a key keeps a stage's or step's id, so a rename keeps the records on it; a new flow is created Draft and activated only if nobody changed it in between; a flow that already exists is never edited by the build (to change its body or status, change it in Maker, then re-adopt it, keeping every stage and step in place); removing or reordering a stage or step is always refused, and no change in Maker or re-adoption unlocks that; a flow changed outside the spec stops the build until it is re-adopted whole with--authorize adopt:bpf:<table>/<name>and a declaration naming its whole body. Explain the approval and let the maker choose.--verifyholds a declared flow to its last build (a flow changed in Maker since fails until it is re-adopted). A download brings it back declared, keys included, only with--include-managed --managed-manifest <store file>(otherwise it is left out); the first build that binds it from the downloaded folder needsadopt:bpf:<table>/<name>, because that folder has no store. Changing only who may run a managed flow (securityRoles) writes nothing to the flow; the build records it. A managed download restores a flow that hassecurityRolesonly when it can prove each persona the flow names from the role a build made for it, and then writes that persona intopersonas[](a NOTE names it). Tell the maker that persona now owns its role: a privilege added to that role outside the spec is removed by the next build. When a persona cannot be proved, the download leaves the flow out with a warning naming the personas and why (nothing is lost; the store and the maker's own spec keep it) and writes the flow ready to paste in the new filemanagedFragments.filenames. Tell the maker to paste that flow and copy the personas it names from the spec it was built from. Earlier fragments files are kept; never delete one yourself. If the download stops withmanaged-fragments-unwritable,.maker-workspaceis not a plain folder or cannot be written: ask the maker to fix it, never move or delete it yourself. A declared rule or flow removed from the spec whose row was deleted is no longer managed once the build reads it gone by its id (amanaged-root-retiredwarning, which never means it was activated); until then, a removed one whose change is still waiting to be proved keeps the build incomplete. A retirement a build reports it could not confirm also ends that build incomplete; tell the maker to run the build again, which reads the record afresh.An unconfirmed publish — a build that stops naming
--authorize publication-risk:table:<table>/<dispatch>(orpublication-risk:dashboard:<id>/<dispatch>) lost the answer to a publish that may still complete. Tell the maker to check what is live on that table; pass the key exactly as printed, from the latest stop, only when they accept the risk, whichever step printed it. The key names that one lost publish: an older key does not accept a later one, and a key that matches nothing is reported as not used. That run records it before it writes anything and stops (publication-risk-accepted); the next build publishes after the usual checks. A dashboard the spec no longer declares stays owed (publication-withheld) until its declaration is restored. A run that cannot tell whether it recorded the key stops before any write (publication-risk-record-unconfirmed): run the build again without the key.--allow-destructivenever gives it. When the stop says the saved layer is still the one the publish shipped yet the published layer reads differently, the platform may read that form's two layers apart: have the maker compare what is published with the spec; each later publish of that table can stop the same way.A saved change the build did not make — a declared form's table is not published while its saved layer holds a change made elsewhere. If the stop says that change is not published, tell the maker to publish it in Maker if it should stay, or undo it and save, then run the build again.
Stable create ids (
minimumPluginVersion: "2.21.0") — writecreateIdentity: "stable-v1"on a new app; never add it to an existing or downloaded spec (a managed download writes it back itself, only with the declared views and charts it restores). Tell the maker: declared views and charts get ids the spec fixes, so a retry after a lost answer binds the same row instead of creating a second; configuration items, custom APIs, environment variables, field security, duplicate rules and pages keep today's ids; and a local copy with an unsent edit stops the build (create-completion-required) — running again does not merge it: put the change into the spec, then refresh the local copy.Configuration items (
minimumPluginVersion: "2.21.0") —environmentVariables[],connectionReferences[],customApis[],duplicateDetectionRules[]andsolution.version. Declare one only when the maker asks for it, accepts your offer at the personas step, or a page of this app needs it (a page calling a connector needs its connection reference; an action a page calls needs its Custom API). Never write a value that differs per environment into the spec — a current value, a connection id, a secret: those go in a--deployment-settingsfile (the solution deployment-settings shape), which the maker supplies, and asecretvariable takes nodefaultValue. Tell the maker: a page that calls a declared reference or Custom API is not written until the reference is bound to a connection and the Custom API has an implementation (a plug-in type) — a declared Custom API alone is a scaffold; clearing a value, unbinding a reference or removing a parameter or condition needs--authorize <kind>:<key>:<field>(the refusal names it); a teardown keeps these items and names them; a plain download does not bring them back into the spec (a managed download of aconfigurationIdentity: "stable-v1"app brings back the ones its store proves, never a value, default, connection, implementation or duplicate rule); and a whole-build retry after a lost answer can create a second row, so check the environment before running a failed build again. Seereferences/app-spec-schema.md→ Configuration items.AI-first features (admin-gated) — form-fill assist, natural-language grid/view search, NL chart / AI data visualization, M365 Copilot (opt-in); per-table Copilot row summaries (Insight Cards) with tailored prompts, auto-selected for good-candidate tables
Author the smallest spec that fully satisfies the ask, then let the user refine. The Genpage-first
policy below is the record-vs-dashboard rule; references/app-spec-schema.md
documents every field.
Genpage-first policy (surface classification)
Every app surface is one of two kinds — enumerate the app's surfaces and classify each one, don't decide page-by-page in passing:
- Record surfaces (create/read/update/list a table's rows) → a model-driven form + view.
- Everything else — overview/landing, dashboard, KPIs, analytics, guided or wizard flow,
composite or comparison screen → a generative page (
pages[]), not a classic dashboard.
Rules:
- An app whose jobs include an overview, a queue, analytics or a guided flow but which proposes no pages has missed a surface. Where the app genuinely is record-CRUD only, say so explicitly rather than silently omitting pages.
- A traditional
dashboards[]is emitted only on explicit request (e.g. "use a classic dashboard"). - A generative page is authored as a design intent (
source: { kind: "intent" },schemaVersion: 2) during Phase 1 — its.tsxis written in Phase 1.5 — Generate pages, after plan approval and after the data pre-build creates the tables sogenpage.js typescan emitRuntimeTypes.ts. Seereferences/authoring-flow.md→ Pages. - The build's
pagesphase writes each page through the SDK and never places it in the sitemap itself — the SDK is the single sitemap writer, so a page's nav entry comes from apagesubarea inappShell(referenced by the page'skey). Seereferences/app-spec-schema.md→pages[]. - Every page in
pages[]must be sitemap-placed — validation rejects any page absent from the sitemap. A "detail" page that receives a caller-supplied id is a normal sitemap page; it reads its input viapageInput?.data?.<field>. Navigation-only (headless) pages are not supported. - A page that declares
pageInputMUST declaredirectEntry. Because every page is sitemap-placed, a detail page is also reachable straight from the app navigation with no input — a state a user reaches by clicking. Say what happens then:{ "behavior": "selector" }shows a picker and then the record,{ "behavior": "emptyState" }explains and renders nothing broken. Preferselectorwhen the table is browsable; it is the more useful landing. Every key inpageInput.datamust also be produced by some page'snavigatesTo[].data, or the generated page reads a key nothing ever sets. - Three-authority page identity (build + download + verify all follow this): (1) IDENTITY —
the durable
<app>_pagemanifest(key → pageId); a downloaded spec's ownpages[].pageIdoutranks it for that rebuild. (2) EXISTENCE — the env-wide page list read through the SDK, drafts included (crash-safe; decides create-vs-reuse). (3) MEMBERSHIP — the app's sitemapGenPageIdset (placement, download enumeration, verify coverage). All matching is by id — never by display name. - Multi-page navigation uses
PAGEREF_<key>(the stablepages[].key) as thepageIdplaceholder; the build resolves each to the real page GUID in a run-scoped staging copy (the canonical.tsxis never mutated), then verifies every nav edge resolves to the deployed page'sGenPageId.
Workflow
Phase 0 — Working directory
- Derive a short kebab-case slug from
$ARGUMENTS(e.g. "Project Tracker" →project-tracker). - Create the directory (
mkdir -p <slug>on bash/PowerShell;mkdir <slug>on cmd, which has no-pand errors if it exists) and resolve its absolute path. It holdsapp-spec.json,model-app-plan.md, andworkflow-log.md.
Phase 1 — Author the App Spec (interactive, main loop)
Follow references/authoring-flow.md step by step, running
every prompt yourself via AskUserQuestion. In short:
Unattended runs (Copilot autopilot / automation)
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, orExitPlanMode; - 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>)inworkflow-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.
- Prereqs —
node --version,pac help(> 2.10.0, the plugin's minimum). - 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 topac auth create. Capture the org URL (pac org who). - Detect existing —
scripts/list-tables.js --env <envUrl> --search … --exactandscripts/apps.js list --env <envUrl>(<envUrl>is the org URL from step 2) to find tables/apps already present; build around them.--exactkeeps only the tables whose logical name is a search term and lists the terms with none inmissing. A failed read (exit 1) is reported and ends the step — never read it as "nothing exists". - 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.mdand the worked samplesamples/app-spec.support-desk.json. That document covers everything an app always has. Additionally readreferences/app-spec-schema-advanced.mdonce your design calls for a conditional feature — business rules, a business process flow, command-bar buttons, web resources, global choices, classic dashboards, orroleGrants[]. 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.tsxhere. Each level is confirmed viaAskUserQuestionbefore the next begins, andapp-spec.jsonis 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[]andCustomercolumns 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.descriptionis the short tile text, andapp.aiDescriptionis 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
designcontract, mapping each job to its surfaces viajobs[].surfaces[]. No page.tsxhere.dashboards[]only on explicit request.
- charts + sample data and the optional
- 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 inpersonas[]so dropping the roles drops the recorded jobs too; offer read-only privileges to keep the record. If a column is confidential, addisSecured
- Level (a0) — personas & jobs-to-be-done (
…(truncated)