create-code-app

**📋 Shared Instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** - Cross-cutting concerns.

**References:**

- [prerequisites-reference.md](./references/prerequisites-reference.md) - Prerequisites and required permissions
- [troubleshooting.md](./references/troubleshooting.md) - Common issues, npm scripts, resources

# Create Power Apps Code App

## Workflow

1. Prerequisites → 2. Gather Requirements → 3. Plan → 4. Scaffold → 5. Initialize → 6. Build & Deploy (baseline) → 7. Add Data Sources → 8. Implement App → 9. Final Build & Deploy → 10. Summary

---

### Step 0: Check Memory Bank

Check for `memory-bank.md` per [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md). Skip completed steps.

### Step 1: Validate Prerequisites

Run prerequisite checks **first** -- no point gathering requirements if the environment isn't ready. See [prerequisites-reference.md](./references/prerequisites-reference.md) for details.

Check Node.js and Git (runs natively in bash):

```bash
node --version   # Must be v22+
git --version    # Optional but recommended
```

- **Missing Node.js**: Report "Install Node.js v22+ from https://nodejs.org/" and STOP.
- **Node.js below v22**: Report "Node.js 22+ is required. Please upgrade or switch with `nvm use 22`." and STOP.
- **Missing Git**: Report "Recommended but optional." Continue if approved.
- **All present**: Report versions and proceed.


### Step 2: Gather Requirements

**Skip questions the user already answered in their initial instruction.**

**If the user has not described what they want to build** (i.e., `/create-code-app` was invoked with no arguments or a vague prompt), start with a single open-ended question before asking anything else:

> "What would you like to build? Describe it in your own words — what it does, who uses it, and what problem it solves."

Wait for their answer. Use it to frame all follow-up questions. Do NOT present a multiple-choice list of app types before the user has described their idea.

Once you have their description:

1. Confirm the app name and clarify the purpose if needed
2. Ask about data -- focus on **what the app needs to do**, not specific technologies:
   - "What data does your app need to work with?" (e.g., company emails, project tasks, custom business records)
   - "Does your app need to search existing information, manage its own data, or both?"
   - Based on their answers, recommend the best approach:
     - **Store and manage custom business data** (tables, forms, CRUD) → Dataverse (`/add-dataverse`)
     - **Interact with specific services** (send emails, post messages, manage files) → the appropriate connector
     - **Search M365 data or get AI-powered answers** (emails, files, people, company knowledge) → Work IQ (`/add-workiq`)
   - If they mention existing Dataverse tables, SharePoint lists, or connectors by name, use those directly
3. Ask about UI requirements: key screens, layout, interactions, theme preference
4. Ask any clarifying questions now -- resolve all ambiguity before entering plan mode

### Step 3: Plan

1. Enter plan mode with `EnterPlanMode`
2. Design the full implementation approach:
   - Which `/add-*` skills to run for data sources
   - App architecture: components, pages, state management
   - Feature list with priority order
3. Present plan for approval, include `allowedPrompts` from [prerequisites-reference.md](./references/prerequisites-reference.md)
4. Exit plan mode with `ExitPlanMode` when approved

### Step 4: Scaffold

Ask the user for a folder name. Default to `powerapps-{app-name-slugified}-{timestamp}` if they don't have a preference.

**IMPORTANT: Use `npx degit` to download the template. Do NOT use `git clone`, do NOT manually create files, do NOT download from GitHub UI. `degit` downloads the template without git history.**

```bash
npx degit microsoft/PowerAppsCodeApps/templates/vite {folder} --force
cd {folder}
npm install
```

**Notes:**

- Use `--force` to overwrite if the directory already has files (e.g., `.claude` from a planning session)
- If targeting an existing directory, use `.` as the folder name: `npx degit microsoft/PowerAppsCodeApps/templates/vite . --force`
- If `npx degit` fails (network issues, npm not found), retry once, then ask the user to run manually

Verify: `package.json` exists, `node_modules/` created.

### Step 5: Initialize

> Resolve the CLI first (see [cli-binary.md](${PLUGIN_ROOT}/shared/cli-binary.md)): run as `$PA app init …` (`npx --no-install pa …`), never a bare `pa`. On `power-apps`-only projects, translate to `power-apps init …` (the `init` verb and its `-n`/`-e` flags are unchanged on both binaries).

```bash
pa app init -n '{user-provided-app-name}' -e <environment-id>
```

**Finding the environment ID:** It's the GUID in the make.powerapps.com URL: `https://make.powerapps.com/environments/<env-id>/home`. If you don't pass `-e`, the CLI will prompt for it interactively.

**Authentication:** On first run, a browser window opens for Microsoft sign-in. Complete the login and the command continues. No separate auth setup is needed.

See [preferred-environment.md](${PLUGIN_ROOT}/shared/preferred-environment.md) for environment selection details.

**`pa app init` failure:**

- Non-zero exit: Report the exact output and STOP. Do not continue to Step 6.
- "environmentId not found" or environment validation error: Verify the environment ID is correct and the user has maker permissions in that environment, then retry.
- Example: _"The `pa app init` command failed: `[error text]`. Please check that environment ID `32a51012-...` is correct and that you have maker permissions in that environment."_

**Critical:** Read `power.config.json` after init and verify `environmentId` is set correctly.

### Step 6: Build & Deploy (baseline)

> **Pre-approved**: This baseline deploy is part of the scaffold flow and does not require a separate confirmation prompt.

Build and deploy the bare template to