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 — read first.
Edit App (/edit-app)
Post-generation editor for an existing mobile app. native-app-plan.md remains the source of truth, but the default outcome is a fixed generated app, not a plan-only diff. After the user approves the plan delta, continue into Dataverse/native/design/screen mutations, run verification, update memory-bank.md, and regenerate the static preview when UI changed.
Use --plan-only only when the user explicitly asks to update planning docs without changing app code. Normal follow-up prompts in Copilot Chat Agent mode should apply the app change end to end.
Edit documentation protocol
Keep two HTML files current during every edit:
<edit-temp-dir>/edit-app-progress.htmlshows the live operation checklist.docs/create-app-plan.htmlremains the living description of the app.
Both are best-effort documentation. A rendering failure does not authorize a mutation, cancel an approval gate, or turn a failed verification into success.
Progress page
As soon as Step 0 resolves working_dir, before inferred-plan sync or the first progress write, ask
app-docs.js for a namespaced directory inside the user's OS temp directory:
node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' temp
Use the returned directory, progress, progressHtml, and sync paths for the rest of the
run. Do not create progress files inside the project. Create <edit-temp-dir>/edit-app-progress.json
with one row per operation this edit will run.
Use stable IDs such as inspect, impact, plan, approve, save-plan, data, native,
design, screens, verify, preview, and sync-plan. Omit operations that do not apply.
Each row has id, label, status (pending, active, waiting, done, skipped, or
failed), and an optional note.
Add a top-level changes array for the Changes tab.
Keep it empty during initial inspection.
After Step 2, every entry requires kind, title, rationale, and optional detail.
Use kind: general for text-only changes.
Use structured diagram data for data-model and screen changes:
{
"changes": [
{
"kind": "data-model",
"title": "Add inspection evidence",
"detail": "Create a child table for photos and signatures.",
"rationale": "One inspection can have several evidence records with independent metadata.",
"dataModel": {
"tables": [
{
"name": "Inspection",
"columns": [{ "name": "inspectionid", "type": "guid", "primaryKey": true }]
},
{
"name": "Evidence",
"columns": [
{ "name": "evidenceid", "type": "guid", "primaryKey": true },
{ "name": "inspectionid", "type": "guid", "foreignKey": true }
]
}
],
"relationships": [
{
"from": "Inspection",
"to": "Evidence",
"cardinality": "one-to-many",
"label": "contains"
}
]
}
},
{
"kind": "screen",
"title": "Add inspection detail",
"detail": "Add a route that shows findings and evidence.",
"rationale": "Inspectors need a focused review surface before updating a record.",
"screenGraph": {
"screens": [
{ "id": "list", "name": "Inspections", "route": "/inspections" },
{ "id": "detail", "name": "Inspection detail", "route": "/inspections/[id]" }
],
"edges": [
{ "from": "list", "to": "detail", "label": "Select inspection" }
]
}
}
]
}
Derive data-model tables, columns, and relationships from the validated schema proposal.
Derive screen nodes and edges from the updated Screen Map and Navigation Contracts.
When multiple screens are shown, include every navigation edge needed to explain how the user moves
between them.
Do not hand-author Mermaid source in the payload.
app-docs.js derives and renders the ER diagram or screen graph from the structured data.
Retain the approved wording, rationale, and graph data through implementation and verification.
Rewrite that JSON at every numbered step boundary and run:
node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' progress \
--json-file '<edit-temp-dir>/edit-app-progress.json'
Every progress payload is a complete snapshot, not a patch.
Carry every operation row forward and update all rows whose state changed before publishing.
When the top-level phase advances, no row from an earlier phase may remain active or waiting.
In particular, an approval wait must show inspection and planning as complete and the approval row
as waiting.
The top-level object also carries phase, status, note, waiting, and
devicePreviewReady. Set the current row to waiting and waiting: true before every user
question. Set completed rows to done; do not leave the first row active for the whole run. On
failure, mark the failed row and top-level status failed. The page keeps a phone preview on the
right while work is active. Keep devicePreviewReady: false until this edit's Step 8 phone command
succeeds. Then set it to true in the final progress write, mark every applicable row settled, and
set top-level status done. A QR left by an earlier run is never current-run preview evidence.
Every branch that ends the workflow must publish a terminal progress write. Preserve the operation's
actual result, mark completed rows done or failed, mark rows that will not run skipped, clear
waiting, and set the top-level status to done or failed.
Open <edit-temp-dir>/edit-app-progress.html once after the first write using the host's file
opener. If no opener is available, print the absolute path. The page refreshes itself while work
is active.
Living app plan
app-docs.js sync accepts a structured snapshot, not a prose summary:
{
"appName": "Field inspections",
"dataPlatform": "dataverse",
"inferred": false,
"summary": "Added inspection detail and evidence capture.",
"sections": {
"requirements": {},
"architecture": { "dataPlatform": "dataverse", "nativeCapabilities": [], "connectors": [] },
"dataModel": { "tables": [] },
"screens": { "navigation": "", "list": [] },
"design": {},
"offline": {},
"trust": {}
},
"sectionStates": { "screens": "approved" }
}
For an existing plan, include every section this edit changed and omit unchanged sections. Serialize the complete current section after implementation; the sync command replaces that section so removed screens, connectors, capabilities, and tables do not survive as stale rows. Build values from the verified app and its durable plan, not from the pre-approval proposal.
Write the payload to <edit-temp-dir>/app-plan-sync.json, then run:
node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' sync \
--json-file '<edit-temp-dir>/app-plan-sync.json'
If docs/.run-plan.json is missing, the payload must cover every section that can be derived from
the app: routes and layouts for screens, generated models/services and the manifest for
dataModel, power.config.json plus generated registrations for connectors, src/native/ and
template dependencies for native capabilities, and brand/token files for design. Mark this first
snapshot inferred: true and use the note Plan inferred from existing app state because no prior create-run plan was present. Unknown facts stay explicitly unknown; do not guess.
Update docs/create-app-plan.html in the background. Do not open or focus it during /edit-app.
Run the sync command after an inferred baseline is created, after approved plan sections are saved,
and again after Step 8 verification so the page ends on the app's actual current state. Tell the
user when the living app plan has been updated to reflect the latest verified changes.
When to use
- "Improve the search screen to make it easier to use on mobile"
- "Add loading, empty, and error states to the list screen"
- "Add a detail screen for the selected record"
- "Update the design to better match the company branding"
- "Add a form to create a new record in Dataverse"
- "Add barcode scanning and use the scanned value to search records"
- "Generate a new static preview of the updated app"
- "Add a
casetable to the data model" - "Replace the Drawer navigation with Tabs"
- "Add
expo-camerato the native capabilities" - "Add signature capture to approvals and store it in Dataverse"
- "Generate an evidence PDF and retain it on the inspection record"
- "Add a View PDF action for an HTTPS report URL"
- "Reorder screens — move profile out of tabs, into a modal from the home header"
- "Enable Application Insights for this app"
- "Change the Application Insights resource used by this app"
- "Disable Application Insights for this app"
When NOT to use
- Brand-new project →
/create-mobile-app - Explicit implementation-only request → the matching leaf skill under app-edit-routing.md; do not infer this from a short request or the absence of screen details.
- No recognizable generated app root (
package.jsonplusapp/) → stop and ask for the app directory. A missing plan by itself is handled by the inferred-baseline path below.
Workflow
This skill owns direct feature requests forwarded by native, connector, data-model, and design entry points. Reuse the forwarded original request, arguments, and answers; do not ask the user to repeat them.
Those entry points ask permission before invoking this full workflow. Reuse
entry_choice: full-integration for the current request without repeating the
mode question. A direct /edit-app invocation also needs no entry-choice menu.
Neither authorizes mutations: keep the impact/plan gates below. Approved child
calls skip the entry question and return here; do not create a recursive menu.
For each child skill invocation, explicitly pass the
app-edit-routing.md context:
MOBILE_APP_ORCHESTRATING=1, orchestrator: edit-app, working_dir, phase,
and approved_scope. Planning uses read-only proposals; Step 5 implementation
uses the scope approved in Step 3 and saved in Step 4. The marker is not approval
and must not be persisted or relied on via a previous shell export.
- Locate app + health/drift probe → 0.5 Application Insights fast path when applicable → 1. Discover intent + inspect existing app → 1.5 Impact preview → 2. Re-plan affected sections → 3. Gate intent, plan + mutation preview → 4. Write plan diff → 5. Apply additions/refreshes → 6. Rebuild affected screens → 6.5 Unregister approved retired sources → 7. Verify + quality sweep → 8. Preview + memory-bank update + optional debug handoff
Edit Quality Gate Policy — no quality compromise
This is a focused edit workflow, not a lighter quality bar. Reuse /create-mobile-app gates at edit scale.
Required gates by edit type:
| Edit touches | Required gates |
|---|---|
| Any source file | Existing-app health gate, final npx --no-install tsc --noEmit |
| Dataverse/schema/connector | Environment drift gate, data-source/schema gate, Generated Services snapshot refresh, final tsc |
| Navigation/routes | Navigation/layout gate, route contract check, final tsc |
| New screen | Shared scaffold gate, skeleton gate, screen-builder wave gate, style-quality sweep, route check, final tsc |
| Existing screen TSX | Screen edit gate, style-quality sweep, route check when navigation changed, final tsc |
| Native capability | Native allowlist gate, wrapper existence gate, final tsc |
| Pure-JavaScript dependency | Approved exact-version dependency table, package-content gate, package validation, final tsc |
| Design/component/density | Design-system gate, affected-screen style sweep, final tsc, preview |
| Application Insights configuration only | Valid app.json, provider appConfig wiring, final tsc only if app/_layout.tsx changed |
When a gate fails: capture full output once, classify by root cause, repair in a batch, rerun the same gate once. Do not make line-by-line fixes with tsc after every tiny edit. Continue only when the gate is clean or record a BLOCKED: / DONE_WITH_CONCERNS: entry in memory-bank.md.
Hard stops:
- Do not run data-source mutations if the app root/environment cannot be identified.
- Do not launch screen-builders from broken generated services, route layouts, shared code, or skeletons.
- Do not import native wrappers in screens before
/add-nativehas generated them. - Do not hide unsupported native capabilities behind mocks or TODOs just to satisfy TypeScript.
- Do not mark an edit successful if changed screens fail TypeScript, route contracts, or required validators.
Step 0 — Locate app + health/drift probe
Telemetry checkpoint: assess_app_health_and_drift
Before any project read or command, execute
app-working-directory.md.
Resolve the absolute working_dir once, bind every shell call to it with the
fail-closed guard, and use absolute paths for file tools. Forward that same root
to every data child; a previous cd or inherited launch cwd is not a handoff.
Immediately run the edit documentation protocol's temp command and bind its returned
directory, progress, progressHtml, and sync paths as <edit-temp-dir> values before any
inferred-plan sync or progress write below.
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f native-app-plan.md && echo "OK: plan found" || echo "INFO: plan will be inferred"
test -f package.json && echo "OK: package found" || echo "ERROR: no package"
test -d app && echo "OK: app routes found" || echo "ERROR: no app routes"
test -f memory-bank.md && echo "OK: memory bank found" || echo "WARN: no memory bank"
git status --short
If package.json or app/ is missing, STOP because this is not a recognizable generated app.
If native-app-plan.md is missing, inspect the current app before asking edit questions. Build an
inferred current-state baseline from routes/layouts, power.config.json, generated
models/services, .datamodel-manifest.json, src/native/, package dependencies, brand/token
files, and memory-bank.md when present. Write native-app-plan.md with every evidenced section,
label it Inferred current-state baseline, and mark unresolved facts as unknown. Do not run
/create-mobile-app, invent missing business intent, or treat inference as mutation approval.
Create <edit-temp-dir>/app-plan-sync.json from the same evidence and run the sync command so imported apps
receive docs/create-app-plan.html before planning begins.
Create the edit progress payload now with inspect: active, run the progress command, and open
<edit-temp-dir>/edit-app-progress.html.
Read if present:
memory-bank.md— project facts, target environment, visual companion flag, prior blocks.datamodel-manifest.json— existing Dataverse tables/columnsbrand/design-system.mdandbrand/tokens.ts— design constraints and token availabilitysrc/generated/services/*.tsandsrc/generated/models/*.ts— generated data surface
Run these existing-app health checks before any mutation:
This is an inspection-only gate. Include required scaffold/provider/service
repairs in the proposed mutation scope; do not apply them before Step 3 approval.
--plan-only never authorizes these repairs or any other app/cloud mutation.
| Check | Action if unhealthy |
|---|---|
memory-bank.md exists and has expected headings |
If missing/corrupt, ask whether to proceed with reduced resume safety; create/update only after approval |
power.config.json, .resolved-environment.json, and memory bank env agree |
For data-source/schema edits, STOP until the user confirms the intended environment |
src/components/index.tsx, src/hooks/index.ts, src/utils/index.ts, src/tokens/index.ts exist |
Restore missing shared scaffold from shared/samples/src/ before screen-builder work; do not overwrite existing files |
app/_layout.tsx still wraps providers and SafeAreaProvider correctly |
Patch conservatively before screen work; route/safe-area validators depend on this |
src/generated/ compiles when the edit depends on generated services |
Regenerate schemas/services first, or block before screen work |
node_modules and package scripts needed for verification exist |
If missing, ask user to run install; do not pretend verification passed |
If the worktree has uncommitted changes that overlap likely edit targets, show the affected files and ask before continuing. Do not revert or stash automatically.
If the app already fails npx --no-install tsc --noEmit, capture the errors once. Continue only when the failures are in files this edit will touch or are generated-service drift this edit can repair; otherwise surface the pre-existing failure and ask whether to proceed. If the edit would add screens or generated services, clean the prerequisite gate before continuing.
Step 0.5 — Application Insights configuration fast path
If --plan-only is present, do not invoke the configuration skill or change
Application Insights. For a configuration-only request, report that it has no
plan section and stop unchanged; for a mixed request, continue with only the
requested plan proposal.
Use this fast path when the request is only to enable Application Insights, change its resource, or disable it. Application Insights is host/runtime configuration, not a connector or plan section, so do not run the planner, data-model, native, design, screen, or preview flows.
For a configuration-only request, use a configure-insights checklist row. Mark inspect: done
and configure-insights: active before delegation.
If the request also adds or changes custom events in app screens, configure Application Insights here first, then continue through the normal edit workflow for those source changes.
All Application Insights logic lives in the dedicated /setup-app-insights skill. Delegate to it rather than duplicating Azure discovery, connection-string handling, provider wiring, or privacy rules here:
Invoke skill: /setup-app-insights
Environment:
MOBILE_APP_ORCHESTRATING=1
orchestrator: edit-app
working_dir: <working_dir>
phase: configuration
approved_scope: <requested configuration action; setup-app-insights owns approval>
Arguments:
--working-dir <working_dir>
--action <enable|change-resource|disable> # omit to let the skill infer + ask
Determine --action from the request (enable / change-resource / disable); omit it if the request only says "update Application Insights" and let the skill ask. The skill owns the mutation preview, approval, app.json + PowerAppsProvider appConfig wiring, memory-bank.md updates, and the selection telemetry emit.
Handle the return per the status protocol (AGENTS.md rule #12):
DONE→ print the action completed. Then, if the return includesinstrumentation_offer: available(a successful enable/change-resource), ask the user one question, defaulting to No: "Application Insights is on. Want me to add custom telemetry to your app's major operations (create / update / delete)?"- Yes → continue into the normal edit workflow (Step 1 onward) with this brief: "Add custom events at each successful create, update, and delete boundary for the app's main entities; emit named events through
getCustomEventsLoggerwith approved scalar properties only (no operation results, payloads, form values, free text, record titles, personal identifiers, tokens, precise coordinates, nested objects, or complete URLs); usetrackScenario()for any duration." Screen-planner and screen-builder own the source edits under their existing privacy allowlist. - No (or
instrumentation_offer: none) → markconfigure-insights: done, mark every remaining rowskipped, clearwaiting, set top-levelphase: doneandstatus: done, publish the progress page, then stop.
- Yes → continue into the normal edit workflow (Step 1 onward) with this brief: "Add custom events at each successful create, update, and delete boundary for the app's main entities; emit named events through
DONE_WITH_CONCERNS→ markconfigure-insights: done, mark every remaining rowskipped, clearwaiting, set top-levelphase: doneandstatus: done, include the concerns in the note, publish the progress page, surface the concerns, then stop.NEEDS_CONTEXT→ surface the question, re-invoke with the answer.BLOCKED→ markconfigure-insights: failed, mark every remaining rowskipped, clearwaiting, set top-levelphase: doneandstatus: failed, publish the progress page, surface the error (usuallyapp.jsonunusable), then stop.
Step 1 — Discover intent + inspect existing app
Update <edit-temp-dir>/edit-app-progress.json: keep inspect active while reading the app, then mark it
done once the existing routes, data surface, native wrappers, and design constraints are known.
Run the protocol's progress --json-file command after each update.
Infer from $ARGUMENTS when possible, but do not mutate files until you have a concrete edit brief. This is the mini /create-mobile-app requirements phase for one existing-app change.
First inspect the app so questions can use real options instead of abstractions:
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
find app -name '*.tsx' -not -name '_layout.tsx' -not -name '+not-found.tsx' | sort
ls -1 src/generated/services/*.ts 2>/dev/null | sed 's|src/generated/services/||;s|\.ts$||'
ls -1 src/generated/models/*.ts 2>/dev/null | sed 's|src/generated/models/||;s|\.ts$||'
find src/native -maxdepth 1 -type f -name '*.ts*' 2>/dev/null | sort
Also read the relevant native-app-plan.md sections (## Data Model, ## Native Capabilities, ## Design, ## Screens, and ## Generated Services if present) plus the existing TSX for any candidate screen. If brand/design-system.md exists, read it before asking design/screen questions so the edit preserves product grammar, density, component rules, and negatives.
Ask only for information that cannot be inferred from the app. If there is exactly one plausible screen/table/service, state the inferred choice in the mutation preview instead of asking. If there are multiple plausible choices, ask a small multiple-choice question with those real names.
Build an edit brief before Step 2:
## Edit Brief
- Intent: <what user wants to accomplish>
- Target screens/routes: <existing or new>
- Data surface: <generated service/table/connector, or none>
- Native capability: <wrapper/control needed, or none>
- Design scope: <tokens/component grammar/screen-specific, or none>
- Plan sections to update: <Data Model / Native Capabilities / Screens / Design / Connectors>
- App files likely touched: <routes/layouts/src/native/src/generated/brand/etc.>
- Verification gates: <schema, tsc, routes, validators, preview>
If the edit brief is incomplete after inspection, ask scenario-specific questions before continuing.
Only if the requested change is still unknown after inspection, ask via AskUserQuestion:
"What should this app edit change? (a) Data model — add/extend/reuse Dataverse tables (b) Native capability — camera, scanner, PDF, pen, files, secure storage (c) Screens/navigation — list, search, detail, form, tabs, states (d) Design — palette, typography, components, density, brand rules (e) Connector/data source — SharePoint, Office, custom connector (f) Multi-section feature — one user-visible change that needs several of the above (g) Preview only (h) Cancel"
Ask for a brief description only if the original request and supplied answers still do not explain it. Ask one unresolved question at a time.
Scenario-specific questions to ask only when the answer is not already obvious:
| Scenario | Required intent questions before planning |
|---|---|
| Search/mobile usability | Which existing search/list screen? Which fields should search cover? Should search run locally over loaded rows or query Dataverse/connector server-side? Are filters/sort/scope needed? |
| Loading, empty, error states | Which list screen(s)? If no list screen exists, should /edit-app create a new list screen or apply states to another data screen? Are there already loading/empty/error components that should be improved rather than duplicated? |
| Detail screen | From which source screen does the user select a record? Which table/service is the record from? Which fields/actions must appear? Should the route be push detail, modal, or formSheet? |
| Branding/design | What is the brand source (brand doc, logo, URL, text description, existing app)? Is this palette-only, typography, component/density, or full reskin? Should all screens update or only named screens? |
| Dataverse create form | Which Dataverse table? Existing table or new table? Which fields are required/editable? Where should the form launch from? What happens after save (back, detail, add another)? Are there lookup/file/image fields? |
| Barcode/QR scan search | Where should scanning live (new scanner screen, existing search screen action, form field)? What does the scanned value represent (record ID, serial number, asset tag, SKU, custom field)? Which table/service/field should it search? What happens on no match or multiple matches? |
| New requirement + screen | What user workflow is being added? Who uses it? What data/native/connectors does it need? Where does it sit in navigation? What is success/failure behavior? |
| New data source | What job does the data source support? Is it structured business data (Dataverse), SharePoint list/library, a connector action, or another connector? Which screen(s), if any, should use it now? |
| Remove/replace a table or integration | Remove it only from this app, or is server deletion separately intended? Which remaining screens, lookup/identity helpers, native sync, or offline behavior still require it? Preserve server data by default. |
| Native capability without a workflow | What should the capability do, where should users invoke it, and should the result stay local or be retained in an existing data source? |
| Preview only | Preview all screens or only changed/key screens? Should Visual Companion auto-open behavior be honored? |
Existing-state checks before deciding to add vs edit:
- For a named screen, confirm the route file exists. If it does not, ask whether to create it or choose an existing screen.
- For list states, grep the target screen for
LoadingState,EmptyState,ErrorState,refreshing, andonRefresh; improve missing or weak states, do not duplicate existing ones. - For forms, check generated service methods for
create/updatebefore planning UI. If methods or table are absent, add/refresh the data model first. - For scanner work, check
src/native/and the plan's Native Capabilities table for scanner/camera wrappers before screen work. - For detail screens, check Navigation Contracts and existing dynamic routes before creating another
[id].tsx. - For branding, check
brand/design-system.md,brand/tokens.ts, andtamagui.config.tsbefore deciding whether TSX rebuilds are needed.
Use this scenario coverage matrix for common follow-ups. The goal is one user prompt -> one orchestrated edit, not a list of commands the user must run manually.
| User asks | Plan sections | Apply path | Screens / verification |
|---|---|---|---|
| Improve search screen for mobile | Screens | mobile-app:screen-planner edit pass only |
Rebuild the named search/list screen; run tsc, route check, preview |
| Add loading, empty, and error states | Screens | Screen spec + existing TSX edit | Rebuild affected list screen; verify visible loading, empty, error, retry, refresh states |
| Add a detail screen for selected record | Screens; Data Model only if fields/services are missing | Update Screen Map + Navigation Contracts; run /add-dataverse or /add-datasource only if data surface is missing |
Create route/folder/layout as needed; build detail screen and source list/search navigation |
| Update design to match company branding | Design; Screens only if component grammar/density changes | /design-system --refresh <dimension> or --reskin |
Rebuild affected screens only when tokens alone are insufficient; always preview |
| Add a form to create a new Dataverse record | Screens; Data Model if table/columns/lookups/create service are missing | /add-dataverse --skip-planning when schema/service is missing |
Build form route, create payload helper, parent navigation, and focus refresh; verify create/update payloads |
| Add barcode scanning and use scanned value to search records | Native Capabilities, Screens; Data Model if scan target field is missing | /add-native barcode-scanner; /add-dataverse only if target field/table is absent |
Build scanner/search flow, pause/lock scan callback, search via service filter, preview |
| Add a full calendar, agenda, or scheduling view | Screens → JavaScript Dependencies | Add exact react-native-calendars version to the approved table, then npm install --save-exact before builders |
Build the calendar screen with the approved pattern; no /add-native or Android/iOS rebuild |
| Add a new requirement with a new screen | Usually Screens plus whichever of Data Model, Connector, Native, Design the requirement implies | Decompose into one coherent feature; apply data/connector/native/design first, then screens | Generate/refresh service snapshot, layouts, skeletons/shared code, then build affected screens |
| Add a new data source but no screen | Connector/Data Source; sometimes Data Model | /add-datasource when ambiguous; /add-sharepoint, /add-connector, or /add-dataverse when clear |
Refresh generated services and memory bank; no screen rebuild unless the user asked for UI |
| Add Teams/email action or profile lookup | Connectors; Screens when consumed | /add-connector after approval |
Wire the action/read and its loading/error/success behavior; no Dataverse schema by default |
| Add SQL/Excel/SharePoint data | Connectors, including external table/list schema; Screens when consumed | Matching connector leaf after approval | Do not add a Dataverse model just because the connector supplies tabular data |
| Add a new table/entity but no screen | Data Model | mobile-app:data-model-architect -> /add-dataverse --skip-planning |
Refresh generated services; optionally seed sample data; no preview unless UI changed |
| Stop using a table/connector/flow or replace its data source | Data Model/Connectors and affected Screens | Approved retirement via the matching leaf after consumer updates in Step 6 | CLI removes the app registration and regenerates services/config; Step 6.5 verifies remaining sources and refreshes the schema map |
| Remove, rename, reorder, or change a screen archetype | Screens | mobile-app:screen-planner edit pass |
Update route files/layouts/navigation contracts; delete only approved files; run route check |
| Generate a new static preview | None unless source is stale | /preview-screens |
No source edits; do not run data/native/design work |
One user-visible feature may require multiple plan sections. That is allowed and expected. Multiple unrelated features in one prompt should be split: list the features, ask which to run first, and do not bundle their mutations.
Data Model is conditional. A connector/action/native capability does not
automatically require Dataverse. Reuse existing storage and schema. Plan Dataverse
changes only for new/changed Dataverse tables, columns, or relationships actually
required by the feature; missing generated services alone require regeneration,
not new schema. Keep connector operations and external table/list schemas in
## Connectors. Preserve unaffected Data Model content verbatim.
Loophole checks before continuing:
- If the request adds UI that reads or writes data, confirm the generated service exists or add the data source before screen work. Never let screen-builders invent services.
- If the request is ambiguous about Dataverse vs SharePoint vs another connector,
consult the
/add-datasourcerouting table read-only and resolve the choice before approval. Execute the selected leaf only in Step 5. - If a screen requires a native wrapper, run
/add-nativebefore screen-builders importsrc/native/*. - If a native capability is not shipped by the template, stop with a clear block; do not install native packages or fake support.
- If a screen requires a pure-JavaScript library, add it with an exact version to
## Screens → ### JavaScript Dependencies, include it in the mutation preview, and install it before screen builders run. Determine JS-only status from shipped contents, not from a package-name prefix. - If the request changes navigation, update route layouts and navigation contracts before spawning screen-builders.
- If the request adds a new screen, generate any needed route folder, generated-service snapshot, shared code, and skeleton before building TSX.
- Do not stop after writing
native-app-plan.md. The plan update is an internal checkpoint; the app mutation and verification are the user-visible result.
For PDF/signature requests, map the change to every affected section instead of editing only the first obvious one:
| User request | Required plan updates |
|---|---|
| Add signature capture, sign-off, pen, ink, drawing | Native Capabilities: pen-input; Screens: capture, preview, cancellation, and applicable failure states; ask about retention, then update Data Model only if new/changed Dataverse storage is required |
| Store signed approval as Dataverse image | Data Model: Image column; Screens: normalize data:image/png;base64,... before update; Native Capabilities: pen-input if capture is in-app |
| Generate/export/print evidence PDF | Native Capabilities: pdf-report only when expo-print is present, plus sharing only when local share is needed and expo-sharing is present; Data Model: File column only if retained; Screens: generation pending/failed/success states |
| Persist generated PDFs | Data Model: Dataverse File column or child Attachment table; Screens: create/update row first, then upload File bytes; Native Capabilities: pdf-report |
| View/open/preview PDF | Native Capabilities: native-pdf-viewer for HTTPS URLs or local file:// URIs when @microsoft/power-apps-native-pdf-viewer 0.2.9+ is present; Screens: invalid URL and viewer failed states |
If a single PDF/signature request requires multiple plan sections, say so and run the edit loop section-by-section. Do not write a native capability entry that references a Dataverse column or screen state that remains absent from the plan.
Step 1.5 — Impact preview (cheap abort gate)
Telemetry checkpoint: analyze_edit_impact
Before showing the impact question, mark inspect: done, set impact: waiting, set top-level
phase: impact, waiting: true, and run progress --json-file. If the user proceeds, change
impact to done, set plan: active, clear waiting, and run it again. A cancellation sets the
top-level status to done with all unstarted operations skipped.
Before spawning architects or mutating files, show a rough impact preview and ask for proceed/edit/cancel. This mirrors /create-mobile-app Step 2c at edit scale.
Compute:
- Cost tier: Cheap (single existing screen), Medium (new route/form/detail or one data source), Heavy (multi-screen/nav/design/data/native), Major (reskin or broad screen rebuild).
- Likely plan sections: Data Model, Native Capabilities, Connectors/Data Sources, Design, Screens.
- Likely files: exact screen/layout/native/brand/generated/memory files when known.
- Likely skills/agents:
mobile-app:data-model-architect,mobile-app:screen-planner,mobile-app:screen-builder,/add-datasource,/add-dataverse,/add-sharepoint,/add-connector,/add-native,/design-system,/preview-screens, optional/debug-apponly when the user gives a concrete runtime symptom. - Verification gates: schema, generated services, route contracts, screen validators, preview.
- Main risks: environment drift, unsupported native package, generated service missing, navigation contract change, broad design churn, stale installed plugin cache.
Print:
─── Edit impact preview ─────────────────────────────
Intent <one sentence>
Tier <cheap|medium|heavy|major> (~<time range>)
Plan <sections>
Skills/agents <list>
Files <screen/layout/data/native/brand/memory summary>
Verification <gates>
Preview <yes/no>
Risks <none or bullets>
Choose:
(a) Proceed
(b) Edit intent / answer more detail
(c) Cancel
If the user chooses edit, return to Step 1 and refine the edit brief. If cancel, stop with no file mutations. If proceed, continue to Step 2.
If the user picks (d) Design:
Read the /design-system references to propose the Design delta without executing
the skill yet. Determine the dimension from the user's description:
| User says | Route to |
|---|---|
| "change colors", "palette", "accent" | /design-system --refresh palette |
| "change fonts", "typography", "font" | /design-system --refresh typography |
| "change components", "buttons", "cards" | /design-system --refresh components |
| "change spacing", "density", "compact" | /design-system --refresh density |
| "add rule", "remove rule", "negatives" | /design-system --refresh negatives |
| "change animations", "motion" | /design-system --refresh motion |
| "full redesign", "reskin", "new theme" | /design-system --reskin |
One-major-change-per-prompt enforced. If the user asks to change palette AND typography → refuse, ask which first. This matches /design-system's own behavior.
Include runtime token/provider wiring and any affected screens in the proposal.
Continue through Steps 2-4 before executing /design-system in Step 5.
Do not write brand artifacts before approval or during --plan-only, and do not
jump from design refresh straight to verification if screen changes are needed.
Step 2 — Re-plan affected sections
Telemetry checkpoint: revise_affected_app_plan
Keep plan: active while architects or inline planning update the affected sections. If a planner
needs user context, change plan to waiting, set waiting: true, and run the progress command
before asking. Restore it to active after the answer.
Reuse the same planning primitives as /create-mobile-app, but only for the affected surfaces:
| Surface | Reuse from create flow | Edit-app scope |
|---|---|---|
| Dataverse schema | data-model-architect + /add-dataverse Step 8 |
New/changed tables, columns, lookups, calculated fields, generated services |
| Connector choice | /add-datasource, /add-sharepoint, /add-connector |
New or changed external data/action surface |
| Native capability | /add-native Step 9 |
New wrappers/controls needed by edited screens |
| JavaScript dependency | screen-planner + shared/references/javascript-dependency-planning.md |
Explicit package requests or established JS libraries needed by edited screens |
| Design | /design-system Step 9b |
Token refresh, reskin, density/component rules |
| Navigation | /create-mobile-app Step 10b |
Changed tabs, stacks, route groups, modal/formSheet presentation |
| Service snapshot | /create-mobile-app Step 10.7 |
Refresh after any data source/schema change |
…(truncated)