1# Plan Template
2 
3Create `.azure/deployment-plan.md` using this template. This file is **mandatory** and serves as the source of truth for the entire workflow.
4 
5## ⛔ BLOCKING REQUIREMENTS
6 
71. You **MUST** create this plan file BEFORE generating any code, infrastructure, or configuration.
82. You **MUST** complete Step 6 Phase 2 (Provisioning Limit Checklist) with NO "_TBD_" entries remaining before presenting the plan to the user.
93. Present the plan to the user and get approval before proceeding to execution.
104. You **MUST NOT** skip any part of the plan.
11 
12---
13 
14## Template
15 
16```markdown
17# Azure Deployment Plan
18 
19> **Status:** Planning | Approved | Executing | Ready for Validation | Validated | Deployed
20 
21Generated: {timestamp}
22 
23---
24 
25## 1. Project Overview
26 
27**Goal:** {what the user wants to build/deploy}
28 
29**Path:** New Project | Add Components | Modernize Existing
30 
31---
32 
33## 2. Requirements
34 
35| Attribute | Value |
36|-----------|-------|
37| Classification | POC / Development / Production |
38| Scale | Small / Medium / Large |
39| Budget | Cost-Optimized / Balanced / Performance |
40| **Subscription** | {subscription-name-or-id} ⚠️ MUST confirm with user |
41| **Location** | {azure-region} ⚠️ MUST confirm with user |
42 
43---
44 
45## 3. Components Detected
46 
47| Component | Type | Technology | Path |
48|-----------|------|------------|------|
49| {name} | Frontend / API / Worker | {stack} | {path} |
50 
51---
52 
53## 4. Recipe Selection
54 
55**Selected:** AZD / AZCLI / Bicep / Terraform
56 
57**Rationale:** {why this recipe was chosen}
58 
59---
60 
61## 5. Architecture
62 
63**Stack:** Containers / Serverless / App Service
64 
65### Service Mapping
66 
67| Component | Azure Service | SKU |
68|-----------|---------------|-----|
69| {component} | {azure-service} | {sku} |
70 
71### Supporting Services
72 
73| Service | Purpose |
74|---------|---------|
75| Log Analytics | Centralized logging |
76| Application Insights | Monitoring & APM |
77| Key Vault | Secrets management |
78| Managed Identity | Service-to-service auth |
79 
80---
81 
82## 6. Provisioning Limit Checklist
83 
84**Purpose:** Validate that the selected subscription and region have sufficient quota/capacity for all resources to be deployed.
85 
86> **⚠️ REQUIRED:** This is a **TWO-PHASE** process. Complete both phases before proceeding.
87 
88### Phase 1: Prepare Resource Inventory
89 
90List all resources to be deployed with their types and quantities. Leave quota/limit columns empty.
91 
92| Resource Type | Number to Deploy | Total After Deployment | Limit/Quota | Notes |
93|---------------|------------------|------------------------|-------------|-------|
94| {ARM-resource-type} | {count} | _To be filled in Phase 2_ | _To be filled in Phase 2_ | _To be filled in Phase 2_ |
95 
96**Example format:**
97 
98| Resource Type | Number to Deploy | Total After Deployment | Limit/Quota | Notes |
99|---------------|------------------|------------------------|-------------|-------|
100| Microsoft.App/managedEnvironments | 1 | _TBD_ | _TBD_ | _TBD_ |
101| Microsoft.Compute/virtualMachines (Standard_D4s_v3) | 3 | _TBD_ | _TBD_ | _TBD_ |
102| Microsoft.Network/publicIPAddresses | 2 | _TBD_ | _TBD_ | _TBD_ |
103| Microsoft.DocumentDB/databaseAccounts | 1 | _TBD_ | _TBD_ | _TBD_ |
104| Microsoft.Storage/storageAccounts | 2 | _TBD_ | _TBD_ | _TBD_ |
105 
106### Phase 2: Fetch Quotas and Validate Capacity
107 
108**Action:** **MUST invoke azure-quotas skill first** to populate the remaining columns with actual quota data using Azure quota CLI. Only use fallback methods if quota CLI is not supported.
109 
110> **⚠️ IMPORTANT:** Process **ONE resource type at a time**. Do NOT try to apply all steps to all resources at once. Complete steps 1-7 for the first resource, then move to the next resource, and so on.
111 
112For each resource type:
113 
1141. **Check if quota CLI is supported** - Run `az quota list --scope /subscriptions/{subscription-id}/providers/{ProviderNamespace}/locations/{region}` to verify the provider is supported. If you encounter issues or need help finding the correct resource name, invoke the azure-quotas skill for troubleshooting.
1152. **Get current usage and limit**:
116   - **If quota CLI is supported**:
117     - Get limit: `az quota show --resource-name {quota-resource-name} --scope /subscriptions/{subscription-id}/providers/{ProviderNamespace}/locations/{region}`
118     - Get current usage: `az quota usage show --resource-name {quota-resource-name} --scope /subscriptions/{subscription-id}/providers/{ProviderNamespace}/locations/{region}`
119   - **If quota CLI is NOT supported** (returns `BadRequest`):
120     - Get current usage: `az graph query -q "resources | where type == '{resource-type}' and location == '{location}' | count"` (requires `az extension add --name resource-graph`)
121     - Get limit: [Azure service limits documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits)
1223. **Calculate total** - Add "Number to Deploy" + current usage = "Total After Deployment"
1234. **Verify capacity** - Ensure "Total After Deployment" ≤ "Limit/Quota"
1245. **Document source** - Note whether data came from "azure-quotas (resource-name)" or "Azure Resource Graph + Official docs"
125 
126**Completed example:**
127 
128| Resource Type | Number to Deploy | Total After Deployment | Limit/Quota | Notes |
129|---------------|------------------|------------------------|-------------|-------|
130| Microsoft.App/managedEnvironments | 1 | 1 | 50 | Fetched from: azure-quotas (ManagedEnvironmentCount) |
131| Microsoft.Compute/virtualMachines (Standard_D4s_v3) | 3 | 15 | 350 vCPUs | Fetched from: azure-quotas (standardDSv3Family) |
132| Microsoft.Network/publicIPAddresses | 2 | 5 | 100 | Fetched from: azure-quotas (PublicIPAddresses) |
133| Microsoft.DocumentDB/databaseAccounts | 1 | 1 | 50 per region | Fetched from: Official docs (quota CLI not supported) |
134| Microsoft.Storage/storageAccounts | 2 | 8 | 250 per region | Fetched from: Official docs |
135 
136**Status:** ✅ All resources within limits | ⚠️ Near limit (>80%) | ❌ Insufficient capacity
137 
138> **⛔ CRITICAL:** You **CANNOT** present this plan to the customer if ANY cells contain "_TBD_" or "_To be filled in Phase 2_". Phase 2 **MUST** be completed with actual quota data before user presentation.
139 
140**Notes:**
141- **MUST use azure-quotas skill first** to check providers via quota CLI (`az quota` commands) - Microsoft.Compute, Microsoft.Network, Microsoft.App, etc.
142- Azure quota CLI is **ALWAYS preferred over REST API** for checking quotas
143- **ONLY for unsupported providers** (e.g., Microsoft.DocumentDB returns `BadRequest`), use fallback methods: [Azure service limits documentation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits)
144- If any resource exceeds limits, return to Step 2 to select a different region or request quota increase
145 
146---
147 
148## 7. Execution Checklist
149 
150### Phase 1: Planning
151- [ ] Analyze workspace
152- [ ] Gather requirements
153- [ ] Confirm subscription and location with user
154- [ ] Prepare resource inventory (Step 6 Phase 1: list resource types and deployment quantities)
155- [ ] Fetch quotas and validate capacity (Step 6 Phase 2: invoke azure-quotas skill to use quota CLI)
156- [ ] Scan codebase
157- [ ] Select recipe
158- [ ] Plan architecture
159- [ ] **User approved this plan**
160 
161### Phase 2: Execution
162- [ ] Research components (load references, invoke skills)
163- [ ] **⛔ For Azure Functions: Load composition rules** (`services/functions/templates/selection.md` → `services/functions/templates/recipes/composition.md`) and use `functions_template_get` MCP tool to list and fetch templates, then write `functionFiles[]` + `projectFiles[]` directly — NEVER hand-write Bicep/Terraform and use `azd init -t <template>`/`func init`/`func new` as fallback when composing multiple recipes and required templates are not found
164- [ ] For other services: Generate infrastructure files following service-specific guidance
165- [ ] Apply recipes for integrations (if needed)
166- [ ] Generate application configuration
167- [ ] Generate Dockerfiles (if containerized)
168- [ ] **⛔ Update plan status to "Ready for Validation"** — Use the `edit` tool to change the Status line in `.azure/deployment-plan.md`. This step is MANDATORY before invoking azure-validate.
169 
170### Phase 3: Validation
171- [ ] **PREREQUISITE:** Plan status MUST be "Ready for Validation" (Phase 2 last step)
172- [ ] Invoke azure-validate skill
173- [ ] All validation checks pass
174  - [ ] _Replace this with recipe validation steps_
175- [ ] Update plan status to "Validated"
176- [ ] Record validation proof below
177 
178### Phase 4: Deployment
179- [ ] Invoke azure-deploy skill
180- [ ] Deployment successful
181- [ ] Report deployed endpoint URLs
182- [ ] Update plan status to "Deployed"
183 
184---
185 
186## 7. Validation Proof
187 
188> **⛔ REQUIRED**: The azure-validate skill MUST populate this section before setting status to `Validated`. If this section is empty and status is `Validated`, the validation was bypassed improperly.
189 
190| Check | Command Run | Result | Timestamp |
191|-------|-------------|--------|-----------|
192| {check-name} | {actual command executed} | ✅ Pass / ❌ Fail | {timestamp} |
193 
194**Validated by:** azure-validate skill
195**Validation timestamp:** {timestamp}
196 
197---
198 
199## 8. Files to Generate
200 
201| File | Purpose | Status |
202|------|---------|--------|
203| `.azure/deployment-plan.md` | This plan | ✅ |
204| `azure.yaml` | AZD configuration | ⏳ |
205| `infra/main.bicep` | Infrastructure | ⏳ |
206| `src/{component}/Dockerfile` | Container build | ⏳ |
207 
208---
209 
210## 9. Next Steps
211 
212> Current: {current phase}
213 
2141. {next action}
2152. {following action}
216```
217 
218---
219 
220## Instructions
221 
2221. **Create the plan first** — Fill in all sections based on analysis
2232. **Complete quota validation** — Ensure Step 6 Phase 2 is completed with NO "_TBD_" entries. **MUST use azure-quotas skill** as the primary method to fetch actual quota/usage data via quota CLI (`az quota` commands) for all resources. Use fallback methods ONLY when provider returns `BadRequest`.
2243. **Present to user** — Show the completed plan and ask for approval. **DO NOT** present if Step 6 contains any "_TBD_" or "_To be filled in Phase 2_" entries.
2254. **Update as you go** — Check off items in the execution checklist
2265. **Track status** — Update the Status field at the top as you progress
227 
228The plan is the **single source of truth** for azure-validate and azure-deploy skills.
229