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.

04-implementation-plan.md

## 📋 Overview

## 📦 Resource Inventory

## 🗂️ Module Structure

## 🔨 Implementation Tasks

## 🚀 Deployment Phases

## 🔗 Dependency Graph

## 🔄 Runtime Flow Diagram

## 🏷️ 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