Skip to content

Agent Architecture

Agent Anatomy

Every agent definition follows a standard structure:

# Frontmatter
---
name: 06b-Bicep CodeGen
description: Expert Azure Bicep IaC specialist...
model: ["Claude Opus (latest)"] # (1)!
tools: [list of allowed tools] # (2)!
handoffs:
  - label: "Step 6: Deploy"
    agent: 07b-Bicep Deploy # (3)!
    prompt: "Deploy the Bicep templates..."
---
# Body (≤ 350 lines)
## MANDATORY: Read Skills First
1. **Read** `.github/skills/azure-defaults/SKILL.md` # (4)!
2. **Read** `.github/skills/azure-artifacts/SKILL.md`
  1. Model selection — the Conductor can override this based on task complexity
  2. Tool allowlist — agents only access tools they need
  3. Handoff target — the next agent in the workflow
  4. Skills are loaded on demand to preserve context budget

The frontmatter is machine-readable metadata. The body is the agent's operating manual, loaded into the system prompt when the agent is invoked.

Tools

Agents interact with external systems through tools — structured interfaces provided by MCP servers and the VS Code runtime. Each agent's frontmatter declares a tools: allowlist that restricts which tools it can call. Common tool categories:

  • MCP tools: Cloud API wrappers (Azure pricing queries, GitHub operations, Terraform registry lookups)
  • File tools: Read and write workspace files (create artifacts, read prior step outputs)
  • Terminal tools: Execute CLI commands (Bicep build, Terraform validate, Azure CLI)
  • Subagent tools: Delegate to specialised subagents via #runSubagent

Handoffs

Agents do not communicate directly. Instead, each agent produces artifact files in agent-output/{project}/ that the next agent reads as input. The Conductor orchestrates this by delegating to one agent at a time, collecting its output, and routing to the next step. At approval gates, the Conductor writes a 00-handoff.md summary document that enables session resume.

Top-Level Agents (16)

Agent Role Primary Skills
01-Conductor Master orchestrator workflow-engine, session-resume
01-Conductor (Fast Path) Simplified path for ≤3 resources session-resume, azure-defaults
02-Requirements Captures project requirements azure-defaults, azure-artifacts
03-Architect WAF assessment and cost estimation azure-defaults
04-Design Diagrams and ADRs azure-diagrams, azure-adr
04g-Governance Policy discovery and compliance azure-defaults
05b-Bicep Planner Bicep implementation planning azure-bicep-patterns
05t-Terraform Planner Terraform implementation planning terraform-patterns
06b-Bicep CodeGen Bicep template generation azure-bicep-patterns
06t-Terraform CodeGen Terraform configuration generation terraform-patterns
07b-Bicep Deploy Bicep deployment execution iac-common
07t-Terraform Deploy Terraform deployment execution iac-common, terraform-patterns
08-As-Built Post-deployment documentation azure-artifacts, azure-diagrams
09-Diagnose Azure resource troubleshooting azure-troubleshooting
10-Challenger Standalone adversarial review —
11-Context Optimizer Context window audit and optimisation context-optimizer

Subagents (11)

Subagents are not user-invocable. They are delegated to by parent agents for isolated, specific tasks:

Subagent Purpose Invoked By
challenger-review-subagent Adversarial review of artifacts Steps 1, 2, 4, 5, 6
challenger-review-batch-subagent Batch multi-lens adversarial review Steps 2, 4, 5
challenger-review-codex-subagent Fast adversarial review (Codex model) Steps 2, 4
cost-estimate-subagent Azure Pricing MCP queries Steps 2, 7
governance-discovery-subagent Azure Policy discovery via REST API Step 4
bicep-lint-subagent bicep build + bicep lint Step 5 (Bicep)
bicep-review-subagent Code review against AVM standards Step 5 (Bicep)
bicep-whatif-subagent az deployment what-if preview Step 6 (Bicep)
terraform-lint-subagent terraform fmt + terraform validate Step 5 (Terraform)
terraform-review-subagent Code review against AVM-TF standards Step 5 (Terraform)
terraform-plan-subagent terraform plan preview Step 6 (Terraform)

The Challenger Pattern

Adversarial Review

The Challenger finds what everyone else missed — untested assumptions, governance gaps, WAF blind spots, and architectural weaknesses.

The challenger-review-subagent implements adversarial review at critical workflow steps. It operates with rotating lenses:

  • 1-pass review (comprehensive): A single review covering all dimensions. Used for requirements (Step 1) and deploy (Step 6).
  • 3-pass review (rotating lenses): Three separate reviews, each focused on a specific dimension (security, reliability, cost). Used for architecture (Step 2), planning (Step 4), and code (Step 5).

Findings are classified as must_fix (blocking) or should_fix (advisory). Only must_fix findings block workflow progression.

Conditional Pass 3: Pass 3 of the 3-pass rotating lens review is now conditional — it only runs if Pass 2 returned ≥1 must_fix finding. If Pass 2 returns zero must_fix items, Pass 3 is skipped entirely, saving approximately 4 minutes per review cycle.

Context Shredding for Challenger Inputs: The challenger applies context compression tiers when loading predecessor artefacts for review:

Context Usage Loading Strategy
< 60% Full artefact
60–80% Key H2 sections only (resource list, SKUs, WAF scores, budget)
> 80% Decision summary from 00-session-state.json + resource list

This achieves 40–70% input reduction for heavy artefacts. After each review pass, only the compact_for_parent string is carried forward (not the full JSON findings), preventing context bloat across multi-pass reviews.

If a challenger review hangs

If a review takes >10 minutes with no output, restart the chat session and resume from the failed gate. Use 00-session-state.json to verify the last completed step.

New Challenger Checklists: Two mandatory checklist categories were added:

  • Cost Monitoring: Budget resource, forecast alerts at 80/100/120%, anomaly detection.
  • Repeatability: Parameterised values, multi-tenant deploy, projectName required.

Handoffs and Delegation

Agents communicate through artefact files, not direct message passing. The Conductor delegates to a step agent, which produces output files in agent-output/{project}/. The next agent reads those files as input. This design:

  • Eliminates context leakage between agents
  • Enables resume from any point (artefacts are persistent)
  • Allows human review at every gate (artefacts are human-readable markdown)
  • Supports parallel development of different steps

Phase Handoff Document: At each approval gate, the Conductor writes a 00-handoff.md file containing a summary of what was completed, key decisions made, what comes next, and (at Gates 2 and 3) a session break recommendation. This enables resume from any gate without needing to re-read all prior artefacts.

Further Reading