Agentic InfraOps Accelerator

Modernize your Azure Infrastructure with AI. A production-ready template for building Well-Architected environments using custom Copilot agents, Dev Containers, and the Model Context Protocol (MCP).

Overview

This accelerator provides the scaffolding and governance to move from requirements to deployed infrastructure using an orchestrated multi-agent workflow. It leverages domain-specific AI agents to ensure every deployment is Well-Architected, governed, and documented.

What you get: 14 specialized agents, 18 skills, 27 validation scripts, a full dev container with all tools pre-installed, and an optional weekly sync workflow that keeps your agents and skills up to date with the upstream project.

---

Multi-Agent Workflow

Agentic InfraOps coordinates specialized AI agents through a complete infrastructure development cycle. Invoke the InfraOps Conductor (Ctrl+Shift+I) to begin.

sequenceDiagram
    autonumber
    participant U as 👤 User
    participant C as 🎼 Conductor
    participant R as 📋 Requirements
    participant A as 🏛️ Architect
    participant P as 📐 IaC Plan
    participant B as ⚒️ IaC Code
    participant D as 🚀 Deploy
    participant W as 📚 As-Built

    Note over C: ORCHESTRATION LAYER<br/>AI prepares. Humans decide.

    U->>C: Describe infrastructure intent
    C->>R: Translate intent into structured requirements
    R-->>C: 01-requirements.md
    C->>U: Present requirements

    rect rgba(255, 200, 0, 0.15)
    Note over U,C: 🛑 HUMAN APPROVAL GATE
    U-->>C: Approve requirements
    end

    C->>A: Assess architecture (WAF + Cost)
    Note right of A: cost-estimate-subagent<br/>handles pricing queries
    A-->>C: 02-assessment.md + 03-cost-estimate.md
    C->>U: Present architecture

    rect rgba(255, 200, 0, 0.15)
    Note over U,C: 🛑 HUMAN APPROVAL GATE
    U-->>C: Approve architecture
    end

    C->>P: Create implementation plan + governance
    Note right of P: governance-discovery-subagent<br/>queries Azure Policy via REST API
    P-->>C: 04-plan.md + governance constraints
    C->>U: Present plan

    rect rgba(255, 200, 0, 0.15)
    Note over U,C: 🛑 HUMAN APPROVAL GATE
    U-->>C: Approve plan
    end

    C->>B: Generate IaC templates (AVM-first)
    B-->>C: infra/bicep/{project} or infra/terraform/{project}

    rect rgba(0, 150, 255, 0.08)
    Note over C,B: 🔍 Subagent Validation Loop
    Note right of B: lint-subagent → PASS/FAIL<br/>review-subagent → APPROVED/REVISION
    alt ✅ Validation passes
        C->>U: Present templates for deployment
        rect rgba(255, 200, 0, 0.15)
        Note over U,C: 🛑 HUMAN APPROVAL GATE
        U-->>C: Approve for deployment
        end
    else ⚠️ Validation fails
        C->>B: Revise with feedback
    end
    end

    C->>D: Execute deployment
    Note right of D: what-if/plan-subagent<br/>previews changes first
    D-->>C: 06-deployment-summary.md
    C->>U: Present deployment summary

    rect rgba(255, 200, 0, 0.15)
    Note over U,D: 🛑 HUMAN VERIFICATION
    U-->>C: Verify deployment
    end

    C->>W: Generate workload documentation
    Note right of W: Reads all prior artifacts (01-06)<br/>+ queries deployed resource state
    W-->>C: 07-*.md documentation suite
    C->>U: Present as-built docs

    Note over U,W: ✅ AI Orchestrated. Human Governed. Azure Ready.

Loading

---

Prerequisites

Requirement	Details
VS Code	Latest stable release
GitHub Copilot	Active license (Individual, Business, or Enterprise)
Docker Desktop	For the dev container (or GitHub Codespaces)
Azure subscription	Optional for Steps 1-5; required for Step 6 (Deploy)

---

Quick Start

1. Create Your Repository

This repository is a GitHub Template — not a fork.

1. Click "Use this template" → "Create a new repository" at the top of this page
2. Choose an owner and name (e.g., my-infraops-project)
3. Select Public or Private
4. Click Create repository

Your new repo has the same directory structure and files but a clean commit history and no fork relationship. It is entirely yours.

2. Clone and Open in Dev Container

git clone https://github.com/YOUR-USERNAME/my-infraops-project.git
cd my-infraops-project
code .

When prompted by VS Code, click "Reopen in Container" (or run Dev Containers: Reopen in Container from the Command Palette). The container build takes 3-5 minutes and pre-installs:

• Azure CLI with Bicep extension
• Terraform CLI with TFLint
• GitHub CLI (gh)
• Node.js + npm (validation scripts)
• Python 3 + pip (MCP server, diagram generation)
• Go (Terraform MCP server)

3. Initialize Your Repository

After the dev container starts, run the initialization commands:

npm install
npm run init
npm run sync:workflows

What these do:

Command	Purpose
npm install	Install Node.js dependencies (validation scripts, linting)
npm run init	One-time setup — replaces all references to the accelerator template repo with your repo's URL (auto-detected from git remote). Run npm run init -- --dry-run first to preview changes.
npm run sync:workflows	Fetches the latest GitHub Actions workflows from the upstream project into your .github/workflows/ directory

After running, review and commit:

git diff
git add -A && git commit -m "chore: initialize from template"

4. Authenticate (Optional)

# Required only for Step 6 (Deploy) and governance discovery
az login

5. Verify VS Code Settings

The dev container configures these automatically, but confirm they are active:

{
  "chat.customAgentInSubagent.enabled": true
}

This setting is required for the Conductor to delegate to specialized agents. If agents don't appear in the Ctrl+Shift+A picker, check that the setting is in your VS Code User Settings (not just workspace settings).

6. Start the Conductor

1. Open Copilot Chat (Ctrl+Shift+I)
2. Select InfraOps Conductor from the agent picker
3. Describe your infrastructure intent: "I need a web application with a SQL database, Key Vault, and Application Insights in Azure"
4. The Conductor guides you through all 8 steps with human approval gates

---

Project Structure

Once you are working in your repo, here is what lives where:

.github/
  agents/              # Agent definitions (*.agent.md)
    _subagents/        # Subagent definitions (non-user-invocable)
  skills/              # Reusable domain knowledge (SKILL.md per skill)
  instructions/        # File-type rules with glob-based auto-application
  copilot-instructions.md  # VS Code Copilot-specific orchestration instructions
  workflows/           # GitHub Actions (sync, CI, validation)
agent-output/          # Generated artifacts organized by project
  {project}/           # 01-requirements.md through 07-*.md
infra/
  bicep/{project}/     # Bicep templates (main.bicep + modules/)
  terraform/{project}/ # Terraform configurations (main.tf + modules/)
mcp/                   # MCP servers (Azure Pricing)
scripts/               # Validation scripts (27 validators)
docs/                  # Documentation site source

What's Yours vs. What's Upstream

Your files (safe to edit, never overwritten by sync)	Upstream-managed files (overwritten by sync)
agent-output/ — generated project artifacts	.github/agents/ — agent definitions
infra/bicep/ — your Bicep templates	.github/skills/ — agent skills
.github/workflows/ — your CI/CD workflows	.github/instructions/ — coding rules
README.md — your documentation	.github/copilot-instructions.md
	scripts/, docs/, mcp/, package.json
	AGENTS.md, .devcontainer/, .vscode/

Note: If you disable the sync workflow, everything becomes yours to edit freely. See Customization below.

---

Customization

Changing defaults (regions, tags, naming)

When you create from this template, every file is yours. The question is which approach gives you the best experience over time.

Strategy A: Edit directly (simplest)

Edit the file you need — for example, change swedencentral to westeurope in .github/skills/azure-defaults/SKILL.md. If you don't plan to pull upstream improvements, disable the sync workflow entirely (repo Settings → Actions → disable Upstream Sync) and manage the repo as your own.

If you want upstream updates later, re-enable the workflow. The sync PR will overwrite your edited files with the upstream version (it is not a merge), so you'll need to re-apply your changes after merging. Keep a record of what you changed.

Strategy B: Keep sync enabled, layer your overrides (recommended for teams that want continuous upstream improvements)

The sync workflow overwrites all upstream-managed files but never touches the four excluded paths. To safely store overrides that survive sync:

1. Edit the sync exclusion list — the sync workflow file itself is user-owned (.github/workflows/ is excluded from sync). Open .github/workflows/weekly-upstream-sync.yml and add paths to EXCLUDE_PATHS and the matching for path in ... loop:

   EXCLUDE_PATHS: |
     .github/workflows/
     agent-output/
     infra/bicep/
     infra/terraform/
     README.md
     AGENTS.md

   Then add your overrides to root AGENTS.md — it will survive all future syncs.

2. Use infra/bicep/AGENTS.md — since infra/bicep/ is already excluded from sync, you can place an AGENTS.md there with your organization defaults. VS Code loads subfolder AGENTS.md files when working with files in that directory.

3. VS Code user-profile instructions — place a .instructions.md file in your VS Code profile's prompts/ folder. This lives outside the repo entirely and applies to all your workspaces.

Which strategy to pick?

Approach	Best for
A: Edit directly, skip sync	Solo users, teams that self-manage updates
B: Layer overrides, keep sync	Teams that want automatic upstream improvements

Adding new agents or skills

Agents are defined in .github/agents/*.agent.md and skills in .github/skills/*/SKILL.md. You can add new ones alongside the existing set. If you keep sync enabled, use distinctive names that won't collide with upstream filenames, or add your custom paths to the sync exclusion list.

---

IaC Tracks: Bicep and Terraform

Both IaC tracks are fully supported. The Requirements agent (Step 1) captures your iac_tool preference, and the Conductor routes Steps 4-6 to the correct track.

Factor	Bicep	Terraform
Azure-only	Native DSL, first-class support	Multi-cloud via AzureRM provider
State	No state file (ARM-managed)	State file (Azure Storage backend)
AVM modules	br/public:avm/res/	registry.terraform.io/Azure/avm-res-*/
CI/CD	az deployment group create	terraform plan + terraform apply

---

Multi-Project Support

The accelerator is designed for one repo containing multiple projects. Each project gets its own folders:

• agent-output/{project}/ — artifacts (requirements, architecture, plans, docs)
• infra/bicep/{project}/ or infra/terraform/{project}/ — IaC templates

Agents, skills, instructions, and the dev container are shared across all projects.

One repo per project is also valid when teams need separate governance or isolation. Each repo is created independently from the template.

Sharing customizations across repos or teams

• Edit the sync exclusion list in each repo to protect AGENTS.md, then maintain a standard overrides section that you copy into each repo
• VS Code user-profile instructions — personal preferences that follow you across repos without any per-repo setup
• Canonical overrides in a shared location — maintain a standard overrides snippet in a team wiki or internal repo and copy it when creating new instances

---

Keeping Up to Date

What	How	Frequency
Agents, skills, instructions, docs, scripts	Automated weekly PR (upstream sync workflow)	Weekly
GitHub Actions workflows	npm run sync:workflows (manual)	As needed
All validations	npm run validate:all	Before each PR

The sync workflow opens a PR for human review — it never auto-merges. You can disable it entirely if you prefer to manage updates manually.

---

Validation & Quality

# Run all code and documentation validations
npm run validate:all

# Fix markdown formatting
npm run lint:md:fix

# Bicep validation (replace {project})
bicep build infra/bicep/{project}/main.bicep
bicep lint infra/bicep/{project}/main.bicep

# Terraform validation
terraform fmt -check -recursive infra/terraform/
cd infra/terraform/{project} && terraform init -backend=false && terraform validate

---

Resources

• Upstream project (azure-agentic-infraops)
• Full documentation site
• MicroHack (hands-on exercises)
• Prompt Guide
• FAQ

License

MIT