setup-solution

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

setup-solution

Creates a Dataverse publisher and solution, then adds Power Pages site components. Writes .solution-manifest.json for use by export-solution, import-solution, and setup-pipeline skills.

Prerequisites

• PAC CLI installed and authenticated (pac env who returns an environment URL)
• Azure CLI installed and logged in (az account show succeeds)
• powerpages.config.json exists in the project root (site must be deployed at least once so .powerpages-site/ exists with component records)

Phases

Phase 0 — ALM plan gate

plan-alm is the front door. When the user expresses an ALM intent (promote / ship / deploy / set up CI-CD / move to staging / push to prod), the orchestrator (/power-pages:plan-alm) should run first. This Phase 0 enforces that and is meant to fail closed when there's no plan, not to be a one-time check the user can dismiss forever.

Skip rule. If this skill was invoked as part of an active plan-alm orchestration, skip Phase 0 entirely and proceed to Phase 1. The gate helper exposes this via its inExecution block — pass through silently to Phase 1 when:

inExecution.status === "active"

The helper computes this from docs/.alm-plan-data.json — PLAN_STATUS === "In Execution" AND LAST_INVOCATION_AT within the last 60 minutes. check-alm-plan.js refreshes LAST_INVOCATION_AT automatically on every invocation that finds the plan in execution, so each in-chain skill keeps the chain alive for the next one — even multi-hour deploys (deploy-pipeline alone can take 60 min per stage) survive the window without the chain incorrectly de-classifying. Stalled chains (no heartbeat for > 60 min) reclassify as stale-heartbeat and Phase 0 gates fire normally so an abandoned plan doesn't silently bypass user confirmation.

When inExecution.status is anything other than "active" ("not-running", "stale-heartbeat", "no-plan"), run the Phase 0 gate flow below. Branch on the remaining helper fields:

Step 1 — Run the gate helper.

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

The helper returns JSON with { exists, deferred, stale, staleness: { reason, detail }, generatedAt, planStatus, ... }. Sync mode (when .solution-manifest.json already exists) may additionally pass --envUrl, --token, --solutionId once Phase 1 has acquired them, but for the initial gate the existence-only check is sufficient.

Step 2 — Branch on the result.

| Result | Behavior | |---|---| | deferred: true | The user has explicitly deferred ALM for this project (.alm-deferred marker present). Pass through silently to Phase 1 — do not nag. | | exists: false | The user hasn't run plan-alm yet. See Step 3. | | exists: true, stale: false | Plan is current. Pass through silently to Phase 1. | | exists: true, stale: true (reason: solution-modified) | The solution changed after the plan was generated. See Step 4. |

Step 3 — No plan. Tell the user:

"No ALM plan exists for this project. /power-pages:plan-alm builds one — it detects the project state, asks about your promotion strategy (PP Pipelines vs Manual export/import), and orchestrates the right skills (including this one) in the right order. Want me to run plan-alm now?"

<!-- gate: setup-solution:0.no-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · setup-solution:0.no-plan): Fail-closed entry gate when check-alm-plan.js returns exists:false. Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Run /power-pages:plan-alm first? | ALM plan gate | Yes — run /power-pages:plan-alm now (Recommended), Continue without a plan (advanced — I know what I'm doing), Cancel |

• Yes (Recommended) → invoke /power-pages:plan-alm. plan-alm's Phase 7 dispatches back into this skill at the appropriate stage.
• Continue without a plan → set BYPASSED_PLAN_GATE = true and proceed to Phase 1.
• Cancel → exit cleanly.

Step 4 — Stale plan. Tell the user:

"ALM plan exists from {generatedAt} but the source solution has been modified since (at {solution.modifiedon}). Components may have changed. Re-running plan-alm will refresh the analysis and the rendered HTML."

<!-- gate: setup-solution:0.stale-plan | category=intent | cancel-leaves=nothing -->

🚦 Gate (intent · setup-solution:0.stale-plan): Fail-closed entry gate when check-alm-plan.js returns stale:true. Helper-script-backed.

AskUserQuestion:

| Question | Header | Options | |---|---|---| | Refresh the plan first? | ALM plan freshness | Refresh — re-run /power-pages:plan-alm (Recommended), Continue with the existing plan, Cancel |

• Refresh (Recommended) → invoke /power-pages:plan-alm. After completion, re-run the Phase 0 helper once to confirm freshness; if still stale, surface the detail and proceed to Phase 1 anyway (don't infinite-loop).
• Continue → set STALE_PLAN_ACK = true and proceed to Phase 1.
• Cancel → exit cleanly.

Why this gate exists. Direct invocation of setup-solution builds (or syncs) a solution without consulting the orchestrator's plan. If a plan already exists and recommends a multi-solution split, running this skill standalone may consolidate components into the wrong base solution. If no plan exists yet, plan-alm would have surfaced split recommendations, the asset-size advisory, and missing-component gaps before any solution was created — running setup-solution first burns through those decisions silently. The gate ensures setup-solution runs in the right context, while still leaving an explicit bypass for users who genuinely know they want a one-off solution.

Phase 1 — Verify Prerequisites

Create all tasks upfront at the start of this phase.

Tasks to create:

1. "Verify prerequisites"
2. "Gather solution configuration"
3. "Check existing publishers and solutions"
4. "Create publisher and solution"
5. "Add site components to solution"
6. "Verify and write manifest"
7. "Present summary"

Steps:

1. Run pac env who — extract environmentUrl, organizationId (shown to user for confirmation)
2. Run verify-alm-prerequisites.js to confirm PAC CLI auth, acquire a token, and verify API access:

``bash node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js" --envUrl "{environmentUrl}" ` Capture output as JSON; extract .envUrl (store as envUrl) and .token (store as token). If the script exits non-zero, stop and explain what is missing (reference ${CLAUDE_PLUGIN_ROOT}/references/dataverse-prerequisites.md`).

1. Locate powerpages.config.json — read siteName and websiteRecordId
2. Confirm .powerpages-site/ folder exists (required to find component records)
3. Check for ALM plan context — look for docs/alm/alm-plan-context.json:

<!-- gate: setup-solution:1.preloaded | category=plan | cancel-leaves=nothing --> > 🚦 Gate (plan · setup-solution:1.preloaded): Use pre-loaded plan classifications, or re-discover. No write happens before this choice.

• If found, ask via AskUserQuestion:

> "An ALM plan was previously generated for this site. It includes a pre-classified list of site settings (keepAsIs, promoteToEnvVar, authNoValue, excluded). Would you like to use those choices, or re-discover and re-classify everything now?"

• Options: "Use pre-loaded choices from plan" / "Re-discover and re-classify"
• If user chooses pre-loaded: read docs/alm/alm-plan-context.json, store the siteSettings object as preloadedSettings. When Step 5.3 is reached, skip the query and classification logic — use preloadedSettings directly.
• If user chooses re-discover: proceed normally (Steps 5.3–5.4 query Dataverse and reclassify).
• Detect sync mode — check