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.html shows the live operation checklist.
• docs/create-app-plan.html remains 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 case table to the data model"
• "Replace the Drawer navigation with Tabs"
• "Add expo-camera to 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.json plus app/) → 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.

0. 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-native has 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/columns
• brand/design-system.md and brand/tokens.ts — design constraints and token availability
• src/generated/services/*.ts and src/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 includes instrumentation_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 getCustomEventsLogger with approved scalar properties only (no operation results, payloads, form values, free text, record titles, personal identifiers, tokens, precise coordinates, nested objects, or complete URLs); use trackScenario() for any duration." Screen-planner and screen-builder own the source edits under their existing privacy allowlist.
  • No (or instrumentation_offer: none) → mark configure-insights: done, mark every remaining row skipped, clear waiting, set top-level phase: done and status: done, publish the progress page, then stop.
• DONE_WITH_CONCERNS → mark configure-insights: done, mark every remaining row skipped, clear waiting, set top-level phase: done and status: 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 → mark configure-insights: failed, mark every remaining row skipped, clear waiting, set top-level phase: done and status: failed, publish the progress page, surface the error (usually app.json unusable), 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, and onRefresh; improve missing or weak states, do not duplicate existing ones.
• For forms, check generated service methods for create/update before 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, and tamagui.config.ts before 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-datasource routing 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-native before screen-builders import src/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-app only 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 before builders run
Shared code + skeletons	/create-mobile-app Step 10.8	New screens, changed data imports, new shared row/card/hooks
Screen implementation	/create-mobile-app Step 11	Only affected screens, via mobile-app:screen-builder waves
Quality sweep	/create-mobile-app Step 11.4	Changed screen files and route layouts

Read each affected section verbatim from native-app-plan.md and pass it as input to the relevant read-only agent. Use the plugin namespace for every Task invocation.

For Dataverse schema/new-binding work, first read and execute dataverse-change-planning.md. Use the requested delta and necessary dependencies, not all historical plan rows. The foreground obtains and validates compact evidence; the architect uses Dataverse planning mode: required, not legacy live discovery. Native/design/connector-only edits, app-binding removals, and retained-service refreshes skip this planning path and never reuse its old artifacts.

Before the first Task, run a silent preflight for the leaf agent you need (mobile-app:data-model-architect, mobile-app:screen-planner, or mobile-app:screen-builder preflight later). If the host cannot spawn agents, print once:

"→ Planner agents unavailable in this host — running inline planning. (No action needed; this is automatic.)"

Inline fallback rules:

• Data Model: use the existing plan, manifest, models, and edit brief as context, but ground decisions in the shared workflow's validated compact evidence. Produce _dm_section.md and the normalized schema contract and run the same decision validator as for an agent result; local files alone are not proof of current server schema.
• Screens: draft Screen Map / Navigation Contracts / per-screen spec changes inline using agents/screen-planner.md, shared/references/screen-templates.md, and the existing screen TSX; then gate it exactly like an agent result.
• Native Capabilities and Connectors: already handled inline by this skill.
• Never skip approval just because a leaf agent is unavailable.

Section	Agent (read-only)	Output file
Data Model	mobile-app:data-model-architect	_dm_section.md + .tmp/dataverse-schema-contract.json
Native Capabilities	(handled inline — no separate agent)	_native_section.md
Screens	mobile-app:screen-planner	_screens_section.md

Spawn agent: mobile-app:<agent-name>

Prompt:
  Update the existing <section-name> section based on the user's change request.

  User request: <verbatim>
  Current section content: <verbatim>
  Working directory: <absolute path>
  Plugin root: ${PLUGIN_ROOT}
  Phase: planning
  Proposal only: <true for --plan-only or a planning-phase caller>

  Mode: edit (preserve existing decisions where the change doesn't affect them).
  Existing generated app must be updated after approval, so include enough detail for builders to mutate code without guessing.
  Return the updated section as a markdown file.

For the Data Model handoff, also include these fields verbatim:

Dataverse planning mode: required
Normalized Dataverse foreground planning snapshot (validator input only): <SNAPSHOT_PATH>
Compact Dataverse architect evidence: <ARCHITECT_EVIDENCE_PATH>
Structured schema contract output: <working_dir>/.tmp/dataverse-schema-contract.json
Scope: <requested delta and necessary dependencies; preserve unrelated rows>
Native capabilities and connector ownership: <retained approved constraints>

Handle structured Dataverse context/revision signals with the shared planning recovery before generic retry limits. For other signals, use AGENTS.md: DONE continues to output validation, DONE_WITH_CONCERNS: must be surfaced and recorded, NEEDS_CONTEXT: gets one clarified retry, BLOCKED: stops before app mutation, and unknown first lines are BLOCKED: malformed agent return. Every Data Model result, including inline output, must pass the shared decision validator; DONE alone never authorizes Step 3.

Before Step 3, rebuild the progress payload's changes array from the completed affected-section proposals. Every change must explain why it is necessary. For a Data Model delta, include the affected tables, relevant columns, and relationships from the validated normalized contract so the Changes tab renders the proposed ER diagram. For a Screens delta, include the affected existing and proposed screens plus their real navigation edges so the Changes tab renders the updated screen graph. Run progress --json-file after writing this payload and before changing approve to waiting.

For Native Capabilities (no separate agent), do it inline: read the current capability table, apply the change, regenerate the table. For PDF/pen rows, include storage/output notes in the table or immediately below it:

• native-pdf-viewer 0.2.9+ opens HTTPS URLs and local file:// URIs; it does not support content://, blob:, or http://.
• pdf-report generates a local PDF only when expo-print is present; local output may be opened by native-pdf-viewer 0.2.9+, shared with expo-sharing when present, or uploaded to Dataverse File storage.
• pen-input returns a PNG data URI; cancellation is a non-error state; Dataverse target must be Image, File, or child Evidence/Signature row.

For connector/data-source edits, read connector-planning.md and the /add-datasource routing table as reference only. Propose the ## Connectors delta with operations, external tables/list schemas, and consuming screens. Do not execute connector skills, create connections, or generate services in Step 2. Update Screens when the connector drives new screens/forms; defer the selected leaf to Step 5 after approval.

For removals/replacements, follow data-source-removal.md. Before changing the plan, capture the current registration inventory and propose retain/add/refresh/removal sets. Do not interpret an omitted table as permission to delete it. Include non-screen consumers and offline dependencies, preserve server tables/records, and carry the approved removal set through Step 6.5.

Step 3 — Gate intent, plan + app mutation preview

Telemetry checkpoint: approve_app_mutation_plan

Before asking for approval, mark plan: done, set approve: waiting, set top-level phase: approval, waiting: true, and run progress --json-file. A revision returns plan to active. Approval marks approve: done, sets save-plan: active, clears waiting, and runs the command again. Cancellation settles the page with remaining operations skipped.

For Dataverse planning, require exit 0 from validate-dataverse-planning-decisions.js for the current normalized contract and snapshot before showing this gate. Revisions repeat that check. There is no extra create-flow approval gate; preserve this edit's existing UX.

If this is a planning-phase handoff from another owner, return the validated proposal and concerns to that owner now, without saving the live plan or opening an implementation gate. Do not turn the caller's planning consent into approval to apply the edit. A direct --plan-only request retains the explicit plan-document approval below. Before returning, mark inspect, impact, and plan as done; mark approval, save, implementation, verification, preview, sync, and device rows skipped; clear waiting; set top-level phase: done, status: done, and devicePreviewReady: false; and publish one final progress write. The note must say that the validated proposal was returned to the owning workflow.

Show the user a side-by-side diff (or before/after) for every changed plan section. Also show an app mutation preview:

• Edit brief: intent, target screens/routes, data/native/JavaScript/design dependencies, and assumptions
• Data/schema operations to run (/add-dataverse --skip-planning, connector add, native wrapper add)
• Exact app data-source removals, consumer updates, and server data that will be preserved
• Exact sample-data table allowlist and count/media policy, if requested; exclude retiring tables and include required seed parents only with explicit approval. An empty approved set authorizes no seed writes.
• Screen files to create, rewrite, rename, or delete
• Navigation/layout files to update
• Verification commands to run
• Whether preview.html will be regenerated

Ask:

"Approve this edit and apply it to the app? (a) Approve and apply (b) Revise — give feedback for another pass (c) Cancel — discard changes"

If revise → loop back to Step 2 with the user's notes appended. If approve → continue. If cancel → STOP, leave the plan and app untouched.

If $ARGUMENTS includes --plan-only, change option (a) to "Approve and save plan only" and stop after Step 4 with a clear note that the app was intentionally not changed.

Step 4 — Write plan diff

Keep save-plan: active while writing the approved native-app-plan.md sections.

Replace the approved section(s) in native-app-plan.md with the approved content (preserve all other sections verbatim). Print a unified diff so the user has a record:

diff --git native-app-plan.md native-app-plan.md
---
+++ Section: Data Model
- | 🆕 Create (Tier 2) | contoso_workitem | ... |
+ | 🆕 Create (Tier 2) | contoso_workitem | ... |
+ | 🆕 Create (Tier 2) | contoso_case | Lookup → account, severity, status |

If this is --plan-only, update memory-bank.md with plan_only: true, mark save-plan: done, mark every implementation, verification, preview, and device-handoff row skipped, set top-level phase: done, status: done, and devicePreviewReady: false, and publish one final progress write. Keep docs/create-app-plan.html unchanged because it describes the current app, while native-app-plan.md holds the approved but unapplied intent. Then print the exact follow-up commands and stop.

For an implementation run, keep docs/create-app-plan.html unchanged until Step 8 verifies the implemented state. The approved proposal belongs in native-app-plan.md and the edit progress page, not in the living current-app plan. Mark save-plan: done and the first applicable implementation operation active in the progress page.

The saved plan describes approved intent, not successful application. When the Data Model changed, merge its newly accepted _dm_section.md proposal here; never replay stale scratch output for an unrelated edit. Preserve unrelated sections and do not reuse execution artifacts/approval receipts bound to an older plan. The leaf updates .datamodel-manifest.json only from verified schema/service outcomes; pending retirements stay transitional until Step 6.5. Record any failure and remaining operations in memory-bank rather than claiming this plan is applied. For approved Dataverse implementation, freeze the shared workflow's contract_sha256 and final saved plan_sha256 in approved_scope, and retain the absolute planning_snapshot, architect_evidence, and schema_contract paths. A plan-only save does not create this implementation approval context.

Step 5 — Apply app mutations

Telemetry checkpoint: apply_app_mutations

Update the progress page after every applicable operation below. Mark each of data, native, and design active only while its leaf runs, then done, skipped, or failed from the actual result. Run progress --json-file after each transition so the checklist identifies the operation that is currently running.

Apply sections in dependency order so screens always build against the current data/native surface:

Run only operations in the approved delta, not every section of the existing plan. Pass MOBILE_APP_ORCHESTRATING=1 and the explicit implementation context above on each handoff, including through routers and on retries. Reuse supplied answers, and return to the approval gate if an unresolved choice changes scope.

0. Environment drift gate for data edits — before Dataverse, SharePoint, connector, or sample-data work, compare memory-bank.md, power.config.json, and .resolved-environment.json. If they disagree, show the values and ask the user which environment is intended. Do not create tables or connections until confirmed.
1. Data Model — invoke /add-dataverse --skip-planning with the approved delta and the scoped planning context below, not every row in the plan. The leaf verifies the evidence/approval hashes and performs fresh live reconciliation before scoped mutations; no partial create-only fast-path flags or fabricated create receipt. It refreshes the affected services, updates verified inventory, and leaves generated services compiling. Pass offline_reconciliation_owner: edit-app; Step 5.6 owns the offline check, so the leaf returns its verified delta without prompting twice. After it returns, run npm run generate-schemas and npx --no-install tsc --noEmit; do not continue to screens until clean.
2. Sample Data — seed only the explicit table allowlist approved in Step 3. Propose newly created Dataverse tables used by changed screens as candidates, not the entire project manifest. Distinguish createdThisEdit from historical manifest status: new; existing/reused parent tables need explicit inclusion. Validate the approved names against verified output and the retirement set. An empty scope means skip seeding. Missing/unverified/retiring targets return to the owner for correction, not a fallback to project-wide seeding. Pass the handoff below. If insertion fails, record the partial result and continue only if the app handles empty states; never report complete seed coverage.
3. Connector/Data Source — read and execute /add-datasource when ambiguous, or /add-sharepoint / /add-connector for approved connector changes. For a retained source refresh, pass skill-only --refresh --data-source-name "<registered-name>" with its verified identity in approved_scope; do not route refreshes through addition. Use the same refresh branch for service-only Dataverse repairs without schema changes. Regenerate services and record connection notes in memory-bank.md.
4. Pure-JavaScript Dependencies — execute the Installation Contract in shared/references/javascript-dependency-planning.md for new or changed rows in the approved ## Screens → ### JavaScript Dependencies table. Approval is consent for those exact packages and versions. Install and validate before screen work; if final inspection finds native code/config or incompatible runtime dependencies, remove only the newly added package and stop with the exact failed criterion.
5. Native Capabilities — read and execute /add-native <capability> for every new capability. Do not install missing native packages or fake wrappers. If a capability is unsupported by the current template, stop before rebuilding screens that import it, record the block, and tell the user what upstream template support is missing.
6. Design — read and execute the approved /design-system operation (refresh, reskin, theme, or rollback). Include CODE_APPS_NATIVE_ORCHESTRATING=1 in the child environment to suppress intermediate browser tabs, alongside the scoped MOBILE_APP_ORCHESTRATING=1 context above. Apply its Tamagui integration reference to changed tokens/themes and provider wiring before verification; a brand artifact alone does not prove runtime integration. Token-only changes usually do not require screen TSX rewrites; component/density/negative-rule changes may. Rebuild affected screens in Step 6 rather than returning early. For an approved custom dark palette, execute the reference's Approved dark palette branch: wire darkTokens.color into appDarkTheme, then into the provider's brandedDarkTheme. Verify the export/keys and resolved dark surface/text values; writing brand/tokens.dark.ts alone is not completion.

Step 5 applies additions/refreshes, not removals. If the Data Model change is removal-only, do not run /add-dataverse's add workflow against the shortened plan: it would neither unregister the old source nor safely update its consumers. Defer approved retirements until Step 6.5, after source consumers are updated.

After any Data Model, Connector/Data Source, JavaScript Dependency, or Native Capabilities mutation, rerun the generated-service/dependency/native-wrapper probe before screen work. Screen prompts must reflect what exists on disk now, not what the earlier plan expected.

Dataverse handoff (only for approved schema/new-binding work):

Invoke skill: /add-dataverse

Context:
  MOBILE_APP_ORCHESTRATING=1
  orchestrator: edit-app
  working_dir: <working_dir>
  phase: implementation
  offline_reconciliation_owner: edit-app
  planning_snapshot: <SNAPSHOT_PATH>
  architect_evidence: <ARCHITECT_EVIDENCE_PATH>
  schema_contract: <working_dir>/.tmp/dataverse-schema-contract.json
  approved_scope: <accepted delta and dependencies, contract_sha256, plan_sha256>

Arguments:
  --working-dir '<working_dir>'
  --plan-section '<working_dir>/native-app-plan.md#data-model'
  --skip-planning

Sample-data handoff (only for a nonempty approved seed scope):

Invoke skill: /add-sample-data

Context:
  MOBILE_APP_ORCHESTRATING=1
  orchestrator: edit-app
  working_dir: <working_dir>
  phase: implementation
  approved_scope: <approved seed tables, count/media policy, and lookup decisions>
  retiring_tables: <approved retirement list, or empty>

Arguments:
  --working-dir '<working_dir>'
  --tables "<approved-seed-table-logical-names>"
  --exclude-tables "<retiring-table-logical-names-or-empty>"

These are skill arguments, not Dataverse CLI flags. A required parent outside the allowlist returns NEEDS_CONTEXT; the seeding leaf must not expand scope or seed a transitional retiring table to satisfy its coverage rules.

Step 5.5 — Refresh generated service snapshot

Run this after any data-source/schema/connector mutation and before any screen-builder prompt:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
for svc in src/generated/services/*.ts; do
  [ -e "$svc" ] || continue
  name=$(basename "$svc" .ts)
  methods=$(grep -oE 'static async [a-zA-Z_]+' "$svc" | sed 's/static async //' | tr '\n' ',' | sed 's/,$//')
  echo "| \`$name\` | \`src/generated/services/$name.ts\` | $methods |"
done

Replace or create the ## Generated Services (snapshot at <ISO timestamp>) section in native-app-plan.md immediately after ## Screens. If there are no services, write an empty table and a note. Screen-builders must treat this table as authoritative.

Mark still-present services in the approved removal set as retiring: builders must not introduce or retain dependencies on them. Refresh this snapshot again after Step 6.5 so it describes the actual remaining output.

Do not ask the user to run these follow-up skills manually. This skill is the orchestrator.

Step 5.6 — Offline profile reconciliation

If Step 5 created or extended Dataverse tables, an existing Mobile Offline Profile may now be missing those tables/columns (new tables never sync to devices; new columns arrive blank). Step 5's complete scoped /add-dataverse --skip-planning handoff names offline_reconciliation_owner: edit-app, so this orchestrator owns the check instead of the leaf's Step 8.5. The flag alone is not enough. Skip when no Data Model mutation occurred in this edit.

For mixed addition/removal edits, intersect any returned additions with the approved retained/added Dataverse set before offering/applying profile changes. Never add a retiring table to the offline profile merely because its transitional manifest entry remains until Step 6.5.

Run the local, no-network delta check:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/offline-profile-delta.js" --project-root '<working_dir>'

Capture the exit status and stdout/stderr and follow the failure dispatch in offline-profile-reconciliation.md before continuing: a non-zero exit, status: error, malformed/missing JSON, or unknown status skips mutation helpers and ends with DONE_WITH_CONCERNS for already-applied changes (otherwise BLOCKED), never a clean success. For valid no-manifest / no-profile / in-sync, continue silently. For delta, obtain approval and execute the reference's Scoped helper handoffs with orchestrator: edit-app, the same absolute working_dir, phase: implementation, and the exact approved environment/profile/table scope. Pass --working-dir '<working_dir>' to each helper along with its table and column arguments, then re-check through the same failure dispatch. Record the outcome in the Step 8 memory-bank entry without clearing pending offlineRetirement outcomes.

These statuses concern additions only. Preserve any offlineRetirement outcomes from earlier attempts, and collect the removal leaf's updated outcomes in Step 6.5; an in-sync result never resolves a pending retirement.

Step 6 — Rebuild affected screens

Telemetry checkpoint: rebuild_affected_screens

Set screens: active before route/layout/shared-code work. Update its note after each builder wave, for example Wave 2 of 3 complete, and run the progress command. Mark it done only after the navigation/skeleton gate and every required builder wave pass.

Use the plan diff plus the user's request to build the affected screen set:

Change type	Screens to rebuild
Existing screen behavior/layout/state/search change	The named screen(s)
New detail screen	The new detail screen plus the source list/search screen that navigates to it
New create/edit form	The form screen plus parent list/detail screens that launch it and refresh on focus
New scanner/camera/PDF/pen workflow	The capability screen plus any result/detail/form screens it routes to
Data-model field added for visible UI	Every screen that displays or writes the field
Data source removed/replaced	Every approved consumer, including shared hooks/helpers and native upload/sync code; retain the old registration until these edits are complete
Navigation pattern changed	Every tab/root screen and any route whose contract changed
Design component/density/reskin changed	All screens whose layout grammar is affected; for full reskin, run a broad screen wave or controlled style sweep

Before spawning builders:

• Pass the approved retiring service/source list to every affected builder. Still-present generated files are transitional dependencies, not permission to keep or introduce usages that the edit is meant to remove.
• Update route layout files using the /create-mobile-app Step 10b layout rules if navigation changed.
• Create missing route folders for new screens.
• Refresh the ## Generated Services table using /create-mobile-app Step 10.7 rules if any data source/schema changed.
• Generate or refresh app-specific shared code from /create-mobile-app Step 10.8a when two or more affected screens share an entity row/card, choice map, cursor hook, or save helper.
• For brand-new screens, write typed skeleton files using /create-mobile-app Step 10.8b patterns before calling builders.
• For existing screens, do not overwrite with skeletons. Pass the current file content and the change request to the builder in edit mode. If imports/data hooks changed, update them surgically before the builder fills or revises JSX.
• For removed screens, delete route files and remove layout entries only when the user approved deletion in Step 3.

Navigation/layout algorithm:

• Read the approved ## Screens Screen Map and Navigation Contracts.
• Normalize every target file to its Expo route before editing. Reject duplicate normalized routes, especially <parent>/[id].tsx together with <parent>/[id]/<child>.tsx; move the detail contract to <parent>/[id]/index.tsx before builders run.
• For every new route, create the parent folder and inner _layout.tsx when the route is nested.
• For modal/formSheet/detail routes, add the correct <Stack.Screen name="..." options={{ presentation: 'modal' | 'formSheet' }} /> in the owning folder layout.
• For tab/root changes, patch only the route list in app/(app)/_layout.tsx; preserve auth/provider logic and imports not related to route registration.
• For removed routes, delete the route file and remove layout entries only after explicit user approval in Step 3.
• After route/layout edits and before builders, run npm run check-routes --if-present or node scripts/check-routes.js if available.

Shared scaffold algorithm:

• If src/components/index.tsx, src/hooks/index.ts, src/utils/index.ts, or src/tokens/index.ts is missing, copy the missing file from shared/samples/src/. Never overwrite an existing shared file.
• If affected screens share an entity card/row, choice map, cursor hook, detail hook, or save helper, create or update a focused app-specific shared file before spawning builders.
• For brand-new screens, write a typed skeleton at the target_file using the relevant /create-mobile-app Step 10.8b template. The skeleton must compile with return null before screen-builder runs.
• For existing screens, never replace the whole file with a skeleton. Patch imports/hooks only when the approved edit changes the data/native surface, then ask the builder to preserve existing behavior.

Run the navigation/skeleton gate before screen-builder work:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npx --no-install tsc --noEmit

If it fails, batch-fix layouts, route names, skeleton imports, generated-service names, shared exports, or hook signatures, then rerun once. Do not launch screen-builders from a broken shell.

Step 6.1 — Screen-builder preflight + waves

Before the first wave, run a silent Task preflight for mobile-app:screen-builder using a no-op screen name. If unavailable, print once and build inline using agents/screen-builder.md; inline mode must satisfy the same quality rules.

Batch affected screens in waves of up to 5. For each wave:

1. Print the wave start: Wave <N>/<W> starting: <screen names>.
2. Spawn all builders in one message so they can run in parallel.
3. Parse each first line per AGENTS.md (DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED). Unknown first lines are BLOCKED.
4. Retry NEEDS_CONTEXT once with the missing context from plan/files/services.
5. Stop on BLOCKED unless the user chooses to skip with an approved placeholder.
6. Run npx --no-install tsc --noEmit after the wave before launching the next wave.
7. If the wave gate fails, group errors by root cause and respawn affected builders with consolidated TypeScript output. Cap at 2 retries per screen.

Do not launch wave N+1 until wave N is clean.

Spawn mobile-app:screen-builder agents in waves of up to 5 screens. Prompt each builder with:

Follow screen-builder.md.
Mode: edit existing generated app.
User change request: <verbatim>
working_dir: <absolute path>
screen_name: <screen id>
route: <route>
target_file: <absolute path>
plan_path: <absolute path>/native-app-plan.md
current_file: <paste current file content if the file exists>

Preserve unaffected behavior from the existing screen. Apply the approved plan diff. If this is an existing screen and no skeleton marker is present, update the screen from current_file instead of falling back to sample layout.

Step 6.5 — Unregister retired data sources

Skip when the approved removal set is empty. After Step 6 updates/removes the consumers, re-check that no retained source depends on a retiring registration. Execute data-source-removal.md through /add-dataverse for Dataverse bindings, /add-sharepoint for SharePoint, or /add-connector for other connectors/procedures/flows, passing removal mode, the exact registered identities, and the current approved orchestration context. Select removal mode with the skill-only --remove argument; never pass it to CLI.

The leaf bypasses its add workflow and uses the supported CLI removal command, which owns .power/schemas/, src/generated/, and power.config.json cleanup. Then regenerate the runtime schema map, verify absent/retained registrations and generated output, and reconcile the app manifest and offline impact. Refresh the Generated Services snapshot again before final validation. A no-op, partial cleanup, or remaining consumer blocks completion; do not mark the new plan as fully applied or manually patch generated/config files. Carry each leaf's offlineRetirement status into Step 8, including intentionally retained coverage and pending decisions/migrations. Do not replace those statuses with Step 5.6's addition-only result.

Step 7 — Verify

Telemetry checkpoint: validate_edited_app

Set verify: active before the first gate and run the progress command. On a failed gate, keep it active while applying the bounded repair and record the failing command in its note. Mark it failed if verification cannot be completed; mark it done only after every required rerun passes.

Run verification after mutations. Batch-fix root causes, then rerun the failed gate once. Verification is selected by what changed, but TypeScript is always required after an app mutation.

Required gates, selected by what changed:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npm run generate-schemas      # if any data source/schema/connector changed
npx --no-install tsc --noEmit              # always after app mutation
npm run check-routes --if-present

If npm run check-routes is absent but scripts/check-routes.js exists, run:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node scripts/check-routes.js

When screen files changed, run the mobile plugin's report-mode validators explicitly:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/hooks/validate-screen-quality.js" --report <changed-screen-files-or-app-dir>
node "${PLUGIN_ROOT}/hooks/validate-color-contrast.js" --report <changed-screen-files-or-app-dir>

Treat validator findings like create-flow gate failures: capture once, batch by root cause, repair, and rerun the same validator once. These scripts are invoked only inside the mobile workflow; do not register them as plugin-wide hooks.

Step 7.1 — Targeted style-quality sweep

When screen files changed, run a focused version of /create-mobile-app Step 11.4 against the changed screen files plus any route layouts changed by this edit.

Rules:

1. Run validate-screen-quality.js --report and validate-color-contrast.js --report when available.
2. Merge issues by file and rule.
3. Auto-fix deterministic issues: weak readable tokens, yellow/orange badges with white text, missing icon-only aria-label, missing role, tiny icon hit targets, raw hex tokens, missing safe-area padding, allowFontScaling={false}. Apply these web-standard accessibility props to Tamagui 2 components; raw React Native components retain their React Native accessibility props.
4. Treat judgement calls as concerns, not infinite loops: complex safe-area restructuring, ambiguous brand color choices, large hierarchy redesigns, or empty-state rewrites that require large JSX movement.
5. Re-run the same report validators for touched files. Cap retries at 2 per file per validator.
6. Run npx --no-install tsc --noEmit after style fixes. Style concerns may remain, but TypeScript may not.

If auto-fixable issues remain after retries, record DONE_WITH_CONCERNS in memory-bank.md with file/rule summaries.

If verification fails because the edit exposed stale generated services, rerun the relevant data-source regeneration once before changing screens by hand. If failures are unrelated pre-existing issues, report them separately and do not hide them as successful edit results.

Step 8 — Preview + memory-bank update

Telemetry checkpoint: refresh_app_preview_and_history

Mark preview: active while regenerating preview.html, or skipped when no visible surface changed. Then build <edit-temp-dir>/app-plan-sync.json from the verified app state and mark sync-plan: active. The payload must contain complete snapshots for every changed section, including removals, plus the preview and verification notes owned by those sections. Run:

node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' sync \
  --json-file '<edit-temp-dir>/app-plan-sync.json'

After the sync succeeds, mark sync-plan: done, settle every applicable checklist row, set top-level phase: done and status: done, and run the progress command one last time, but only after the device-test handoff below has updated the phone state. Before that final progress write, reconcile each change entry with the verified app state. Update data-model tables and relationships from the final normalized contract and update screen nodes and edges from the final routes and navigation layouts. The completed edit page and docs/create-app-plan.html must describe the same final structure. If sync rendering fails, record the concern but do not misreport the app edit or verification as failed.

Before Step 8, npx --no-install tsc --noEmit must be clean after all code edits from this /edit-app run. If any code was written after Step 7's tsc, rerun npx --no-install tsc --noEmit, batch-fix root causes, and continue only when TypeScript is error-free.

If any UI, design, navigation, native interaction, or visible data state changed - or if the user explicitly asked for a preview - read and execute /preview-screens after verification with MOBILE_APP_ORCHESTRATING=1 and MOBILE_APP_EMBED_PREVIEW=1. This regenerates preview.html without opening a separate browser page. After the file is written, put the same screens in the phone rail and publish the progress page:

node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' phone --stage screens \
  --preview-file '<working_dir>/preview.html'

Keep the progress page open. It shows the screens in a sandboxed phone carousel, links to preview.html for a full-size view, and keeps the living docs/create-app-plan.html in sync through the same phone state. If the preview was skipped or generation failed, leave the phone on its current progress state and report the concern.

Unless this is --plan-only, finish with a real-device handoff. Read /create-mobile-app Step 12 from Launch command through Put the QR in the plan and execute that sequence from the same <working_dir>. Before launching, apply /debug-app Phase 0.0's project-local log, PID, and port-ownership checks to every <working_dir>/.powernative/metro-logs/metro-*-pid-*-port-*.log candidate.

• When exactly one session is live, reuse it. Read its native Metro URL from the sanitized log, verify that the URL port matches the live log's port, and do not run npm run dev.
• When no session is live, start Metro with the template-owned npm run dev and capture the URL it prints.
• When several sessions are live, or the PID, port, log, and URL disagree, show the sessions and ask which one to use. Do not start another server while the choice is unresolved.

Generate .expo/metro-qr.png from the selected URL with the pinned npx --no-install qrcode. Then update both documents through the existing phone command:

node "${PLUGIN_ROOT}/scripts/app-docs.js" --working-dir '<working_dir>' phone --stage qr \
  --qr-image '<working_dir>/.expo/metro-qr.png' --qr-url "<metro-url>"

Do not open docs/create-app-plan.html; its phone changes in the background. Run the final progress write with devicePreviewReady: true after this command succeeds so the already-open edit page replaces the screen carousel with the same QR code and shows the App Store and Google Play buttons for Power Apps Mobile Preview. If Metro or QR generation fails, keep devicePreviewReady: false; the completed edit page then shows Device preview unavailable even when the living plan contains a QR from an earlier run. Report the preview concern separately, and do not turn a verified app edit into a failure.

If the user gives a concrete runtime symptom and Metro is already running from the native dev-client flow, you may invoke /debug-app "<symptom>" after the static verification and preview steps. This is an optional symptom-debug handoff, not a verification gate: do not run screen-by-screen runtime checks, do not crawl routes, do not use React Native Web, and do not call Metro HTTP endpoints directly.

Append an edit entry to memory-bank.md:

### Edit: <yyyy-mm-dd> <short title>
- Request: <verbatim or concise summary>
- Intent brief: <target screens/routes, data surface, native capability, design scope>
- Assumptions: <inferred choices or none>
- Skills/agents invoked: <data-model-architect, screen-planner, add-dataverse, screen-builder, etc.>
- Plan sections changed: <Data Model / Native Capabilities / Screens / Design / Connectors>
- App changes: <screens/routes/native wrappers/data sources>
- Verification: <commands/gates + pass/fail/skipped with reason>
- Preview: <preview.html path or not generated>
- Debug handoff: <not requested / /debug-app "<symptom>" invoked>
- Offline retirement: <per-table not-applicable / retained with reason / pending / reconciled with verification>
- Blocks/concerns: <none or list>

Final summary must say what changed in the app, what verification ran, where the preview is, whether the living app plan was updated to reflect the latest verified changes, and whether a symptom-debug handoff was requested. Claim the plan was updated only when the final sync succeeded; otherwise state that the app edit verified but the living plan refresh failed and include that concern. Do not end by saying the codebase was not changed unless this was explicitly --plan-only. If any offlineRetirement outcome is pending, return DONE_WITH_CONCERNS and state the unfinished decision separately: "App changes completed. The offline profile still includes Orders; deciding whether to retain or remove that coverage is pending." Substitute the actual table and only claim app completion when its verification passed. Never remove profile entries automatically to clear this note.

Notes

• native-app-plan.md is still the durable source of truth. The change should be planned before it is applied, but planning is not the end state.
• For complex multi-section edits, update and gate every required section first, then apply the mutation in dependency order. Do not leave a native capability entry that references missing Dataverse storage or a screen state that was never planned.
• The architect agents are the same ones used by native-app-planner during initial creation, so planning improvements flow through here.
• This skill intentionally covers post-generation iteration. It is acceptable for /edit-app to touch Dataverse, src/native/, route layouts, screen TSX, brand tokens, preview.html, and memory-bank.md when the approved edit requires it.