---

name: publish-pcf-companion description: Deploy the dispatcher PCF for a third-party .ppmplugin control to a Power Platform environment via pac pcf push. The dispatcher PCF is the Studio-side control that dispatches the composite key <name>/<receiver> over the wrap shell's SendMessagePlugin bridge to the control's native module. Verifies deploy prereqs (Node.js 20+ with npm, .NET SDK, and active pac auth), then three confirmation gates — publisher prefix (2–8 chars; defaults to pamext or the last-used value from .extension-state.md), version bump (patch / minor / major / no-bump), target environment URL (from pac org who). Builds the PCF if needed, then pushes. Decoupled from /generate-pcf-companion so the engineer can scaffold and customize locally, then deploy when ready. Updates .extension-state.md with deployment history (timestamp, env URL, version, prefix used). allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill model: sonnet

/publish-pcf-companion

On-demand deployment of the dispatcher PCF for a third-party .ppmplugin control to a Power Platform environment. The dispatcher PCF is the Studio-side control that dispatches the composite key <name>/<receiver> over the wrap shell's SendMessagePlugin bridge to the control's native module. Runs pac pcf push against the user's active pac auth profile. Decoupled from /generate-pcf-companion — the engineer scaffolds locally, customizes / iterates, then deploys when ready.

---

Step 1 — Read shared docs and verify prereqs

1. Read shared/shared-instructions.md, shared/naming-conventions.md.

2. Apply the per-skill minimal prereq policy (shared-instructions.md §1.5). This skill needs Node.js 20+ with npm, pac CLI, .NET SDK, and an active pac auth profile. It does not need pnpm.

   Print the prereq status as a visible block per shared-instructions.md §9.2 before continuing:

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    Prereq check — /publish-pcf-companion
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
    🟢 ✓ Node.js 20+ and npm installed       (for npm install / npm run build)
    🟢 ✓ pac CLI installed                   (for pac pcf push)
    🟢 ✓ .NET SDK installed                  (solution build runs inside pac pcf push)
    🟢 ✓ pac auth profile active             (target env: <env URL from pac org who>)
   
    🟢 4 checks passed. Ready to proceed.
   

   Fix table for failures:

   | Missing | → Fix: line in the failure block | |---|---| | Node.js / npm | Install Node.js 20 LTS from https://nodejs.org, then verify with node -v and npm -v | | pac CLI | dotnet tool install -g Microsoft.PowerApps.CLI.Tool (chains on .NET SDK first if also missing) | | .NET SDK | brew install dotnet (mac) / winget install Microsoft.DotNet.SDK.10 (win) / package manager (linux) | | No active pac auth | pac auth create --environment <your-env-url> (interactive browser flow; use an identity with access to the target Power Platform environment). Do not reach for --deviceCode first — it's a headless-shell fallback that commonly fails under Conditional Access. |

   Run the /publish-pcf-companion check from prereq-check.md. Per the auto-fix policy (shared-instructions §1.5): a missing pac CLI is auto-fixable when .NET is present — offer dotnet tool install -g Microsoft.PowerApps.CLI.Tool and continue on yes; no active pac auth → initiate pac auth create --environment <url> (browser) and verify after. If an auth attempt fails, walk the variant ladder in prereq-check.md (browser → device code only if headless → back to browser with --environment → pac auth clear) — change a variable each step and never re-run a variant that already failed. A missing .NET SDK hard-stops (system-wide install — print the command).

3. Read ./PRD.md. Required — the skill derives the PCF folder name (pcf/<Pascal>PCF/) and publisher prefix from PRD §2. If PRD is missing, STOP with BLOCKED: PRD.md missing — cannot determine PCF folder name.

4. Read ./.extension-state.md if present. The state file is informational; this skill works without it but uses Phase info to surface "scaffold-pcf hasn't happened yet" early.

---

Step 2 — Detect current state

Build a status dashboard so the user sees what was detected before any action.

Discover the PCF folder robustly — don't assume the exact nesting depth. Use Glob to find pcf/**/ControlManifest.Input.xml and select the first match. pac pcf init normally produces pcf/<Pascal>PCF/<Pascal>PCF/ControlManifest.Input.xml, but case differences and manual restructuring should not break discovery. If pcf/ is absent, stop with BLOCKED: no pcf/ directory — PCF has not been scaffolded. Run /generate-pcf-companion first. If pcf/ exists but the manifest is absent, list the relevant files with Glob and stop with BLOCKED: pcf/ exists but no ControlManifest.Input.xml was found.

Derive the PCF project root from the manifest path by moving up two directory levels. Use Glob to check whether <PCF_PROJECT_ROOT>/out/ exists. Use Read to extract the <control version="X.Y.Z"> value from the manifest and the latest deployment version from .extension-state.md. Run pac org who to retrieve the active environment because that is a real toolchain command.

Print:

PCF deploy status
─────────────────
Repo: <cwd>
PCF project root: <PCF_PROJECT_ROOT from find>
Manifest: <MANIFEST path>
Built (out/): <yes | no — will build now>
Current manifest version: <CURRENT_VERSION>
Last deployed version: <LAST_DEPLOYED or "none — first deploy">
Publisher prefix: <LAST_PREFIX from .extension-state.md, else `pamext` default — confirmed in Step 3.0>
Active pac auth env: <env URL from `pac org who`>
Active pac auth user: <user from `pac org who`>

Plan: pick publisher prefix → bump version if chosen → build if needed → pac pcf push --publisher-prefix <chosen prefix>

Why the version matters: Power Platform caches PCF controls by version in deployed apps. If you re-push the same version, apps that already loaded the previous bundle may not see your changes until their cache invalidates (timing varies — sometimes minutes, sometimes hours, sometimes never until the maker re-publishes the app). Best practice is to bump the patch version on every meaningful push.

If pac org who returns "No active connection": STOP — this means pac auth list showed a profile but it's not currently selected. Run pac auth select --index <n> and re-run this skill. (Step 1 catches missing auth; this catches the rarer "auth exists but not active" case.)

Why Glob instead of an exact path: the standard layout is nested two levels below the project root, but case differences, manual restructuring, and non-standard scaffolders occur. Glob provides OS-neutral discovery without assuming a fixed path.

---

Step 3 — Confirm with the user

This step has THREE gates: publisher prefix → version-bump → deploy confirmation. Each is its own AskUserQuestion.

3.0 — Publisher prefix gate

The publisher prefix becomes part of the solution name in Power Platform (e.g. pamext_<Pascal>PCF). It must be 2–8 characters — pac pcf push rejects anything outside that range with Argument --publisher-prefix has incorrect length.

Use Read on .extension-state.md and extract the most recent Publisher prefix: <value> entry. If the file or entry is absent, use pamext as the default.

Then ask via AskUserQuestion:

Publisher prefix for this deployment? (must be 2–8 lowercase chars)

• <LAST_PREFIX> (use the prefix from the previous deployment) — only shown if LAST_PREFIX was found
• pamext (recommended) — 6 chars; "PAM Extension"; the default we suggest for first-party native-extension PCFs
• mspa — 4 chars; "Microsoft PowerApps"
• Custom — supply your own 2–8-char prefix (free-text input, validate length before continuing)

Validate the chosen value:

PREFIX="<from user choice>"
PREFIX_LEN=${#PREFIX}
if [ "$PREFIX_LEN" -lt 2 ] || [ "$PREFIX_LEN" -gt 8 ]; then
  echo "❌ Publisher prefix '$PREFIX' is $PREFIX_LEN chars; must be 2–8. Try again."
  # Re-prompt
fi
if ! [[ "$PREFIX" =~ ^[a-z][a-z0-9]*$ ]]; then
  echo "❌ Publisher prefix must start with a lowercase letter and contain only lowercase letters and digits."
  # Re-prompt
fi

Why the prefix matters: it groups your PCF with other solutions under the same publisher identity in Power Platform's solution explorer. Use the same prefix across all first-party native-extension PCFs so they appear together. The recommended pamext is a project convention — your team may have its own; ask before picking custom on a shared environment.

Why we don't hardcode it: the team / environment may have an existing publisher prefix established. Hardcoding "powerapps" was wrong on two counts — it's 9 chars (over the limit) AND it doesn't respect environment conventions.

3.1 — Version-bump gate

Use AskUserQuestion. Compute the bump-target options from CURRENT_VERSION (the version currently in the manifest):

Current PCF version: <CURRENT_VERSION> (last deployed: <LAST_DEPLOYED or "never">)

Power Platform caches PCFs by version. Re-pushing the same version may not invalidate caches in apps that already use this control. Bump the version?

• Patch bump → <CURRENT major.minor.(patch+1)> (recommended for bug fixes, internal improvements) — typical default
• Minor bump → <CURRENT major.(minor+1).0> (for new features or new outputs/configurable inputs the maker can opt into)
• Major bump → <(CURRENT major+1).0.0> (for breaking changes to the bound input, output names, or trigger semantics)
• No bump — push as-is at <CURRENT_VERSION> (only if you're iterating during initial dev and accept the cache risk; the skill will print a warning)

Apply the chosen bump with the Edit tool by replacing only the <control version="..."> attribute in the manifest. Show the exact version change (<CURRENT_VERSION> → <NEW_VERSION>) before writing and preserve every other manifest field.

After bumping, re-build is required (the manifest changed, so out/ is stale). The build runs as part of Step 4 regardless of the user's choice in 3.2 below, so this is fine.

If user picked "No bump": skip the manifest edit. Print a warning:

⚠️ Pushing at <CURRENT_VERSION> again. Apps that previously loaded this control may not see your changes until their PCF cache invalidates. Use a version bump for the next push if this matters.

3.2 — Deploy confirmation gate — lead with the ENVIRONMENT

Wrong-env deploys are a confirmed failure mode (a publish once went to wrap-bug-bash-env instead of wrap-player-test-env because the env URL was buried in a long question). So make the target environment the headline of this gate, and explicitly offer to change it — never silently reuse whatever pac auth happens to be active. Show the FULL current-env details (not just the URL) so the user can tell which env it is: read pac org who (and pac auth list for the friendly profile name) and print:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ►► CURRENT DEPLOY TARGET ◄◄
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Environment:   <friendly org name from `pac org who` — e.g. "Contoso Test (default)">
 URL:           <env-url>
 Environment ID:<org/environment id from `pac org who`, if shown>
 Signed-in as:  <user from `pac org who`>
 Auth profile:  <active profile name from `pac auth list` (the ★ row)>
 Last deployed: <from .extension-state.md PCF deployments — env + timestamp, or "first deploy">
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━