awesome-copilot/skills/azure-architecture-autopilot/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:

1. "What would you like to change here?" — User's natural language request
2. Apply Delta Confirmation Rule — Confirm undecided required fields for the changes
3. Fact check — Cross-verify with MS Docs
4. Generate updated diagram (01_arch_diagram_draft.html)
5. 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:**
```powershell
# 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_user` choices
- 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:**
1. **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
2. **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
3. **Targeted fetch of discovered options** — Fetch MS Docs for the services found via search to collect accurate comparison information
4. **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)
- **`choices` MUST 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.**

1. Compose **services JSON + connections JSON** based on the confirmed service list
2. Use the built-in diagram engine to generate **`<project-name>/01_arch_diagram_draft.html`**
3. Automatically open it in the browser via `Start-Process`
4. Show the diagram to the user in the **report format** below — this MUST include a **detailed configuration table**
5. Ask the user: **"Would you like to change or add anything?"**
6. 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.**

```powershell
# ─── 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:

```python
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-Process` command. 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.

```json
[
  {"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 Gateway |
| | `front_door` | Microsoft.Cdn/profiles (Front Door) | Front Door |
| | `vpn` | Microsoft.Network/virtualNetworkGateways | VPN Gateway |
| | `load_balancer` | Microsoft.Network/loadBalancers | Load Balancer |
| | `nat_gateway` | Microsoft.Network/natGateways | NAT Gateway |
| | `cdn` | Microsoft.Cdn/profiles | CDN |
| **IoT** | `iot_hub` | Microsoft.Devices/IotHubs | IoT Hub |
| | `digital_twins` | Microsoft.DigitalTwins/digitalTwinsInstances | Digital Twins |
| **Integration** | `event_hub` | Microsoft.EventHub/namespaces | Event Hub |
| | `event_grid` | Microsoft.EventGrid/topics | Event Grid |
| | `apim` | Microsoft.ApiManagement/service | API Management |
| | `service_bus` | Microsoft.ServiceBus/namespaces | Service Bus |
| | `logic_apps` | Microsoft.Logic/workflows | Logic Apps |
| **Monitoring** | `log_analytics` | Microsoft.OperationalInsights/workspaces | Log Analytics |
| | `appinsights` | Microsoft.Insights/components | App Insights |
| | `monitor` | Azure Monitor | Monitor |
| **Other** | `jumpbox`, `user`, `devops` | — | Special |

**When Using Private Endpoints — PE Node Addition Required:**

If Private Endpoints are included in the architecture, a PE node MUST be added to the services JSON for each service, and connections must also include the PE links for them to appear in the diagram.

```json
// Add PE node corresponding to each service
{"id": "pe_serviceID", "name": "PE: ServiceName", "type": "pe", "details": ["groupId: correspondingGroupID"]}

// Add service → PE connection in connections
{"from": "serviceID", "to": "pe_serviceID", "label": "", "type": "private"}
```

**🚨🚨🚨 PE Connections and Business Logic Connections Are Separate — BOTH MUST Be Included 🚨🚨🚨**

PE connections (`"type": "private"`) represent network isolation. But this alone does NOT show the actual **data flow/API calls** between services in the diagram.

**MUST include both types of connections:**

1. **Business logic connections** — Actual data flow between services (api, data, security types)
2. **PE connections** — Network isolation between service ↔ PE (private type)

```json
// ✅ Correct example — Function App → Foundry
// 1) Business logic: Function App calls Foundry for chat/embedding
{"from": "func_app", "to": "foundry", "label": "RAG Chat + Embedding", "type": "api"}
// 2) PE connection: Foundry's Private Endpoint
{"from": "foundry", "to": "pe_foundry", "label": "", "type": "private"}

// ❌ Wrong example — Only PE connection, no business logic connection
{"from": "foundry", "to": "pe_foundry", "label": "", "type": "private"}
// → No connection line between Function App and Foundry in the diagram, so the architecture flow is not visible
```

**NEVER do this:**
- Create only PE connections and omit business logic connections
- Connect `from`/`to` of business logic connections to PE nodes (use the **actual service ID**, not the PE)
- Assume "the PE is there so the connection line will show up"

The PE groupId differs by service. Refer to the PE groupId & DNS Zone mapping table in `references/service-gotchas.md`.

> **Service naming convention**: MUST use the latest official Azure names. If uncertain about the name, verify with MS Docs.
> For resource types and key properties per service, refer to `references/ai-data.md`.

**connections JSON format:**
```json
[
  {"from": "serviceA_ID", "to": "serviceB_ID", "label": "Connection description", "type": "api|data|security|private"}
]
```

**Connection Types:**

| type | Color | Style | Use For |
|------|-------|-------|---------|
| `api` | Blue | Solid | API calls, queries |
| `data` | Green | Solid | Data flow, indexing |
| `security` | Orange | Dashed | Secrets, auth |
| `private` | Purple | Dashed | Private Endpoint connections |
| `network` | Gray | Solid | Network routing |
| `default` | Gray | Solid | Other |

**🔹 Diagram Multilingual Principle:**
- The `name`, `details` in services and `label` in connections are written in **the user's language**
- Example: `"label": "RAG Search"`, `"label": "Data Ingestion"`
- Official Azure service names (Microsoft Foundry, AI Search, etc.) are always in English regardless of language

**🔹 VNet Node — Do NOT add to services JSON:**
- VNet is automatically displayed as a **purple dashed boundary** in the diagram (when PEs are present)
- Adding a separate VNet node to services JSON causes confusion by duplicating with the boundary line
- VNet information (CIDR, subnets) is sufficiently conveyed through the sidebar VNet boundary label

Provide the full path of the generated HTML file to the user.

### 1-3. Finalizing Architecture Through Conversation

The architecture is finalized incrementally through conversation with the user. When the user requests changes, do NOT ask everything from scratch; instead, **reflect only the requested changes based on the current confirmed state** and regenerate the diagram.

**⚠️ Delta Confirmation Rule — Required Verification on Service Addition/Change:**

Service addition/change is not a "simple update" — it is an **event that reopens undecided required fields for that service**.

**Process:**
1. Diff the current confirmed state + new request
2. Identify the required fields for newly added services (refer to `domain-packs` or MS Docs)
3. Fetch the region availability/options for the service from MS Docs
4. If any required fields are undecided, **ask the user via ask_user first**
5. **Regenerate the diagram only after confirmation is complete**

**NEVER do this:**
- Finalize diagram update while required fields remain undecided
- Arbitrarily add sub-components/workloads the user did not mention (e.g., automatically adding OneLake and data pipeline to a Fabric request)
- Vaguely assume SKU/model like "F SKU" without confirmation

**Do not re-ask settings for already confirmed services.** Only confirm undecided items for newly added/changed services.

---

**🚨🚨🚨 [Top Priority Principle] Immediate Fact Check During Design Phase 🚨🚨🚨**

**The purpose of Phase 1 is to confirm a "feasible architecture".**
**No matter what the user requests, before reflecting it in the diagram, you MUST fact-check whether it is actually possible by directly querying MS Docs via web_fetch.**

**Design Direction vs Deployment Specs — Separate Information Paths:**

| Decision Type | Reference Path | Examples |
|--------------|----------------|----------|
| **Design direction** (architecture patterns, best practices, service combinations) | `references/architecture-guidance-sources.md` → targeted fetch | "What's the recommended RAG structure?", "Enterprise baseline?" |
| **Deployment specs** (API version, SKU, region, model, PE mapping) | `references/azure-dynamic-sources.md` → MS Docs fetch | "What's the API version?", "Is this model available in Korea Central?" |

- **Design direction comes from architecture guidance, actual deployment values from dynamic sources.** Do not mix these two paths.
- Do NOT use Architecture guidance document content to determine SKU/API version/region.
- **Do NOT crawl through all Architecture Center sub-documents for every request.** Perform trigger-based targeted fetch of at most 2 relevant documents.
- For trigger/fetch budget/decision rules by question type, refer to `architecture-guidance-sources.md`.

**This principle applies to ALL requests without exception:**
- Model addition/change → Verify in MS Docs whether the model exists and can be deployed in the target region
- Service addition/change → Verify in MS Docs whether the service is available in the target region
- SKU change → Verify in MS Docs whether the SKU is valid and supports the desired features
- Feature request → Verify in MS Docs whether the feature is actually supported
- Service combination → Verify in MS Docs whether inter-service integration is possible
- **Any other request** → Fact-check with MS Docs

**MS Docs verification results:**
- **Possible** → Reflect in diagram
- **Not possible** → Immediately explain the reason to the user and suggest available alternatives

**Fact Check Process — Cross-Verification Required:**

Do not simply query once and move on for user requests.
**Cross-verification using other MS Docs pages/sources MUST always be performed.**

> **GHCP Environment Constraint**: Sub-agents (explore/task/general-purpose) do NOT have `web_fetch`/`web_search` tools.
> Therefore, verification requiring MS Docs queries MUST be performed **directly by the main agent**.

```
[1st Verification] Main agent directly queries MS Docs via web_fetch (primary page)
    ↓
[2nd Verification] Main agent additionally fetches other/related MS Docs pages via web_fetch for cross-checking
    - e.g., Model availability → 1st: models page / 2nd: regional availability or pricing page
    - e.g., API version → 1st: Bicep reference page / 2nd: REST API reference page
    - Compare 1st and 2nd results and flag any discrepancies
    ↓
[Consolidate Results] If both verifications match, respond to the user
    - On discrepancy: Resolve with additional queries, or honestly inform the user about the uncertainty
```

**Fact Check Quality Standards — Be Thorough, Not Cursory:**
- When a MS Docs page is fetched, **check ALL relevant sections, tabs, and conditions without omission**
- When checking model availability: Check **ALL deployment types** including Global Standard, Standard, Provisioned, Data Zone, etc. Do NOT conclude "not supported" based on only one deployment type
- When checking SKUs: **Fully** verify the feature list supported by that SKU
- If the page is large, fetch relevant sections **multiple times** to ensure accuracy
- If uncertain, query additional pages. **NEVER answer based on guesswork**

**NEVER do this:**
- Add to the diagram without verification
- Defer verification with "I'll check during Bicep generation" or "It will be validated during deployment"
- Rely only on your memory and answer "it should work" — **MUST directly query MS Docs**
- Fetch MS Docs but rush to conclusions after only partially reading
- Finalize based on a single query — **MUST cross-verify with another source**

**🚫 Sub-Agent Usage Rules:**

**Sub-agents in GHCP = `task` tool:**
- `agent_type: "explore"` — Read-only tasks like codebase exploration, file search (**web_fetch/web_search NOT available**)
- `agent_type: "task"` — Command execution like az cli, bicep build
- `agent_type: "general-purpose"` — High-level tasks like complex Bicep generation

> **⚠️ Sub-agent tool constraint**: ALL sub-agents (explore/task/general-purpose) CANNOT use `web_fetch` or `web_search`.
> Fact checks requiring MS Docs queries, API version verification, model availability checks, etc. MUST be performed **directly by the main agent**.

**Foreground vs Background Decision Criteria:**
- **If results are needed before proceeding to the next step → `mode: "sync"` (default)**
  - e.g., Query SKU list then provide choices to user, verify model availability then reflect in diagram
  - Running in background here would leave the user idle waiting for results
- **If there is other independent work that can be done while waiting for results → `mode: "background"`**
  - e.g., Simultaneously web_fetch multiple MS Docs pages for cross-verification

**Most fact checks should be run in foreground (`mode: "sync"`)** because the next question cannot be asked without the results.

**How to run cross-verification in parallel:**
```
// Execute 1st and 2nd verification simultaneously (main agent performs directly)
[Simultaneously] Directly query primary MS Docs page via web_fetch (1st)
[Simultaneously] Additionally query related MS Docs page via web_fetch (2nd)
// Compare both results to check for discrepancies
// e.g., Model availability → parallel fetch of models page + regional availability page
```

**NEVER do this:**
- Run in background when results are needed, then sit idle doing nothing while waiting
- Delegate tasks requiring web_fetch/web_search to sub-agents (main agent MUST perform directly)
- Attempt to directly read files internal to sub-agents

---

**⚠️ Important: Do NOT execute any shell commands until the user explicitly approves proceeding to the next step.**
However, MS Docs web_fetch for the above fact checks is exceptionally allowed.

Once the architecture is confirmed (user said no changes to the diagram), ask the user whether to proceed to the next step.

**🚨 Phase 2 Transition Prerequisites — ALL of the following must be met before asking this question:**

1. `01_arch_diagram_draft.html` has been **generated** using the built-in diagram engine
2. The diagram has been **opened in the browser** and **displayed to the user** in the report format with the **configuration table**
3. The user was asked **"Would you like to change or add anything?"** and responded with **no changes**, or modifications have been reflected and **final confirmation** is given

**If ANY of the above conditions are not met, do NOT proceed to Phase 2.**
If the diagram does not exist yet, **generate it right now** — follow the procedure in section 1-2.
If the configuration table was not shown, **show it right now** before asking about changes.

**Following the parallel preload principle, execute `az account list` and `az group list` simultaneously with ask_user to prepare subscription/RG choices in advance.**

```
// Call simultaneously in the same response:
[1] ask_user — "The architecture is confirmed! Shall we proceed to the next step?"
[2] powershell — az account show 2>&1              (pre-check login status)
[3] powershell — az account list --output json      (pre-prepare subscription choices)
[4] powershell — az group list --output json        (pre-prepare resource group choices)
```

ask_user display format:
```
The architecture is confirmed! Shall we proceed to the next step?

✅ Confirmed architecture: [summary]

The following steps will proceed:
1. [Bicep Code Generation] — AI automatically writes IaC code
2. [Code Review] — Automated security/best practice review
3. [Azure Deployment] — Actual resource creation (optional)

Shall we proceed? (If you'd like just the code without deployment, let me know)
```

Once the user approves, collect information in the following order.
**Since `az account show` + `az account list` + `az group list` were already completed during preload, subscription/RG choices can be presented immediately.**

**Step 1: Azure Login Verification**

The `az account show` result is already available from preload. No additional call needed.

- If logged in → Move to Step 2
- If not logged in → Guide the user:
  ```
  Azure CLI login is required. Please run the following command in your terminal:
  az login
  Please let me know once completed.
  ```

**Step 2: Subscription Selection**

The `az account list` result is already available from preload. No additional call needed.

Provide up to 4 subscriptions from the query results as `ask_user` choices.
If there are 5 or more, include the 3-4 most frequently used subscriptions as choices (users can also type a custom input).
Once the user selects, execute `az account set --subscription "<ID>"`.

**Step 3: Resource Group Confirmation**

The `az group list` result is already available from preload. No additional call needed.

Provide up to 4 existing resource groups from the list as `ask_user` choices.
If the user selects an existing group, use it as-is; if they type a new name as custom input, create it during Phase 4 deployment.

**Required confirmed items:**
- [ ] Service list and SKUs
- [ ] Networking method (Private Endpoint usage)
- [ ] Subscription ID (confirmed in Step 2)
- [ ] Resource group name (confirmed in Step 3)
- [ ] Location (confirmed with user — regional availability per service verified via MS Docs)

---

## 🚨 Phase 1 Completion Checklist — Required Verification Before Phase 2 Entry

Before leaving Phase 1, verify **ALL** items below. If any are incomplete, do NOT proceed to Phase 2.

| # | Item | Verification Method |
|---|------|---------------------|
| 1 | All required specs confirmed | Project name, services, SKUs, region, and networking method are all confirmed |
| 2 | Fact check completed | MS Docs cross-verification has been performed |
| 3 | **Diagram generated** | `01_arch_diagram_draft.html` file has been generated using the built-in diagram engine |
| 4 | **Configuration table shown** | Detailed table with Service/Type/SKU/Details displayed to user in report format |
| 5 | **User reviewed diagram** | Browser auto-open + report format + "anything to change?" question asked |
| 6 | User final approval | User confirmed no changes, then selected "proceed to next step" |

**⚠️ Do NOT ask item 6 while items 3-5 are incomplete.** The flow must be: diagram → table → ask changes → confirm → next step.

---

## Phase 2 Handoff: Bicep Generation Agent

Once the user agrees to proceed, read the `references/bicep-generator.md` instructions and generate the Bicep template.
Alternatively, this can be delegated to a separate sub-agent.

**Sensitive Information Handling Principle (NEVER violate):**
- NEVER ask for VM passwords, API keys, or other sensitive values in chat, and NEVER store them in parameter files
- During code review, if sensitive values are found in plaintext in `main.bicepparam`, remove them immediately

**🔹 User-Input Sensitive Values Like VM Passwords — Complexity Validation Required:**

When the user inputs a VM admin password or similar, validate complexity requirements **before** sending to Azure.
Azure VMs must satisfy ALL of the following conditions:
- 12 characters or more
- Contains at least 3 of: uppercase letters, lowercase letters, numbers, special characters

**On validation failure:** Do NOT attempt deployment; immediately ask the user to re-enter:
> **⚠️ The password does not meet Azure complexity requirements.** It must be 12 characters or more and contain at least 3 of: uppercase + lowercase + numbers + special characters.

**NEVER do this:**
- Warn "it may not meet requirements" but attempt deployment anyway — **MUST block**
- Send to Azure without complexity validation, causing deployment failure

**🚨 `@secure()` Parameter and `.bicepparam` Compatibility Principle:**

When a `.bicepparam` file has a `using './main.bicep'` directive, additional `--parameters` flags CANNOT be used together with `az deployment group what-if/create`.
Therefore, `@secure()` parameter handling follows these rules:

1. **`@secure()` parameters MUST have default values** — Use Bicep functions like `newGuid()`, `uniqueString()`
   ```bicep
   @secure()
   param sqlAdminPassword string = newGuid()  // Auto-generated at deployment, store in Key Vault if needed
   ```
2. **If there are `@secure()` parameters that require user-specified values:**
   - Do NOT use `.bicepparam` file; instead use `--template-file` + `--parameters` combination
   - Or generate a separate JSON parameter file (`main.parameters.json`)
   ```powershell
   # When .bicepparam cannot be used — substitute with JSON parameter file
   az deployment group what-if `
     --template-file main.bicep `
     --parameters main.parameters.json `
     --parameters sqlAdminPassword='user-input-value'
   ```
3. **Do NOT use `.bicepparam` and `--parameters` simultaneously in a deployment command**
   ```
   ❌ az deployment group create --parameters main.bicepparam --parameters key=value
   ✅ az deployment group create --parameters main.bicepparam
   ✅ az deployment group create --template-file main.bicep --parameters main.parameters.json --parameters key=value
   ```

**Decision criteria:**
- All `@secure()` parameters have default values (newGuid, etc.) → `.bicepparam` can be used
- Any `@secure()` parameter requires user input → Use JSON parameter file instead of `.bicepparam`

**When MS Docs fetch fails:**
- If web_fetch fails due to rate limiting, etc., MUST notify the user:
  ```
  ⚠️ MS Docs API version lookup failed. Generating with the last known stable version.
  Verifying the actual latest version before deployment is recommended.
  Shall we continue?
  ```
- Do NOT silently proceed with a hardcoded version without user approval

**Pre-Bicep generation reference files:**
- `references/service-gotchas.md` — Required properties, common mistakes, PE groupId/DNS Zone mapping
- `references/ai-data.md` — AI/Data service configuration guide (v1 domain)
- `references/azure-common-patterns.md` — PE/security/naming common patterns
- `references/azure-dynamic-sources.md` — MS Docs URL registry (for API version fetch)
- For services not covered in the above files, directly fetch MS Docs to verify resource types, properties, and PE mappings

**Output structure:**
```
<project-name>/
├── main.bicep              # Main orchestration
├── main.bicepparam         # Parameters (environment-specific values)
└── modules/
    ├── network.bicep       # VNet, Subnet (including private endpoint subnet)
    ├── ai.bicep            # AI services (configured per user requirements)
    ├── storage.bicep       # ADLS Gen2 (isHnsEnabled: true)
    ├── fabric.bicep        # Microsoft Fabric (if needed)
    ├── keyvault.bicep      # Key Vault
    └── private-endpoints.bicep  # All PEs + DNS Zones
```

**Bicep mandatory principles:**
- Parameterize all resource names — `param openAiName string = 'oai-${uniqueString(resourceGroup().id)}'`
- Private services MUST have `publicNetworkAccess: 'Disabled'`
- Set `privateEndpointNetworkPolicies: 'Disabled'` on pe-subnet
- Private DNS Zone + VNet Link + DNS Zone Group — all 3 required
- When using Microsoft Foundry, **Foundry Project (`accounts/projects`) MUST be created alongside** — without it, the portal is unusable
- ADLS Gen2 MUST have `isHnsEnabled: true` (omitting this creates a regular Blob Storage)
- Store secrets in Key Vault, reference via `@secure()` parameters
- Add English comments explaining the purpose of each section

Immediately transition to Phase 3 after generation is complete.

---

## Phase 3 Handoff: Bicep Review Agent

Review according to `references/bicep-reviewer.md` instructions.

**⚠️ Key Point: Do NOT just visually inspect and say "pass". You MUST run `az bicep build` to verify actual compilation results.**

```powershell
az bicep build --file main.bicep 2>&1
```

1. Compilation errors/warnings → Fix
2. Checklist review → Fix
3. Re-compile to confirm
4. Report results (including compilation results)

For detailed checklists and fix procedures, see `references/bicep-reviewer.md`.

After review is complete, show the user the results before transitioning to Phase 4, and **MUST guide the user on the next steps.**

**🚨 Required Report Format When Phase 3 Is Complete:**

```
## Bicep Code Review Complete

[Review result summary — bicep-reviewer.md Step 6 format]

---

**Next Step: Phase 4 (Azure Deployment)**

The review is complete. The following steps will proceed:
1. **What-if Validation** — Preview planned resources without making actual changes
2. **Preview Diagram** — Architecture visualization based on What-if results (02_arch_diagram_preview.html)
3. **Actual Deployment** — Create resources in Azure after user confirmation

Shall we proceed with deployment? (If you'd like just the code without deployment, let me know)
```

**NEVER do this:**
- Completing Phase 3 and just providing the `az deployment group create` command without further guidance
- Deploying directly without What-if validation, or telling the user to run commands themselves
- Skipping the Phase 4 steps (What-if → Preview Diagram → Deployment)