canvas-app

# Create or Edit a Canvas App

Create or edit a Power Apps canvas app for:

$ARGUMENTS

## Establish the Workspace

Canvas Authoring tools operate on a local directory containing the app YAML.

1. Reuse the current directory when it already contains `App.pa.yaml`.
2. Otherwise, reuse the single immediate child directory containing `App.pa.yaml`, when
   exactly one exists.
3. Otherwise, derive a short kebab-case folder name from the app name or requirements,
   create it with `Bash`, and resolve its absolute path.
4. Call `sync_canvas` with that absolute working directory before reading or editing app
   files. Do not proceed if sync fails.

Always use absolute paths for app files. Never edit `_EditorState.pa.yaml`; Studio owns it.

## Route the Request

Inspect the synced `.pa.yaml` files before choosing a workflow. A blank app normally contains
`App.pa.yaml`, `Screen1.pa.yaml`, and `_EditorState.pa.yaml`.

Treat the app as empty when it has no screens with meaningful leaf controls. Containers
without leaf controls do not make the app non-empty.

- **Empty app:** read `${PLUGIN_ROOT}/references/CreateWorkflow.md` and follow it.
- **Existing app:** read `${PLUGIN_ROOT}/references/EditWorkflow.md` and follow it.

Do not load both workflow documents.

## Planned Build Handoff

CREATE and complex EDIT workflows return here after the planner finishes.

1. Read `[working directory]/canvas-app-plan.md` returned by the planner.
2. Verify its `## Requirement Coverage` table maps every concrete requested noun and
   interaction to a visible affordance. Any approximation must be explicit and must not
   use UI copy that claims the unavailable interaction is exact.
3. Verify its `## Action Contracts` table:
   - Every requested or approved action has its own row and reachable entry point.
   - Create, edit, delete, search, filter, approve, reject, period, and export behaviors
     are not collapsed into vague combined rows.
   - When review distinguishes approved and rejected outcomes, Approve and Reject/Decline
     have separate contracts owned by the same eligible record surface.
   - Every mutation names an observable bound result, not only a confirmation message.
   - Every mutation declares a write set and receipt proof set. For create/edit, reject the
     plan when any user-entered or user-selected write-set field is absent from the proof set.
   - Supporting setup actions exist when required to exercise an explicitly requested
     lifecycle, relationship, comparison, or ranking.
   - Role-scoped management of all primary records includes separate visible select/edit/save
     and remove/cancel paths, not only review or status controls.
   - Create/edit contracts define required inputs, directly selectable finite choices,
     stable identity, edit prepopulation, cancel/reset behavior, and post-save evidence.
   - Every row names a precondition, source and stable identity, exact transition and
     postcondition, observer reading that source, and visible evidence.
4. Verify its `## Functional Test Matrix`:
   - Every Action Contract has at least one deterministic Given/When/Then success row.
   - Every required invalid, blocked, empty, clear/reset, or boundary path has a row.
   - Every `Then` names a source postcondition and an evidence surface that reads it.
   - Local/mock scenarios use concrete seeded IDs and values. Filter scenarios include at
     least two matching records and one non-matching record.
   - EDIT scenarios cover existing behavior touched by changed sources, fields, controls,
     or observer formulas.
5. Verify its `## Dispatch` table:
   - Every row has `Action`, `Screen`, `Target File`, `YAML Key`, `Name Prefix`, and
     `Screen Brief`.
   - CREATE rows use `Create`; EDIT rows use `Modify` or `Create`.
   - Target files and screen briefs are absolute paths under `[working directory]`.
   - No two rows target the same file.
   - No two rows share a `Name Prefix`.
   - In CREATE mode the first row targets `[working directory]/Screen1.pa.yaml` with YAML key `Screen1`.
   - `## Editor State Changes` exists and contains exact final order lists or `None`.
6. Confirm `[working directory]/canvas-app-shared.md` and every dispatch row's `Screen Brief` exists.
   Verify each brief's assignment matches its dispatch row and includes every Action
   Contract owned by that screen under `## Required Actions` and every scenario it
   exercises under `## Functional Test Scenarios`.
7. In EDIT mode, apply the `### Before builders` group of `## App Changes` to
   `[working directory]/App.pa.yaml` now. Screens bind to those collections, formulas and variables, and
   compiling them against a stale `App.pa.yaml` produces a flood of false name errors.
8. Confirm the planner reported a clean `compile_canvas` for `[working directory]/App.pa.yaml`. If it
   did not, compile now and resolve every `App`-level diagnostic before dispatching.
   For EDIT mode, compile after applying the before-builder app changes and resolve
   App-level diagnostics before dispatching.
9. Invoke `canvas-screen-builder` once per dispatch row, in waves of
   **at most three**. Fire the wave's invocations together in one message, wait for that
   wave to return, then dispatch the next.

Never dispatch more than three builders at once. Larger fan-outs have hung without
returning, and waves of three get you the first compile sooner, which is where systemic
defects surface.

If any pre-dispatch check fails, do not start builders. Re-invoke the planner with the
specific defects and repeat the checks on the corrected artifacts.

Pass each builder only:

```text
Action: [Create / Modify]
Screen: [logical screen name]
Target file: `[working directory]/[file].pa.yaml`
YAML screen key: [key from dispatch row]
Control name prefix: [prefix from dispatch row]
Shared plan: `[working directory]/canvas-app-shared.md`
Screen brief: `[working directory]/[file-base].screen-plan.md`
Plugin root: ${PLUGIN_ROOT}
```

The target file,