edit-app

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.

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"

When NOT to use

• Brand-new project → /create-mobile-app
• Just adding one connector with no screen changes → /add-connector directly
• Just adding a single native wrapper with no screen changes → /add-native directly
• The plan file is missing → re-run /create-mobile-app (don't try to reconstruct)

Workflow

0. Locate app + health/drift probe → 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 app mutations → 6. Rebuild affected screens → 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 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

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

test -f native-app-plan.md && echo "OK: plan found" || echo "ERROR: no plan"
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 native-app-plan.md is missing → STOP. Tell the user this skill edits an existing generated app; they should re-run /create-mobile-app on a fresh template or manually recreate the plan before using this editor.

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:

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 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 1 — Discover intent + inspect existing app

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:

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.

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"

Then ask: "Briefly describe the change you want."

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, cloud flow/action, or another connector? Which screen(s), if any, should use it now?
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 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
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.

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, route through /add-datasource rather than guessing.
• 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; Data Model: Image/File column or child Evidence/Signature table; Screens: capture action, preview state, cancelled state, upload failed state
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 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 and execute the /design-system skill instead of spawning a planner agent. 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.

After /design-system --refresh returns, print:

✅ Design system updated. brand/design-system.md + brand/tokens.ts refreshed.

Continuing with verification and preview. Rebuilding screens only if component shapes, density, navigation, or screen-specific design rules changed.

Do not stop after design refresh. Continue to Step 7 verification and Step 8 preview. If the refresh changed component shapes, density, negatives, or a full reskin requires TSX adjustments, include Screens in the affected sections and rebuild those screens.

Step 2 — Re-plan affected sections

Telemetry checkpoint: revise_affected_app_plan

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.

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: