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

plan-alm

An 8-phase orchestrator that gathers ALM strategy from the user, generates an HTML deployment plan, gets approval, then executes the plan by calling existing skills in sequence.

Overview

This skill detects the current project state (existing solution, pipeline), asks targeted questions about the desired promotion strategy (Power Platform Pipelines or Manual export/import), generates a visual docs/alm-plan.html, gets user approval, and then invokes setup-solution, setup-pipeline (or export-solution), and deploy-pipeline (or import-solution) in the correct order.

Do NOT create tasks at the start — strategy is unknown until Phase 2 completes. Create all tasks in Phase 3 once the strategy is determined.

Phase 1 — Detect Project State

Do NOT create tasks yet. Use natural language progress reporting only during this phase.

Steps:

0. Detect prior ALM deferral for this project. Before any discovery work, check whether the project root contains a .alm-deferred marker file. The marker is written by users who explicitly opted ALM-skill validators out of "missing artifacts" warnings (e.g. "this site is handled separately" or "ni-dev — no ALM"). If a user is now invoking plan-alm, we should surface that the marker is present and ask what to do, rather than silently proceeding (which would build a plan the user previously decided not to maintain) or silently removing the marker (which would re-enable nags on every other ALM skill).

   node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/check-alm-plan.js" --projectRoot "."
   

   <!-- gate: plan-alm:1.deferral | category=progress | cancel-leaves=deferral-marker -->

   🚦 Gate (progress · plan-alm:1.deferral): .alm-deferred marker present — continue and remove, continue and keep marker, or cancel. Determines whether downstream ALM skills resume gate enforcement.

   The helper returns { deferred, deferral, ... }. If deferred === true, read the deferral reason (deferral.reason or the raw marker text) and ask via AskUserQuestion:

   "This project has an .alm-deferred marker — {reason}. ALM was previously deferred here, so the other ALM skills (setup-solution, setup-pipeline, deploy-pipeline, …) skip their plan-completeness checks for this project. How would you like to proceed?"

   Question	Header	Options
   How would you like to proceed?	ALM deferral marker	Continue planning and remove the marker (Recommended), Continue planning but keep the marker (record deferral context in plan), Cancel

   • Continue and remove marker (Recommended) → delete .alm-deferred (the user is re-engaging with ALM). Set DEFERRAL_CLEARED = true and proceed to step 1.
   • Continue and keep marker → set DEFERRAL_PRESERVED = true and DEFERRAL_REASON = {reason}. Proceed to step 1. Surface a one-line note in the Phase 1 step 9 user report (e.g. "Note: .alm-deferred is preserved — other ALM skills will continue to skip plan-completeness checks for this project.") so the user remembers the marker remains in effect after planning.
   • Cancel → exit cleanly (don't touch the marker).

   If deferred === false, skip this step silently and proceed to step 1.

1. Resolve the site identity from the local project. ALM skills are normally invoked from a site-root directory where pac pages download-code-site (or a create-site scaffold followed by a deploy) has written .powerpages-site/website.yml. That YAML file is the source of truth for websiteRecordId and siteName.

   Resolution order (first match wins):

   1. .powerpages-site/website.yml (preferred, present for every deployed site) — read with the Read tool and extract:
      • id field → websiteRecordId
      • name field → siteName (the file uses short keys; it is name:, not adx_name:)
   2. powerpages.config.json (fallback, used during plugin development from this repo root or for sites scaffolded but not yet deployed) — read siteName and websiteRecordId.

   If neither is found, stop with:

   "No Power Pages site found in the current directory. Run this skill from your site project root (where .powerpages-site/ exists after pac pages download-code-site). If you haven't created the site yet, run /power-pages:create-site first."

   environmentUrl is always re-confirmed from pac env who in step 4 — it does not need to come from either source.

2. Check for .solution-manifest.json in the project root:

   • Store SOLUTION_DONE = true if found, false otherwise
   • If found, read solution.uniqueName and store as SOLUTION_UNIQUE_NAME

3. Check for docs/alm/last-pipeline.json in the project root:

   • Store PIPELINE_DONE = true if found, false otherwise
   • If found, read pipelineName and stages[] for later use

4. Run silently:

   pac env who
   

   Capture the Environment URL and display name. Store as DEV_ENV_URL and DEV_ENV_NAME.

5. Run silently:

   pac env list --output json 2>/dev/null
   

   Store output as ENV_LIST for pre-filling environment URLs in Phase 2.

6. Acquire dev environment token (silently):

   node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js" --envUrl "{DEV_ENV_URL}"
   

   Store .token as DEV_TOKEN and .userId as userId. If this fails (auth error), set DEV_TOKEN = null and continue — contents discovery will be skipped gracefully.

7. Discover and classify site settings (if DEV_TOKEN is available and websiteRecordId is known):

   Use Node.js https module to query. Paginate via @odata.nextLink — sites with > 500 settings would otherwise silently truncate, dropping tier classifications and underreporting plannedEnvVarCount. Send Prefer: odata.maxpagesize=5000 so Dataverse emits the continuation link, then loop until exhausted:

   GET {DEV_ENV_URL}/api/data/v9.2/mspp_sitesettings?$filter=_mspp_websiteid_value eq '{websiteRecordId}'&$select=mspp_name,mspp_value&$top=5000
   Authorization: Bearer {DEV_TOKEN}
   Prefer: odata.maxpagesize=5000
   OData-MaxVersion: 4.0
   OData-Version: 4.0
   Accept: application/json
   

   On each response, append value[] to the running array. If @odata.nextLink is present, GET that URL with the same headers (no need to re-add the filter — the nextLink already encodes the query). Stop when the response has no @odata.nextLink. Cap at 100 iterations for safety.

   Classify the returned settings using ${CLAUDE_PLUGIN_ROOT}/scripts/lib/classify-site-settings.js — the single source of truth for the credential regex and tier mapping shared with setup-solution Phase 5. Either pipe the JSON array of {name, value} rows into the script's stdin (CLI mode) or require() it inline:

   echo '<JSON array of {name,value}>' \
     | node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/classify-site-settings.js"
   

   Output (the four-bucket shape that downstream phases + setup-solution consume directly):

   SITE_SETTINGS_DATA = {
     keepAsIs: [{name}],                          // regular settings (Tier 3 — Search/Bootstrap/WebApi/feature flags)
     authNoValue: [{name}],                       // Authentication/* or AzureAD/* with empty value (Tier 2b — added as-is, set in target env)
     promoteToEnvVar: [{name, value}],            // Authentication/* or AzureAD/* with value (Tier 2a — setup-solution offers env-var promotion)
     credentialNeedsDecision: [{name, value}]     // ConsumerKey/ConsumerSecret/ClientId/ClientSecret/AppSecret/AppKey/ApiKey/Password (Tier 1 — bulk-with-override prompt in setup-solution Phase 5.4.C)
   }
   

   Tier semantics in plain English (so reviewers reading the plan know what each bucket implies):

   • **Tier 1 (`credenti