references/phase1-advisor.md
Phase 1: Architecture Advisor
This file contains the detailed instructions for Phase 1. When entering Phase 1 from SKILL.md, read and follow this file. Used in both Path A (new design) and Path B (modification after Phase 0 scan).
When Entering from Path B (After Existing Resource Analysis)
The current architecture diagram (00_arch_current.html) scanned in Phase 0 already exists. In this case, skip the project name/service list confirmation in 1-1 and enter the modification conversation directly:
- "What would you like to change here?" — User's natural language request
- Apply Delta Confirmation Rule — Confirm undecided required fields for the changes
- Fact check — Cross-verify with MS Docs
- Generate updated diagram (01_arch_diagram_draft.html)
- Proceed to Phase 2 after confirmation
Goal of this Phase: Accurately identify what the user wants and finalize the architecture together.
1-1. Diagram Preparation — Gathering Required Information
Before drawing the diagram, ask the user questions until all items below are confirmed. Generate the diagram only after all items are confirmed.
First, confirm the project name:
Provide a default value as a choice via ask_user. If the user just presses Enter, the default is applied; they can also type a custom name.
The default is inferred from the user's request (e.g., RAG chatbot → rag-chatbot, data platform → data-platform).
ask_user({
question: "Please choose a project name. It will be used for the Bicep folder name, diagram path, and deployment name.",
choices: ["<inferred-default>", "azure-project"]
})
The project name is used for the Bicep output folder name, diagram save path, deployment name, etc.
🔹 Parallel Preload Along with Project Name Question (Required):
When asking the project name via ask_user, there is idle time while waiting for the user to respond.
Utilize this time to preload information needed for subsequent questions and Bicep generation in parallel.
Tools to call simultaneously with ask_user:
// Call ask_user + the tools below simultaneously in a single response
[1] ask_user — Project name question
[2] view — Load reference files (pre-acquire Stable information)
- references/service-gotchas.md
- references/ai-data.md
- references/azure-dynamic-sources.md
- references/architecture-guidance-sources.md
[3] web_fetch — Pre-fetch architecture guidance (when workload type is identified)
- Up to 2 targeted fetches based on decision rules in architecture-guidance-sources.md
[4] web_fetch — Fetch MS Docs for services mentioned by the user (pre-acquire Dynamic information)
- e.g., Foundry → API version, model availability page
- e.g., AI Search → SKU list page
- Use URL patterns from azure-dynamic-sources.md
Benefits: While the user types the project name, all information is loaded, so SKU/region questions can be presented with accurate choices immediately after the project name is confirmed. Wait time is significantly reduced compared to sequential execution.
Notes:
- Preload targets are only information independent of the project name (nothing depends on the name)
- web_fetch is performed only for services mentioned in the user's initial request (no guessing)
- Azure CLI check (
az account show) is NOT done at this point — preload at architecture finalization
🔹 Utilizing Architecture Guidance (Adjusting Question Depth):
Extract design decision points from the architecture guidance documents fetched during preload, and naturally incorporate them into subsequent user questions.
Purpose: Not just spec questions like SKU/region, but reflecting design decision points recommended by official architecture guidance into the questions.
Example — When "RAG chatbot" is requested:
- Fetch Baseline Foundry Chat Architecture (A6)
- Extract recommended design decision points from the document: → Network isolation level (full private vs hybrid?) → Authentication method (managed identity vs API key?) → Data ingestion strategy (push vs pull indexing?) → Monitoring scope (Application Insights needed?)
- Naturally include these points in user questions
Notes:
- What is extracted from architecture guidance is "points to ask about", not "answers"
- Deployment specs like SKU/API version/region are still determined only via
azure-dynamic-sources.md - Fetch budget: maximum 2 documents. No full traversal
Required confirmation items:
- [ ] Project name (default:
azure-project) - [ ] Service list (which Azure services to use)
- [ ] SKU/tier for each service
- [ ] Networking method (Private Endpoint usage)
- [ ] Deployment location (region)
Questioning principles:
- Do not ask again for information the user has already mentioned
- Do not ask about detailed implementation specifics not directly represented in the diagram (indexing method, query volume, etc.)
- Do not ask too many questions at once; ask only key undecided items concisely
- For items with obvious defaults (e.g., PE enabled), assume and just confirm. However, location MUST always be confirmed with the user
- When asking about SKUs, models, or service options, show ALL available choices verified from MS Docs, and provide the MS Docs URL as well. This allows the user to reference and make their own judgment. Do not show only partial options or arbitrarily filter them out
🔹 VM/Resource SKU Selection — Region Availability Pre-check Required:
Before asking the user about VM or other resource SKUs, you MUST first query which SKUs are actually available in the target region. If a SKU is blocked due to capacity restrictions in a specific region, the deployment will fail.
VM SKU verification method:
# Query only VM SKUs available without restrictions in the target region
az vm list-skus --location "<LOCATION>" --size Standard_D2 --resource-type virtualMachines `
--query "[?restrictions==``[]``].name" -o tsv
Principles:
- Do not include unverified SKUs in the choices
- Do not recommend "commonly used SKUs" from memory — MUST verify via az cli or MS Docs
- Include only verified SKUs in
ask_userchoices - Even for user-provided SKUs, verify availability before proceeding
This principle applies equally not just to VMs, but to ALL resources subject to capacity restrictions (Fabric Capacity, etc.).
🔹 Service Option Exploration Principle — "Listing from Memory" is Prohibited:
When the user asks about a service category ("What Spark options are there?", "What are the message queue options?"), or when you need to explore services for a specific capability:
NEVER do this:
- Directly fetch URLs for only 2-3 services from your memory and list them
- State definitively "In Azure, X has A and B"
MUST do this:
- Explore the full category via web_search — Search at the category level like
"Azure managed Spark options site:learn.microsoft.com"to first discover what services exist - Cross-check with v1 scope — Regardless of search results, check whether v1 scope services (Foundry, Fabric, AI Search, ADLS Gen2, etc.) fall under the relevant category. e.g.: "Spark" → Microsoft Fabric's Data Engineering workload also provides Spark
- Targeted fetch of discovered options — Fetch MS Docs for the services found via search to collect accurate comparison information
- Present all options to the user — Present all discovered options in a comprehensive comparison without omitting any
Example — When asked "What Spark instances are available?":
Wrong approach: Fetch only Databricks URL + Synapse URL → Compare only 2
Correct approach: web_search("Azure managed Spark options") → Discover Databricks, Synapse, Fabric Spark, HDInsight
→ v1 scope check: Fabric is v1 scope and provides Spark → MUST include
→ Targeted fetch of each service's MS Docs → Present full comparison table
This principle applies not only to service category exploration, but to all situations where the user requests "alternatives", "other options", "comparison", etc.
🔹 ask_user Tool — Mandatory Usage:
For questions with choices, you MUST use the ask_user tool. It allows users to select with arrow keys for convenience, and they can also type a custom input.
ask_user usage rules:
- Questions with 2 or more choices MUST use ask_user (do not list them as text)
choicesMUST be passed as a string array (["A", "B"]) — passing as a string ("A, B") will cause an error- If there is a recommended option, place it first and append
(Recommended)at the end - Include reference information in choices — e.g.,
"Standard S1 - Recommended for production. Ref: https://..." - Only 1 question per call — if multiple items need to be asked, call ask_user sequentially for each
- Choices are limited to a maximum of 4. If there are 5 or more, include only the 3-4 most common ones (users can also type a custom input)
- If multiple selections are needed, split them into separate questions
Items requiring ask_user:
- Deployment location (region) selection
- SKU/tier selection
- Model selection (chat model, embedding model, etc.)
- Networking method selection
- Subscription selection (Phase 1 Step 2)
- Resource group selection (Phase 1 Step 3)
- Any other question requiring a user choice
Usage examples:
// Project name is free-form input so ask_user is not used (ask as text)
// SKU, region, etc. with defined choices use ask_user:
// 1. SKU question
ask_user({
question: "Please select the SKU for AI Search. Ref: https://learn.microsoft.com/en-us/azure/search/search-sku-tier",
choices: [
"Standard S1 - Recommended for production (Recommended)",
"Basic - For dev/test, up to 15 indexes",
"Standard S2 - High-traffic production",
"Free - Free trial, 50MB storage"
]
})
// 2. Region question (separate call — only 1 question per call)
ask_user({
question: "Please select the Azure region for deployment. Ref: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models",
choices: [
"Korea Central - Korea region, supports most services (Recommended)",
"East US - US East, supports all AI models",
"Japan East - Japan East, close to Korea"
]
})
Note: The SKU and region values in the examples above are for illustration only. When actually asking, dynamically compose choices based on the latest information by querying MS Docs via web_fetch. Do not hardcode.
Example — When user input is insufficient:
User: "I want to build a RAG chatbot. Using a GPT model in Foundry and AI Search."
→ Confirmed: Microsoft Foundry, Azure AI Search
→ Still undecided: Project name, specific model name, embedding model, networking (PE?), SKU, deployment location
The agent first confirms the project name via ask_user (default: rag-chatbot).
Then provides choices for each undecided item via the ask_user tool.
Include MS Docs URLs in the choices so the user can reference them directly.
🚨🚨🚨 [HARD GATE] Spec Collection Complete → Diagram Generation Required 🚨🚨🚨
Immediately after all confirmed items are filled in, you MUST perform the following steps IN ORDER. Skipping any step means Phase 1 is incomplete.
- Compose services JSON + connections JSON based on the confirmed service list
- Use the built-in diagram engine to generate
<project-name>/01_arch_diagram_draft.html - Automatically open it in the browser via
Start-Process - Show the diagram to the user in the report format below — this MUST include a detailed configuration table
- Ask the user: "Would you like to change or add anything?"
- If the user has no changes → proceed to Phase 2 transition (ask_user with next step guidance)
NEVER do this:
- ❌ Not generating the diagram and asking "The architecture is confirmed. Shall we proceed to the next step?"
- ❌ Deferring diagram generation to Phase 2 or later
- ❌ Saying "I'll create the diagram later"
- ❌ Declaring "architecture confirmed" based solely on spec collection completion
- ❌ Generating the diagram but NOT showing the configuration table
- ❌ Skipping the "anything to change?" question and jumping straight to Phase 2
Validation condition: Phase 2 entry is NOT allowed if the 01_arch_diagram_draft.html file has not been generated.
Report format after diagram completion (ALL sections are MANDATORY):
## Architecture Diagram
[Interactive diagram link — auto-opened in browser]
### Confirmed Configuration
| Service | Type | SKU/Tier | Details |
|---------|------|----------|---------|
| [Service name] | [Azure resource type] | [SKU] | [Key config: model, capacity, etc.] |
| ... | ... | ... | ... |
**Networking**: [VNet + Private Endpoint / Public / etc.]
**Location**: [confirmed region]
After showing the report, immediately use ask_user with choices:
ask_user({
question: "The architecture diagram and configuration are ready. What would you like to do?",
choices: [
"Looks good — proceed to Bicep code generation (Recommended)",
"I want to modify the architecture",
"Add more services"
]
})
- If "proceed" → move to Phase 2 transition (collect subscription/RG info)
- If "modify" or "add" → apply changes, regenerate diagram, show report again
🚨 The configuration table is NOT optional. The user needs to visually verify what was confirmed before proceeding. Without the table, the user cannot validate the architecture.
1-2. Interactive HTML Diagram Generation
Use the built-in diagram engine (Python scripts included in the skill) to create an interactive HTML diagram.
No pip install is needed as the scripts are directly available in the scripts/ folder, requiring no network connection or package installation.
605+ official Azure icons are built in.
Diagram file naming convention:
All diagrams are generated inside the Bicep project folder (<project-name>/).
They are systematically managed with numbered prefixes per stage, and previous stage files are never overwritten.
| Stage | File Name | When Generated |
|-------|-----------|----------------|
| Phase 1 design draft | 01_arch_diagram_draft.html | When architecture design is confirmed |
| Phase 4 What-if preview | 02_arch_diagram_preview.html | After What-if validation |
| Phase 4 deployment result | 03_arch_diagram_result.html | After actual deployment completes |
Built-in module path discovery + Python path discovery:
🚨 The Python path + built-in module path are verified once during Phase 1 preload, and reused for all subsequent diagram generations. Do NOT re-discover every time.
# ─── Step 1: Python Path Discovery ───
# ⚠️ Get-Command python may pick up the Windows Store alias, so filesystem discovery is done first
$PythonCmd = $null
# Priority 1: Direct discovery of actual installation path (most reliable)
$PythonExe = Get-ChildItem -Path "$env:LOCALAPPDATA\Programs\Python" -Filter "python.exe" -Recurse -ErrorAction SilentlyContinue |
Where-Object { $_.FullName -notlike '*WindowsApps*' } |
Select-Object -First 1 -ExpandProperty FullName
if ($PythonExe) { $PythonCmd = $PythonExe }
# Priority 2: Program Files discovery
if (-not $PythonCmd) {
$PythonExe = Get-ChildItem -Path "$env:ProgramFiles\Python*", "$env:ProgramFiles(x86)\Python*" -Filter "python.exe" -Recurse -ErrorAction SilentlyContinue |
Select-Object -First 1 -ExpandProperty FullName
if ($PythonExe) { $PythonCmd = $PythonExe }
}
# Priority 3: Find in PATH (only if not a Windows Store alias)
if (-not $PythonCmd) {
foreach ($cmd in @('python3', 'py')) {
$found = Get-Command $cmd -ErrorAction SilentlyContinue
if ($found -and $found.Source -notlike '*WindowsApps*') { $PythonCmd = $cmd; break }
}
}
if (-not $PythonCmd) {
Write-Host ""
Write-Host "Python is not installed or not found in PATH." -ForegroundColor Red
Write-Host ""
Write-Host "Please install using one of the following methods:" -ForegroundColor Yellow
Write-Host " 1. winget install Python.Python.3.12"
Write-Host " 2. Download from https://www.python.org/downloads/"
Write-Host " 3. Search for 'Python 3.12' in the Microsoft Store and install"
Write-Host ""
Write-Host "After installation, restart your terminal and try again."
return
}
# ─── Step 2: Built-in Script Path Discovery (no pip install needed) ───
# Priority 1: Project local skill folder
$ScriptsDir = Get-ChildItem -Path ".github\skills\azure-architecture-autopilot" -Filter "cli.py" -Recurse -ErrorAction SilentlyContinue |
Where-Object { $_.Directory.Name -eq 'scripts' } |
Select-Object -First 1 -ExpandProperty DirectoryName
# Priority 2: Global skill folder
if (-not $ScriptsDir) {
$ScriptsDir = Get-ChildItem -Path "$env:USERPROFILE\.copilot\skills\azure-architecture-autopilot" -Filter "cli.py" -Recurse -ErrorAction SilentlyContinue |
Where-Object { $_.Directory.Name -eq 'scripts' } |
Select-Object -First 1 -ExpandProperty DirectoryName
}
# ─── Step 3: Diagram Generation (CLI method — direct script execution) ───
$OutputFile = "<project-name>\01_arch_diagram_draft.html"
& $PythonCmd "$ScriptsDir\cli.py" `
--services '<services_JSON>' `
--connections '<connections_JSON>' `
--title "Architecture Title" `
--vnet-info "10.0.0.0/16 | pe-subnet: 10.0.1.0/24" `
--output $OutputFile
# Automatically open in browser after generation
Start-Process $OutputFile
Python API method is also available (alternative):
When JSON is very large, you can directly call the Python API to avoid CLI argument length limitations.
Add the scripts folder to sys.path to import the built-in module:
import sys, os
# Add scripts folder to Python path (use built-in module without pip install)
scripts_dir = r"<absolute path to scripts folder>" # $ScriptsDir value found in Step 2
sys.path.insert(0, scripts_dir)
from generator import generate_diagram
services = [...] # services JSON
connections = [...] # connections JSON
html = generate_diagram(
services=services,
connections=connections,
title="Architecture Title",
vnet_info="10.0.0.0/16 | pe-subnet: 10.0.1.0/24",
hierarchy=None # Only used for multiple subscriptions/RGs
)
with open("<project-name>/01_arch_diagram_draft.html", "w", encoding="utf-8") as f:
f.write(html)
🔹 CLI vs Python API Selection Criteria:
| Scenario | Method | Reason |
|----------|--------|--------|
| 10 or fewer services | CLI (python scripts/cli.py) | Simple and fast |
| More than 10 services or using hierarchy | Python API (sys.path addition) | Avoids CLI argument length limits |
| Multi-subscription/RG diagrams | Python API + hierarchy parameter | Hierarchical structure representation |
Full list of supported service types:
Available in the skill's built-in reference files under references/.
Supported service type values are listed below in the services JSON format section.
Diagram generation order: (1) Verify Python path → (2) Verify built-in module path → (3) Compose services/connections JSON → (4) Execute. If Python is not installed, guide the user to install it before composing JSON. This prevents the waste of building JSON only to fail because Python is missing.
🚨 Automatic Diagram Open (No Exceptions): When an HTML file is generated with the built-in diagram engine, it MUST always be opened in the browser regardless of the situation. Without exception, whenever a diagram is (re)generated, execute the
Start-Processcommand. Diagram generation and browser opening are always executed together in a single PowerShell command block.When this applies (not just these, but ALL times an HTML diagram is generated):
- Phase 1 design draft (
01_arch_diagram_draft.html)- Diagram regeneration after Delta Confirmation
- Phase 4 What-if preview (
02_arch_diagram_preview.html)- Phase 4 deployment result (
03_arch_diagram_result.html)- Architecture changes after deployment (
04_arch_diagram_update_draft.html)- Any other case where a diagram is regenerated for any reason
services JSON format:
Dynamically composed based on the user's confirmed service list. Below is the JSON structure description.
[
{"id": "uniqueID", "name": "Service Display Name", "type": "iconType", "sku": "SKU", "private": true/false,
"details": ["Detail line 1", "Detail line 2"]}
]
| Field | Required | Type | Description |
|-------|----------|------|-------------|
| id | Yes | string | Unique identifier (kebab-case) |
| name | Yes | string | Display name shown on diagram |
| type | Yes | string | Service type (select from list below) |
| sku | | string | SKU/tier information |
| private | | boolean | Private Endpoint connected (default: false) |
| details | | string[] | Additional info shown in sidebar |
| subscription | | string | Subscription name (required when using hierarchy) |
| resourceGroup | | string | Resource group name (required when using hierarchy) |
Service Type — Canonical Reference:
⚠️ CRITICAL: Always use the canonical type from the table below. Do NOT use Azure ARM resource names (e.g.,
private_endpoints,storage_accounts,data_factories). The generator normalizes common variants, but using canonical types ensures correct icon rendering, PE detection, and color coding.
| Category | Canonical Type | Azure Resource | Icon |
|----------|---------------|----------------|------|
| AI | ai_foundry | Microsoft.CognitiveServices/accounts (kind: AIServices) | AI Foundry |
| | openai | Microsoft.CognitiveServices/accounts (kind: OpenAI) | Azure OpenAI |
| | ai_hub | Foundry Project | AI Studio |
| | search | Microsoft.Search/searchServices | Cognitive Search |
| | document_intelligence | Microsoft.CognitiveServices/accounts (kind: FormRecognizer) | Form Recognizer |
| | aml | Microsoft.MachineLearningServices/workspaces | Machine Learning |
| Data | fabric | Microsoft.Fabric/capacities | Microsoft Fabric |
| | adf | Microsoft.DataFactory/factories | Data Factory |
| | storage | Microsoft.Storage/storageAccounts | Storage Account |
| | adls | ADLS Gen2 (Storage with HNS) | Data Lake |
| | cosmos_db | Microsoft.DocumentDB/databaseAccounts | Cosmos DB |
| | sql_database | Microsoft.Sql/servers/databases | SQL Database |
| | sql_server | Microsoft.Sql/servers | SQL Server |
| | databricks | Microsoft.Databricks/workspaces | Databricks |
| | synapse | Microsoft.Synapse/workspaces | Synapse Analytics |
| | redis | Microsoft.Cache/redis | Redis Cache |
| | stream_analytics | Microsoft.StreamAnalytics/streamingjobs | Stream Analytics |
| | postgresql | Microsoft.DBforPostgreSQL/flexibleServers | PostgreSQL |
| | mysql | Microsoft.DBforMySQL/flexibleServers | MySQL |
| Security | keyvault | Microsoft.KeyVault/vaults | Key Vault |
| | sentinel | Microsoft.SecurityInsights | Sentinel |
| Compute | appservice | Microsoft.Web/sites | App Service |
| | function_app | Microsoft.Web/sites (kind: functionapp) | Function App |
| | vm | Microsoft.Compute/virtualMachines | Virtual Machine |
| | aks | Microsoft.ContainerService/managedClusters | AKS |
| | acr | Microsoft.ContainerRegistry/registries | Container Registry |
| | container_apps | Microsoft.App/containerApps | Container Apps |
| | static_web_app | Microsoft.Web/staticSites | Static Web App |
| | spring_apps | Microsoft.AppPlatform/Spring | Spring Apps |
| Network | pe | Microsoft.Network/privateEndpoints | Private Endpoint |
| | vnet | Microsoft.Network/virtualNetworks | VNet |
| | nsg | Microsoft.Network/networkSecurityGroups | NSG |
| | firewall | Microsoft.Network/azureFirewalls | Firewall |
| | bastion | Microsoft.Network/bastionHosts | Bastion |
| | app_gateway | Microsoft.Network/applicationGateways | App Gatewa