1# Azure VM/VMSS Creator
2 
3Guided create-flow for Azure Virtual Machines (VMs) and VM Scale Sets (VMSS). Adapts to the user's expertise — beginners get sensible defaults; networking/spec/cost/security experts get the deep questions for their domain only — then emits the chosen artifact: az CLI bash, Bicep, Terraform, or live apply via Azure MCP.
4 
5## When to use
6 
7- User wants to **create / provision / deploy / spin up** a VM or VMSS (not just pick a SKU)
8- User has a recommendation in hand and wants a deployable artifact
9- User asks for a "create VM" script, template, or commands in az CLI, Bicep, or Terraform
10 
11> **Disambiguator.** If the user wants to deploy an **application** (Docker service, web app, API, function), route to `azure-prepare`. This workflow is for **bare VM/VMSS infrastructure** only.
12> **Recommender first.** If the user has not picked a SKU yet ("what should I pick?"), pause and run [vm-recommender](../vm-recommender/vm-recommender.md) Steps 1–6 first, then resume here.
13 
14## Workflow
15 
16### Step 1 — Determine VM vs VMSS
17 
18If the user already said "VM" or "VMSS" / "scale set", use that. Otherwise: autoscaling, multiple identical instances, or stateless tier behind a load balancer → **VMSS**; everything else → **VM**. If unsure, default to single VM and ask one confirmation.
19 
20### Step 2 — Depth Probe
21 
22Classify the user's first 1–2 messages against the signal table in [depth-probe/index.md](references/depth-probe/index.md) and pick the highest-scoring branch:
23 
24| Branch | File |
25|---|---|
26| Beginner / fast-path | [beginner.md](references/depth-probe/beginner.md) |
27| Networking-deep | [networking-deep.md](references/depth-probe/networking-deep.md) |
28| Spec-deep | [spec-deep.md](references/depth-probe/spec-deep.md) |
29| Cost-deep | [cost-deep.md](references/depth-probe/cost-deep.md) |
30| Security-deep | [security-deep.md](references/depth-probe/security-deep.md) |
31 
32> Never ask a question whose answer can be inferred or safely defaulted. Batch silent inferences into the Plan Card so the user can see and edit them.
33 
34### Step 3 — Adaptive Gather
35 
36Ask **only** the questions from the matched branch's matrix. Use the defaults ladder when asking:
37 
38> *"NSG inbound rules — `[Recommended: SSH from your IP only]` / `[Show alternatives]` / `[I have specifics]`"*
39 
40Cross-branch follow-ups (once, after the primary branch):
41- Resource group (existing or new — propose `<vm-name>-rg`)
42- Tags (accept "none" without follow-up)
43- VMSS only: instance count, orchestration mode (default **Flexible**)
44 
45If the user volunteers a deep signal mid-flow, append the relevant matrix questions for that topic. Do not restart.
46 
47### Step 4 — Validate
48 
49> **GATE — do not present the Plan Card until validation passes.**
50 
51Use the Azure MCP read-only tools listed in [validation-gates.md](references/validation-gates.md) (SKU exists in region / image is current / quota headroom / region availability). Required path; CLI fallback is documented in [mcp-tools.md](references/mcp-tools.md).
52 
53Outcomes:
54 
55| Result | Action |
56|---|---|
57| ✅ Sufficient | Proceed to Step 5 |
58| ⚠️ Near limit (>80%) | Proceed but flag in Plan Card; suggest quota increase |
59| ❌ Insufficient / SKU missing | Propose alternate SKU or region; do **not** generate output |
60 
61### Step 5 — Plan Card (with explicit-override fast path)
62 
63**Default path.** Render a single markdown table summarizing **every decision** (explicit answers + silent defaults). The user reads top-to-bottom and either approves or edits any row before output is generated. See [plan-card.md](references/plan-card.md) for the schema, example, and rendering rules.
64 
65Ask: *"Approve as-is, edit a row, or change output format?"* — do not generate until approved.
66 
67**Explicit-override fast path.** If the user's prompt combines (a) an explicit deliverable ("give me the Bicep", "just print the az CLI", "apply it via MCP") **and** (b) an explicit refusal of dialog ("no questions", "skip planning", "no plan", "just do it"), **respect them**. Skip the Plan Card table and the approval AskUserQuestion. Instead:
68 
691. Emit a **single-line preview** that surfaces the high-signal decisions inline — e.g. *"→ Deploying `Standard_D2s_v5` in `eastus`, OS `Ubuntu2404`, NSG = your public IP only on 22, est. ~$70/mo."*
702. Immediately emit the requested artifact (Bicep / Terraform / az CLI / MCP apply).
713. Mention once, at the end, that the full Plan Card is available on request if they want to edit rows.
72 
73Step 4 validation gates (SKU / image / quota / region) still run on the fast path — they protect against broken artifacts, not user intent. If validation fails, fall back to the ❌ outcome in Step 4 (propose alternate SKU/region, do not generate output).
74 
75### Step 6 — Output Choice
76 
77Ask the user to pick one of four formats (or use the one they already specified):
78 
79| Format | When | Adapter |
80|---|---|---|
81| **az CLI bash** | Quick one-off, learning, copy-paste | [az-cli.md](references/output-adapters/az-cli.md) |
82| **Bicep** | Repeatable IaC, production, ARM-native | [bicep.md](references/output-adapters/bicep.md) |
83| **Terraform** | Existing TF state, multi-cloud | [terraform.md](references/output-adapters/terraform.md) |
84| **Apply via Azure MCP** | "Just do it" — MCP connected, user trusts the Plan Card | [mcp-apply.md](references/output-adapters/mcp-apply.md) |
85 
86All four adapters consume the **same Plan Card parameter set** — switching format is a re-render, not a re-gather. For Apply via MCP, confirm one more time (the only destructive path) before calling `compute_vm_create` / `compute_vmss_create`.
87 
88### Step 7 — Delivery
89 
90> **Skip for Apply via MCP** — the artifact is the live deployment.
91 
92For `az CLI` / `Bicep` / `Terraform`, ask one final question: *where should it land?* See [delivery-options/index.md](references/delivery-options/index.md) for the decision logic. Three modes: [print](references/delivery-options/print.md), [save locally](references/delivery-options/save-local.md), [GitHub PR](references/delivery-options/github-pr.md).
93 
94If the user later says "also save it locally" or "open the PR now", re-run delivery with the cached Plan Card — **do not re-ask Plan Card questions**.
95 
96## Error handling
97 
98| Scenario | Action |
99|---|---|
100| Azure MCP not connected | Skip MCP pre-flight; warn that quota / SKU availability is unverified; offer CLI fallback |
101| `compute_vm_list-skus` returns empty | Broaden filter (drop `familyPrefix`, lower `minVCpus`); if still empty, suggest another region |
102| Quota insufficient | Show the gap; offer (a) smaller SKU, (b) different family, (c) different region, (d) quota-increase link |
103| User wants Windows but supplies SSH key | Switch auth to password (with strength check) or RDP + cert; do not generate broken artifact |
104| User asks "what was that az CLI again?" after picking Bicep | Re-render via Adapter 1; do not re-ask questions |
105| Custom image / Shared Image Gallery | Pass full resource ID to `compute_vm_list-images`; do not try to map to an alias |
106| User requests confidential / FedRAMP / HIPAA controls mid-flow | Append Security-deep questions; flag any defaults that fail the compliance bar |
107 
108## Routing back / handoff
109 
110| Situation | Route to |
111|---|---|
112| Deploy an **application** (not a bare VM) | `azure-prepare` skill |
113| Reserve capacity *before* creating | [capacity-reservation](../capacity-reservation/capacity-reservation.md) |
114| Enroll the new VM in management | [essential-machine-management](../essential-machine-management/essential-machine-management.md) |
115| Compare more SKU / pricing options | [vm-recommender](../vm-recommender/vm-recommender.md) Steps 1–6 |
116| Post-create RDP / SSH issues | [vm-troubleshooter](../vm-troubleshooter/vm-troubleshooter.md) |
117