/add-cloud-flow

name: add-cloud-flow
description: >-
  Integrates Power Automate cloud flows into a Power Pages site. Lists available flows,
  suggests relevant ones based on intent, identifies scenarios and web roles, creates metadata
  files, and generates client-side code to call flows. Handles both new flow registration and
  adding already-registered flows to additional pages without re-creating metadata. Use when
  the user wants to add, connect, register, or link a Power Automate cloud flow to their site.
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill, Task, TaskCreate, TaskUpdate, TaskList
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Add Cloud Flow

Connect one or more Power Automate cloud flows to a Power Pages SPA site, or wire already-registered flows into additional pages/components. For new flows this skill:

• Creates the `adx_cloudflowconsumer` metadata YAML in `.powerpages-site/cloud-flow-consumer/`
• Assigns web roles based on the flow's scenario and target audience
• Generates client-side TypeScript/JavaScript service code to trigger the flow with CSRF authentication

For already-registered flows, the skill skips metadata and role creation and goes straight to client-side integration — wiring the existing flow into new UI locations.

Core Principles

• **Multiple flows in one run**: The user can add several flows at once. All flows are planned together and implemented together before asking for deployment.
• **Ask before acting**: Present a full HTML plan (all flows, roles, reasoning) before creating any files.
• **Web roles drive access**: Every flow must have at least one web role. Anonymous Users role is valid but must be confirmed.
• **Scenario determines roles**: Understand what each flow does and who triggers it before picking roles.
• **Use TaskCreate/TaskUpdate**: Track all phases upfront before starting any work.
• **Preserve site integrity**: Before wiring a flow into a page or component, read `${PLUGIN_ROOT}/references/site-modification-integrity.md`; localize every new visible state when configured and keep the UI bidirectional and expansion-safe.

> **Prerequisites:** > - An existing Power Pages SPA site with `.powerpages-site` deployed > - PAC CLI authenticated (`pac auth who` must succeed) > - Azure CLI authenticated (`az login --allow-no-subscriptions` works whether or not your account has an Azure subscription — Dataverse and Power Platform tokens are AAD-scoped)

**Initial request:** $ARGUMENTS

---

Workflow

1. **Verify Prerequisites** — Locate the project, confirm `.powerpages-site` exists, inventory web roles and existing flows 2. **List Available Flows** — Fetch flows from the Power Automate Flow RP API 3. **Select Flows & Understand Scenarios** — User picks one or more flows; determine scenario and audience for each 4. **Determine Web Roles** — Propose minimum roles per flow with reasoning 5. **Review Plan** — Render HTML plan for all flows; get user approval 6. **Create Metadata** — Write `.cloudflowconsumer.yml` for each flow; create missing web roles first 7. **Client-Side Integration** — Generate typed service code to call each flow from the frontend 8. **Verify & Summarize** — Validate all YAMLs, record skill usage, offer deployment

---

Phase 1: Verify Prerequisites

**Goal**: Locate the Power Pages project and confirm all prerequisites are met

**Actions**:

1. Create todo list with all 8 phases (see [Progress Tracking](#progress-tracking) table)

1.1 Locate Project

Look for `powerpages.config.json` in the current directory or immediate subdirectories.

**If not found**: Tell the user to create a site first with `/create-site`.

1.2 Read Config

Read `powerpages.config.json` to get the `siteName` (used for display and plan rendering).

1.3 Check `.powerpages-site` Exists

Look for the `.powerpages-site` folder in the project root.

**If not found**:

<!-- gate: add-cloud-flow:1.3.deploy-first | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · add-cloud-flow:1.3.deploy-first):** `.powerpages-site` missing — cloud flow YAML lives inside it. Deploy first or stop. > > **Trigger:** Phase 1.3 found no `.powerpages-site` directory. > **Why we ask:** Cloud flow YAML written to a non-existent path will never deploy. > **Cancel leaves:** Nothing — no YAML files written.

Use `AskUserQuestion`:

| Question | Options | |----------|---------| | `.powerpages-site` is required to add cloud flows. Would you like to deploy the site now? | Yes, deploy now (Required), Cancel |

**If "Yes, deploy now"**: Invoke `/deploy-site` first, then continue to Phase 2. **If "Cancel"**: Stop.

1.4 Read Existing Web Roles

Read all `.webrole.yml` files from `.powerpages-site/web-roles/` to inventory available roles. Note each role's `id`, `name`, `adx_anonymoususersrole`, and `adx_authenticatedusersrole`.

1.5 Check Existing Cloud Flows

Check `.powerpages-site/cloud-flow-consumer/` for existing `.cloudflowconsumer.yml` files. For each file, read:

• `processid` — the flow's `workflowEntityId`
• `name` — the flow's display name
• `adx_CloudFlowConsumer_adx_webrole` — assigned web role UUIDs

Store these as the **already-registered flows** list. These flows already have metadata and web roles configured but may need additional frontend integration on other pages or components.

1.6 Detect Frontend Framework

Read `package.json` to detect the framework (React, Vue, Angular, Astro). Note the framework and its conventions for Phase 7. See `${PLUGIN_ROOT}/references/framework-conventions.md` for the detection mapping.

**Output**: Project root, site name, framework, available web roles, already-registered flows (with processid, name, and web roles)

---

Phase 2: List Available Flows

**Goal**: Fetch all Power Automate cloud flows that have a PowerPages trigger

**Actions**:

Run