azv-bicep-diagram-sync

name	azv-bicep-diagram-sync
description	Compare Bicep templates against a Draw.io Azure architecture diagram to detect resource-level divergence. Reports differences and offers resolution — update Bicep to match the diagram, update the diagram to match Bicep, or selectively resolve per resource.
license	MIT
metadata	{"author":"AzVerify","version":"1.0","project":"AzVerify"}

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.

7. Resolution: Update Bicep

If the user chooses to update Bicep to match the diagram:

7a. Confirm changes

## Confirm Bicep Changes

The following changes will be made to the Bicep templates:

**Add to Bicep** (Diagram-only resources):
- cosmos-db (Microsoft.DocumentDB/databaseAccounts)

**Remove from Bicep** (Bicep-only resources):
- redis-cache (Microsoft.Cache/redis) — in modules/data.bicep

⚠️ Removing resources from Bicep templates means they will no longer be part of deployments.

Proceed? (yes/no)

Wait for explicit confirmation. If the user says no, return to Step 6.

7b. Run deployment verification

Before generating Bicep, read and run the verification rules from .github/skills/shared/azure-deployment-verification.md:

1. SKU dependency rules — verify companion resources exist
2. Resource compatibility rules — verify backend protocols, DNS zones
3. Networking rules — verify subnet sizing, no overlaps
4. Security rules — verify TLS 1.2+, HTTPS, @secure() decorators
5. Version currency rules — verify runtime stacks and API versions are current

7c. Apply Bicep changes

For Diagram-only resources (add to Bicep):

1. Determine the appropriate module file based on resource type:
   • Networking resources → modules/networking.bicep
   • Compute resources → modules/compute.bicep
   • Data/storage resources → modules/data.bicep
   • If no matching module exists, create one
2. Generate the resource block following the rules in .github/skills/shared/bicep-best-practices.md
3. Use configuration defaults from .github/skills/shared/azure-resource-configs.md
4. Add parameters to main.bicep and the .bicepparam file with descriptive comments
5. Follow Bicep best practices: parent: for child resources, @secure(), @description(), symbolic references

For Bicep-only resources (remove from Bicep):

1. Remove the resource block from the module file
2. Remove associated parameters from main.bicep and the .bicepparam file
3. Remove module references in main.bicep if the module file is now empty
4. Remove empty module files

7d. Present result

## Bicep Updated ✓

**Added:** 1 resource (cosmos-db)
**Removed:** 1 resource (redis-cache)

The Bicep templates now match the diagram.

| File | Changes |
|------|---------|
| main.bicep | Added cosmos-db module reference; removed redis-cache reference |
| modules/data.bicep | Added Cosmos DB resource; removed Redis Cache resource |
| <name>.bicepparam | Added cosmos-db parameters; removed redis-cache parameters |

⚠️ Review the updated `.bicepparam` file — new parameters use defaults that you may want to customize.

8. Resolution: Update Diagram

If the user chooses to update the diagram to match Bicep:

8a. Confirm changes

## Confirm Diagram Changes

The following changes will be made to the diagram:

**Add to diagram** (Bicep-only resources):
- redis-cache (Redis Cache)

**Remove from diagram** (Diagram-only resources):
- cosmos-db (Cosmos DB)

⚠️ Removing resources from the diagram is irreversible unless you have a backup.

Proceed? (yes/no)

Wait for explicit confirmation. If the user says no, return to Step 6.

8b. Generate updated diagram

1. Load the existing diagram XML
2. For Bicep-only resources (add to diagram):
   • Look up each resource type in .github/skills/shared/azure-stencil-mapping.json for the correct icon and style
   • Add new mxCell elements with proper Azure icons
   • Place new resources in the correct container based on their module file and any parent relationships in Bicep
   • For container resources (VNets, Subnets), create both the container cell and its icon child cell using the dual icon pattern
3. For Diagram-only resources (remove from diagram):
   • Remove the corresponding mxCell elements from the XML
   • Also remove any associated icon cells (cells with id ending in -icon)
   • Remove any edges connected to removed cells
4. Re-layout the diagram to accommodate changes (adjust container sizes, reposition as needed)
5. Save the updated diagram via the Draw.io MCP tool

8c. Present result

## Diagram Updated ✓

**Added:** 1 resource (redis-cache)
**Removed:** 1 resource (cosmos-db)

The diagram now matches the Bicep templates.
Saved to `<diagram-path>`.

9. Resolution: Selective

If the user chooses selective resolution:

For each drifted resource, present the options:

### Resource: cosmos-db (Cosmos DB) — Diagram Only

This resource exists in the diagram but not in the Bicep templates.

1. **Add to Bicep** — Generate a Cosmos DB resource block in modules/data.bicep
2. **Remove from Diagram** — Remove this resource from the diagram
3. **Skip** — Leave this resource unresolved

Choice? (1/2/3)

Apply the user's choice for each resource following the same logic as Steps 7 and 8.

After all resources are resolved, present a summary:

## Selective Resolution Complete ✓

| Resource | Type | Action |
|----------|------|--------|
| cosmos-db | Cosmos DB | Added to Bicep |
| redis-cache | Redis Cache | Removed from Bicep |
| old-function | Function App | Skipped |

Remaining drift: 1 resource (old-function)