Azv Bicep Diagram Sync

Compare Bicep templates in a solution folder against their source Draw.io diagram and resolve divergence.

Input: A solution folder containing Bicep templates (main.bicep, modules/*.bicep) and a Draw.io diagram file (.drawio or .drawio.xml). The user can specify the folder and diagram file, or the skill will auto-discover them.

Tools required: File system tools (read/write files), Draw.io MCP (mcp_drawio_create_diagram or mcp_draw_io_create_diagram), Bicep MCP server (for best-practice validation when regenerating Bicep)

Reference files:

• .github/skills/shared/azure-resource-model.md — Shared resource metadata model definition
• .github/skills/shared/azure-stencil-mapping.json — Azure resource type to Draw.io stencil mapping (used for reverse-lookup and diagram generation)
• .github/skills/shared/azure-resource-configs.md — Per-resource-type configuration schemas with defaults
• .github/skills/shared/azure-deployment-verification.md — Pre-deployment verification rules (MUST run before generating Bicep updates)

Shared procedures (MUST follow):

• .github/skills/shared/procedures/diagram-parsing.md — Diagram-to-resource-model parsing procedure
• .github/skills/shared/procedures/bicep-parsing.md — Bicep template parsing procedure
• .github/skills/shared/procedures/resource-matching.md — Resource matching algorithm

Steps

1. Accept Inputs

Identify the solution folder, the Bicep templates, and the Draw.io diagram to compare.

1a. Identify the Solution Folder

If the user specifies a folder path:

• Verify the folder exists
• Use it as the solution folder

If no folder is specified:

• Use the current workspace directory
• Search for folders containing both a .drawio file and a main.bicep file
• If exactly one such folder is found, use it (announce which folder)
• If multiple are found, present the list and ask the user to select one
• If none are found, ask the user to provide a solution folder

1b. Identify the Draw.io Diagram

If the user specifies a diagram file:

• Verify the file exists and is a .drawio or .drawio.xml file
• Read the file contents

If no diagram file is specified:

• Search the solution folder for .drawio files
• If exactly one is found, use it (announce which file)
• If multiple are found, present the list and ask the user to select one
• If none are found, report an error:

## No Diagram Found

No `.drawio` files found in the solution folder `<folder-path>`.
This skill requires a Draw.io diagram to compare against the Bicep templates.

• Stop execution

1c. Identify the Bicep Templates

• Search the solution folder for main.bicep
• If found, also scan for modules/*.bicep files
• If main.bicep is not found, report an error:

## No Bicep Templates Found

No `main.bicep` file found in the solution folder `<folder-path>`.
This skill requires Bicep templates to compare against the diagram.

• Stop execution

2. Parse Diagram into Resource Model

Follow the procedure in .github/skills/shared/procedures/diagram-parsing.md to parse the Draw.io XML into a structured resource model.

Display the parsed resource model as a table with columns: #, Resource, Type, Container.

3. Parse Bicep Templates into Resource Model

Follow the procedure in .github/skills/shared/procedures/bicep-parsing.md to parse all .bicep files in the solution folder.

Display the parsed Bicep resource model as a table with columns: #, Resource, Type, Source File, Notes.

4. Compare Resource Models

Follow the matching procedure in .github/skills/shared/procedures/resource-matching.md to compare the diagram resource model (Step 2) against the Bicep resource model (Step 3).

Additional classifications for this skill:

• In Sync (name differs) — single-instance type match with name mismatch
• Bicep Only — exists in Bicep templates but not in the diagram
• Diagram Only — exists in the diagram but not in the Bicep templates

Bicep-specific rules:

• Container resources: VNet containers in diagram should match Microsoft.Network/virtualNetworks in Bicep
• Conditional resources: Resources with if conditions are classified normally but noted as "conditional"

5. Present Drift Report

Display a clear drift report summarizing all differences.

Report format:

## Bicep-Diagram Sync Report: <diagram-name>

### Summary
- **In Sync:** N resources
- **Bicep Only:** N resources (in Bicep, not in diagram)
- **Diagram Only:** N resources (in diagram, not in Bicep)

### Details

| Resource | Type | Status | Notes |
|----------|------|--------|-------|
| my-vnet | VNet | ✅ In Sync | |
| my-vm | Virtual Machine | ✅ In Sync | |
| redis-cache | Redis Cache | ⬜ Bicep Only | In modules/data.bicep |
| cosmos-db | Cosmos DB | 🔷 Diagram Only | Not in Bicep templates |
| my-subnet | Subnet | ✅ In Sync (name differs) | Diagram: "default", Bicep: "snet-default" |

If fully in sync:

## Bicep-Diagram Sync Report: <diagram-name>

✅ **Fully in sync!** All N resources in the diagram match the Bicep templates.

No action needed.

If drift is detected, proceed to Step 6.

6. Offer Resolution Options

When drift is detected, present resolution options to the user.

### Resolution Options

Drift detected — how would you like to resolve it?

1. **Update Bicep** — Add diagram-only resources to Bicep templates, remove Bicep-only resources
2. **Update Diagram** — Add Bicep-only resources to diagram, remove diagram-only resources
3. **Selective** — Choose per-resource which direction to resolve
4. **No action** — Keep the report for reference, don't change anything

Which option? (1/2/3/4)

Wait for the user's choice before proceeding.