Shared Agent Configuration

Shared Agent Configuration

This file contains shared configuration values that all agents should reference to maintain consistency.

Note: Agents should import these defaults rather than duplicating them.

⚠️ See Also: AVM Pitfalls for known AVM parameter issues and region limitations.

Default Regions

Region Limitations (IMPORTANT)

Some Azure services do not support all regions:

Action: When planning Static Web Apps, hardcode westeurope region, not the location parameter.

Region Selection Guidelines

• Default (no constraints): Use swedencentral
• German data residency: Use germanywestcentral
• Swiss banking/healthcare: Use switzerlandnorth
• UK GDPR requirements: Use uksouth
• APAC latency optimization: Use southeastasia

Required Tags

All Azure resources MUST include these tags:

Bicep Tag Pattern

var tags = {
  Environment: environment
  ManagedBy: 'Bicep'
  Project: projectName
  Owner: owner
  CostCenter: costCenter
  DeploymentDate: utcNow('yyyy-MM-dd')
}

CAF Naming Conventions

Follow Cloud Adoption Framework pattern: {type}-{workload}-{env}-{region}-{instance}

Region Abbreviations

Resource Type Prefixes

Azure Pricing MCP - Service Name Reference

When using Azure Pricing MCP tools (azure_price_search, azure_cost_estimate), use these exact service names:

Tier Keywords

Use tier keywords (Basic, Standard, Premium, Free, Consumption) directly as sku_name. The MCP automatically searches both productName and skuName fields for these.

Example Queries

# Correct usage
azure_price_search(service_name="SQL Database", sku_name="Basic", region="swedencentral")
azure_price_search(service_name="Azure App Service", sku_name="B1", region="swedencentral")
azure_price_search(service_name="Service Bus", sku_name="Basic", region="swedencentral")

# Incorrect - will return 0 results
azure_price_search(service_name="Azure SQL", sku_name="Basic")  # Wrong service name
azure_price_search(service_name="Container Apps", sku_name="Consumption")  # Missing "Azure" prefix

Azure Verified Modules (AVM)

MANDATORY: MUST use AVM modules for all resources where available.

Raw Bicep resources are only permitted when:

1. No AVM module exists for the resource type (verified at https://aka.ms/avm/index)
2. User explicitly types "approve raw bicep" when prompted
3. The rationale is documented in the implementation plan/reference

AVM Approval Workflow

AVM Registry

• Registry: br/public:avm/res/*
• Documentation: https://aka.ms/avm
• GitHub: https://github.com/Azure/bicep-registry-modules/tree/main/avm/res
• Module Index: https://aka.ms/avm/index

Common AVM Modules (Verified January 2025)

⚠️ Version Freshness: Versions shown are minimums verified as of January 2025. Always check the AVM Module Index for latest versions before implementation.

How to Find Latest Versions

PREFERRED: Use MCP Tool (Automated)

# Call mcp_bicep_list_avm_metadata to get all AVM versions
# Returns JSON with modulePath, versions[], and documentationUri
# Latest version = LAST element in the versions array

Version Extraction Pattern:

{
  "modulePath": "avm/res/storage/storage-account",
  "versions": ["0.8.0", "0.9.0", ..., "0.31.0"],  // ← 0.31.0 is latest
  "documentationUri": "https://..."
}

Fallback Methods:

1. AVM Index: https://aka.ms/avm/index (searchable catalog)
2. GitHub Changelog: Each module has a CHANGELOG.md in its folder
3. Bicep Registry: bicep restore will fetch available versions
4. VS Code: Bicep extension provides version intellisense

Automated Version Checks

• GitHub Actions: .github/workflows/avm-version-check.yml runs weekly
• Agent Handoff: Use "▶ Refresh AVM Versions" in Bicep Plan agent
• GATE CHECK: Agents MUST call mcp_bicep_list_avm_metadata before planning

Well-Architected Framework (WAF) Pillars

Scoring Guidelines

Pillar Definitions

Security Defaults

All implementations MUST include:

Template-First Output Generation

All agents generating workflow artifacts MUST follow the template-first approach:

Before Generating Output

1. Read the template file - Load ../templates/{artifact}.template.md
2. Extract H2 headings - Note exact text and order of required sections
3. Prepare content - Organize responses to fit the template structure

Output Structure Rules

Attribution Header Format

# Step N: {Artifact Title} - {project-name}

> Generated by {agent-name} agent | {YYYY-MM-DD}
> **Confidence Level**: {High|Medium|Low}

Validation

All generated artifacts are validated by:

• Pre-commit hook: STRICTNESS=standard npm run lint:wave1-artifacts
• CI workflow: .github/workflows/wave1-artifact-drift-guard.yml
• Project-specific: npm run validate:{project-name} (if available)

Governance Discovery (MANDATORY for Bicep Plan)

CRITICAL: Governance constraints MUST be discovered from Azure Resource Graph, NOT assumed.

Why This Matters

Assumed governance causes deployment failures:

Discovery Workflow

Before creating 04-governance-constraints.md, execute these Azure Resource Graph queries:

1. Query all Policy Assignments with effects and enforcement mode
2. Query Tag Policies with actual parameter values (tag names)
3. Query Security Policies for TLS, HTTPS, encryption requirements

Required Output

04-governance-constraints.md MUST include:

## Discovery Source

| Query              | Results               | Timestamp  |
| ------------------ | --------------------- | ---------- |
| Policy Assignments | X policies discovered | {ISO-8601} |
| Tag Policies       | X tags required       | {ISO-8601} |

See full instructions: governance-discovery.instructions.md

Research Requirements (MANDATORY)

All agents MUST perform thorough research before implementation to ensure complete, one-shot execution without missing context or requiring multiple iterations.

Pre-Implementation Research Checklist

Before creating ANY output files or making changes:

• Search workspace for existing patterns (agent-output/, similar projects)
• Read relevant templates in .github/templates/ for output structure
• Query documentation via MCP tools (Azure docs, best practices)
• Validate inputs - confirm all required artifacts from previous steps exist
• Achieve 80% confidence before proceeding to implementation

Research Workflow Pattern

<research_mandate>
MANDATORY: Before producing output artifacts, run comprehensive research.

Step 1: Context Gathering
- Use semantic_search, grep_search, read_file to gather workspace context
- Use Azure MCP tools to query documentation and best practices
- Read template files to understand output structure

Step 2: Validation Gate
- Confirm required inputs from previous workflow steps exist
- Verify template has been loaded
- Check Azure guidance has been obtained

Step 3: Confidence Assessment
- Only proceed when you have 80% confidence in context understanding
- If below 80%, use #tool:agent to delegate autonomous research
- Or ASK the user for clarification rather than assuming
</research_mandate>

Delegation Pattern

When extensive research is needed, delegate to a subagent:

MANDATORY: Run #tool:agent tool, instructing the agent to work autonomously
without pausing for user feedback, to gather comprehensive context.

Service Recommendation Matrix

Use this matrix when recommending Azure services based on workload patterns. Present options to the user via askQuestions for confirmation.

Workload Pattern → Service Options

Tier Indicators

Detection Signals

Use these signals to identify workload patterns during requirements discovery:

Business Domain Signals

When users describe their project in business terms (not technical), use these signals to infer the workload pattern. Present the inference as a recommendation for user confirmation — do not ask the user to self-classify into technical categories.

Low-confidence signals (migration/modernization): When the user mentions migration or modernization, you MUST ask follow-up questions about the current system before inferring a pattern. Migration source determines target pattern:

Company Size Heuristics

Use company size to suggest appropriate default budget tier and scale expectations. These are starting points — always confirm with the user.

Industry Compliance Mapping

When a user mentions their industry, pre-select applicable compliance frameworks using recommended: true in askQuestions options.

Per-Agent Research Focus

See also: Agent Research Instructions