Quickstart

Get running in 10 minutes.

Template repository

You do not clone this repository directly. Instead, you create your own repository from the Accelerator template, which gives you a clean starting point with all agents, skills, and dev container configuration ready to go.

Prerequisites

What you need before starting

An Azure subscription is optional for learning the workflow — you only need it when deploying to Azure in Step 6.

Requirement	How to Get
GitHub account	Sign up
GitHub Copilot license	Get Copilot
VS Code	Download
Docker Desktop	Download
Azure subscription	Optional for learning

Docker is required

A Docker-compatible runtime is needed for the dev container. Docker Desktop is the most common choice. Free alternatives include Rancher Desktop, Colima (macOS), and Podman (Linux/macOS). See Dev Container Setup for detailed installation options.

Step 1: Create Your Repository from the Template

1. Go to the Accelerator template repository
2. Click the green “Use this template” button → “Create a new repository”
3. Choose an owner and repository name (e.g. my-infraops-project)
4. Select Public or Private visibility
5. Click Create repository

What is a template repository?

A GitHub template repository creates a brand-new repository with the same directory structure and files — but with a clean commit history and no fork relationship. Your repo is entirely yours.

Step 2: Clone and Open

Clone your new repository (not this upstream project):

git clone https://github.com/YOUR-USERNAME/my-infraops-project.git # (1)!
code my-infraops-project

1. Replace YOUR-USERNAME/my-infraops-project with your actual GitHub username and the repository name you chose in Step 1.

Step 3: Open in Dev Container

What is a dev container?

A dev container is a pre-configured development environment that runs inside a Docker container. It ensures every contributor has identical tools, extensions, and settings — no manual setup required. See the Dev Container Setup page for details.

1. Press F1 (or Ctrl+Shift+P)
2. Type: Dev Containers: Reopen in Container
3. Wait 3-5 minutes for setup

The Dev Container installs all tools automatically:

• Azure CLI + Bicep CLI
• Terraform CLI + TFLint
• PowerShell 7
• Python 3 + diagrams library
• Go (Terraform MCP server)
• 26 VS Code extensions

Step 4: Verify Setup

Verify all tools installed correctly

Run this command to confirm the dev container has all required CLIs:

az --version && bicep --version && terraform --version && pwsh --version # (1)!

1. All four CLIs should print version numbers. If any fail, reopen the dev container.

Step 5: Enable Subagent Orchestration

Required

The Conductor pattern requires this setting.

Add this to your VS Code User Settings (Ctrl+, → Settings JSON):

{
  "chat.customAgentInSubagent.enabled": true // (1)!
}

1. This must be in User Settings, not Workspace Settings. Experimental features require user-level configuration.

Why User Settings? Workspace settings exist in .vscode/settings.json, but user settings take precedence for experimental features like subagent invocation.

Verify it’s enabled:

1. Open Command Palette (Ctrl+Shift+P)
2. Type: Preferences: Open User Settings (JSON)
3. Confirm the setting is present

Step 6: Start the Conductor

Option A: InfraOps Conductor (Recommended)

The Conductor (🎼 Maestro), also known as the Coordinator, orchestrates the complete multi-step workflow:

1. Press Ctrl+Shift+I to open Copilot Chat
2. Select InfraOps Conductor from the agent dropdown
3. Describe your project:

Create a simple web app in Azure with:
- App Service for web frontend
- Azure SQL Database for data
- Key Vault for secrets
- Region: swedencentral
- Environment: dev
- Project name: my-webapp

The Conductor guides you through all steps with approval gates.

Option B: Direct Agent Invocation

Invoke agents directly for specific tasks:

1. Press Ctrl+Shift+A to open the agent picker
2. Select the specific agent (e.g., requirements)
3. Enter your prompt

Step 7: Follow the Workflow

The agents work in sequence with handoffs. Steps 1-3.5 and 7 are shared; steps 4-6 route to Bicep or Terraform agents based on your iac_tool selection in Step 1. During requirements gathering, the Requirements agent asks which IaC tool you prefer — this choice determines which planning, code generation, and deployment agents the Conductor invokes.

Each agent has a thematic codename for easy reference in documentation and prompts.

Step	Agent	Codename	What Happens
1	requirements	📜 Scribe	Captures requirements
2	architect	🏛️ Oracle	WAF assessment
3	design	🎨 Artisan	Diagrams/ADRs (optional)
3.5	governance	🛡️ Warden	Policy discovery/compliance
4	bicep-planner / terraform-planner	📐 Strategist	Implementation plan
5	bicep-codegen / terraform-codegen	⚒️ Forge	IaC templates
6	bicep-deploy / terraform-deploy	🚀 Envoy	Azure deployment
7	as-built	📚 Chronicler	Documentation suite

Approval Gates: The Conductor pauses at key points:

• ⛔ Gate 1: After requirements (Step 1) — confirm requirements
• ⛔ Gate 2: After architecture (Step 2) — approve WAF assessment
• ⛔ Gate 2.5: After governance (Step 3.5) — approve governance constraints
• ⛔ Gate 3: After planning (Step 4) — approve implementation plan
• ⛔ Gate 4: After validation (Step 5) — approve preflight results
• ⛔ Gate 5: After deployment (Step 6) — verify resources

If a gate rejects your proposal

If the Challenger or an approval gate produces must_fix findings, return to the previous step, update your approach based on the feedback, and re-run. The Conductor will re-execute the step and re-trigger the gate. Use the artifact files in agent-output/{project}/ to understand what was flagged.

What You’ve Created

After completing the workflow:

agent-output/my-webapp/
├── 01-requirements.md          # Captured requirements (includes iac_tool)
├── 02-architecture-assessment.md  # WAF analysis
├── 03-des-diagram.excalidraw   # Optional Step 3 architecture diagram
├── 04-implementation-plan.md   # Phased plan
├── 04-dependency-diagram.excalidraw  # Step 4 dependency diagram
├── 04-runtime-diagram.excalidraw     # Step 4 runtime diagram
├── 04-governance-constraints.md   # Policy discovery
├── 05-implementation-reference.md # Module inventory
├── 06-deployment-summary.md    # Deployed resources
└── 07-*.md                     # Documentation suite

# Bicep track output:
infra/bicep/my-webapp/
├── main.bicep                  # Entry point
├── main.bicepparam             # Parameters
└── modules/
    ├── app-service.bicep
    ├── sql-database.bicep
    └── key-vault.bicep

# — OR — Terraform track output:
infra/terraform/my-webapp/
├── main.tf                     # Entry point
├── variables.tf                # Input variables
├── outputs.tf                  # Outputs
├── terraform.tfvars            # Variable values
└── modules/
    ├── app-service/
    ├── sql-database/
    └── key-vault/

Next Steps

Goal	Resource
Understand the full workflow	workflow.md
Try a guided hands-on challenge	MicroHack
Try a complete workflow	Prompt Guide
Generate architecture diagrams	Use azure-diagrams skill
Create documentation	Use azure-artifacts skill
Explore Terraform patterns	Use terraform-patterns skill
Troubleshoot issues	troubleshooting.md
Contribute to the upstream repo	azure-agentic-infraops

Quick Reference

Conductor (Orchestrated Workflow)

Ctrl+Shift+I → InfraOps Conductor → Describe project → Follow gates

Direct Agent Invocation

Ctrl+Shift+A → Select agent → Type prompt → Approve

Skill Invocation

Skills activate automatically based on your prompt:

• “Create an architecture diagram” → azure-diagrams
• “Generate an ADR” → azure-adr
• “Create workload documentation” → azure-artifacts

Or invoke explicitly:

Use the azure-diagrams skill to create a diagram for my-webapp