Artifact Generation Rules - MANDATORY

Artifact Generation Rules - MANDATORY

CRITICAL: This file is the SINGLE SOURCE OF TRUTH for artifact H2 headings. All agents MUST use these EXACT headings when generating artifacts. Violations block commits (pre-commit) and PRs (CI validation).

Pre-Generation Workflow

Before creating ANY artifact file, agents MUST:

1. FIND the section for your artifact type below (e.g., "06-deployment-summary.md")
2. COPY the EXACT H2 headings listed there
3. USE those headings in order in your generated artifact
4. ADD ## References at the end (always allowed)
5. ADD custom H3 subsections under H2s as needed

Template Mapping

All templates live in .github/skills/azure-artifacts/templates/:

Golden Rule

DO NOT INVENT H2 HEADINGS. Use ONLY the headings listed below for each artifact type.

Standard Components (Validated)

Every artifact (except PROJECT-README) must include these visual components above the first H2 heading. The validator checks for their presence.

Complete H2 Heading Reference

IMPORTANT: Copy-paste these headings. Do not paraphrase or abbreviate.

01-requirements.md

## Project Overview
## Functional Requirements
## Non-Functional Requirements (NFRs)
## Compliance & Security Requirements
## Budget
## Operational Requirements
## Regional Preferences
## Summary for Architecture Assessment
## References  <!-- Optional, add at end -->

H3 subsections (within H2s above):

• ## Project Overview → Business Context
• ## Functional Requirements → Core Capabilities, User Types, Integrations, Data Types, Architecture Pattern
• ## Non-Functional Requirements (NFRs) → Availability & Reliability, Performance, Scalability
• ## Compliance & Security Requirements → Regulatory Frameworks, Data Residency, Auth & Authorization, Network Security, Recommended Security Controls
• ## Budget → Cost Optimization Priorities (optional)
• ## Operational Requirements → Monitoring & Alerting, Support & Maintenance, Backup & Disaster Recovery

02-architecture-assessment.md

## Requirements Validation ✅
## Executive Summary
## WAF Pillar Assessment
## Resource SKU Recommendations
## Architecture Decision Summary
## Implementation Handoff
## Approval Gate
## References  <!-- Optional, add at end -->

03-des-cost-estimate.md

## 💰 Cost At-a-Glance
## ✅ Decision Summary
## 🔁 Requirements → Cost Mapping
## 📊 Top 5 Cost Drivers
## Architecture Overview
## 🧾 What We Are Not Paying For (Yet)
## ⚠️ Cost Risk Indicators
## 🎯 Quick Decision Matrix
## 💰 Savings Opportunities
## Detailed Cost Breakdown
## References  <!-- Required -->

NOTE: Cost estimate files use emoji-prefixed headings and are validated by the unified validate-artifact-templates.mjs validator. The legacy validate-cost-estimate-templates.mjs remains as an optional helper.

04-implementation-plan.md

## Overview
## Resource Inventory
## Module Structure
## Implementation Tasks
## Deployment Phases
## Dependency Graph
## Naming Conventions
## Security Configuration
## Estimated Implementation Time
## Approval Gate
## References  <!-- Optional, add at end -->

04-governance-constraints.md

## Discovery Source
## Azure Policy Compliance
## Plan Adaptations Based on Policies
## Deployment Blockers
## Required Tags
## Security Policies
## Cost Policies
## Network Policies
## References  <!-- Optional, add at end -->

04-preflight-check.md

## Purpose
## AVM Schema Validation Results
## Parameter Type Analysis
## Region Limitations Identified
## Pitfalls Checklist
## Ready for Implementation
## References  <!-- Optional, add at end -->

05-implementation-reference.md

## Bicep Templates Location
## File Structure
## Validation Status
## Resources Created
## Deployment Instructions
## Key Implementation Notes
## References  <!-- Optional, add at end -->

06-deployment-summary.md

## Preflight Validation
## Deployment Details
## Deployed Resources
## Outputs (Expected)
## To Actually Deploy
## Post-Deployment Tasks
## References  <!-- Optional, add at end -->

07-documentation-index.md

## 1. Document Package Contents
## 2. Source Artifacts
## 3. Project Summary
## 4. Related Resources
## 5. Quick Links
## References  <!-- Optional, add at end -->

07-design-document.md

## 1. Introduction
## 2. Azure Architecture Overview
## 3. Networking
## 4. Storage
## 5. Compute
## 6. Identity & Access
## 7. Security & Compliance
## 8. Backup & Disaster Recovery
## 9. Management & Monitoring
## 10. Appendix
## References  <!-- Optional, add at end -->

07-operations-runbook.md

## Quick Reference
## 1. Daily Operations
## 2. Incident Response
## 3. Common Procedures
## 4. Maintenance Windows
## 5. Contacts & Escalation
## 6. Change Log
## References  <!-- Optional, add at end -->

07-resource-inventory.md

## Summary
## Resource Listing
## References  <!-- Optional, add at end -->

07-backup-dr-plan.md

## Executive Summary
## 1. Recovery Objectives
## 2. Backup Strategy
## 3. Disaster Recovery Procedures
## 4. Testing Schedule
## 5. Communication Plan
## 6. Roles and Responsibilities
## 7. Dependencies
## 8. Recovery Runbooks
## 9. Appendix
## References  <!-- Optional, add at end -->

07-compliance-matrix.md

## Executive Summary
## 1. Control Mapping
## 2. Gap Analysis
## 3. Evidence Collection
## 4. Audit Trail
## 5. Remediation Tracker
## 6. Appendix
## References  <!-- Optional, add at end -->

07-ab-cost-estimate.md

## 💰 Cost At-a-Glance
## ✅ Decision Summary
## 🔁 Requirements → Cost Mapping
## 📊 Top 5 Cost Drivers
## Architecture Overview
## 🧾 What We Are Not Paying For (Yet)
## ⚠️ Cost Risk Indicators
## 🎯 Quick Decision Matrix
## 💰 Savings Opportunities
## Detailed Cost Breakdown
## References  <!-- Required -->

Enforcement Layers

Quick Fix Command

# Analyze what's wrong
npm run fix:artifact-h2 agent-output/{project}/{file}.md

# Auto-fix where possible
npm run fix:artifact-h2 agent-output/{project}/{file}.md --apply

Common Errors and Fixes

If you see:

missing required H2 headings: ## Outputs (Expected)

Fix: You used ## Outputs instead of ## Outputs (Expected). Use the EXACT text.

If you see:

contains extra H2 headings: ## Cost Summary

Fix: ## Cost Summary is not in the template. Either:

1. Remove it
2. Change to H3: ### Cost Summary (under a valid H2)
3. Move after ## References as optional section

Generation Workflow

1. Identify artifact type (e.g., 06-deployment-summary.md)
2. Find matching section in THIS FILE (above)
3. Use EXACT H2 headings in EXACT order
4. Fill content under each H2
5. Add ## References at end (always allowed)
6. Add custom H3 subsections under H2s as needed

Why This Matters

• Validation runs on every commit
• Non-compliant artifacts block commits
• CI fails if artifacts don't match
• Consistent structure enables automation

Quick Reference Card