azure-artifacts

name	azure-artifacts
description	Defines canonical artifact templates, H2 structures, and documentation styling rules for agent outputs (Steps 1-7); use for artifact generation, formatting, and template compliance.
compatibility	Works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool.
license	MIT
metadata	{"author":"jonathan-vella","version":"1.0","category":"workflow-automation"}

Azure Artifacts Skill

Single source of truth for all artifact template structures and documentation styling. Replaces individual template file lookups with embedded H2 definitions.

---

Artifact Generation Rules

Mandatory Compliance

Rule	Requirement
Template skeleton	Read .template.md file and replicate its structure
Exact text	Use H2 text from this skill verbatim
Exact order	Required H2s appear in the order listed below
Anchor rule	Extra sections allowed ONLY after last required H2
No omissions	Every H2 listed must appear in output
Attribution	Include header: > Generated by {agent} agent | {YYYY-MM-DD}

DO / DON'T

• DO: Read this skill BEFORE generating any artifact
• DO: Copy H2 text character-for-character (including emoji prefixes)
• DO: Include ## References section at bottom when listed
• DO: Use callout styles from the Styling section below
• DO: Save all output to agent-output/{project}/
• DON'T: Generate artifacts without checking H2 structure first
• DON'T: Reorder H2 headings from the listed sequence
• DON'T: Use placeholder text like "TBD" or "Insert here"
• DON'T: Skip sections — empty sections are better than missing ones
• DON'T: Add custom H2 sections BEFORE the last required H2

---

Mandatory: Project README

Every project in agent-output/{project}/ MUST have a README.md. This is a cross-agent requirement — not owned by a single step.

Responsibility	Agent
Create initial README from PROJECT-README.template.md	Requirements (Step 1)
Update workflow progress after saving step artifacts	Every step agent (Steps 2-7)

README Update Rules (All Agents)

After saving your step artifact(s), update agent-output/{project}/README.md:

1. Mark your step as complete in the ## ✅ Workflow Progress table
2. Add your artifact files to the ## 📄 Generated Artifacts section
3. Update the Last Updated date in ## 📋 Project Summary
4. Update the progress bar percentage (each of the 7 steps = ~14%)
5. If README doesn't exist (e.g., resuming a mid-workflow project), create it from PROJECT-README.template.md and backfill completed steps

Template: .github/skills/azure-artifacts/templates/PROJECT-README.template.md

---

Standard Components

Reusable building blocks that templates embed. Agents copy these patterns verbatim, replacing only {placeholder} values.

Badge Row

Every artifact opens with a badge row immediately after the title. Use Shields.io static badges for visual scanning:

![Step](https://img.shields.io/badge/Step-{n}-blue)
![Status](https://img.shields.io/badge/Status-{Draft|Complete}-{orange|brightgreen})
![Agent](https://img.shields.io/badge/Agent-{agent--name}-purple)

Badge values use -- for hyphens (Shields.io escaping). The Status badge is Draft|orange on first generation and Complete|brightgreen after review. Agents may optionally add a fourth Date badge (![Date](https://img.shields.io/badge/Generated-{YYYY--MM--DD}-grey)) when generating final artifacts.

Collapsible Table of Contents

Include in every artifact after the badge row:

<details>
<summary><strong>📑 Table of Contents</strong></summary>

- Section Name (#section-name)
- Section Name (#section-name)
<!-- auto-generate from H2 headings -->

</details>

Attribution Header

Appears immediately after the TOC:

> Generated by {agent} agent | {YYYY-MM-DD}

Cross-Navigation

Every artifact includes header and footer navigation links to adjacent workflow steps:

Header (after attribution):

| ⬅️ Previous     | 📑 Index  | Next ➡️         |
| --------------- | --------- | --------------- |
| {prev-filename} | README.md | {next-filename} |

Footer (before References or at document end):

---

| ⬅️ {prev-step-name} ({prev-filename}) | 🏠 Project Index (README.md) | ➡️ {next-step-name} ({next-filename}) |
| ------------------------------------- | ---------------------------- | ------------------------------------- |

For the first artifact (01), omit the Previous link. For the last artifact (07), omit the Next link.

Placeholder Syntax

All templates use single-brace {placeholder-name} syntax:

• Lowercase, hyphen-separated: {project-name}, {monthly-cost}
• No Mustache/Handlebars {{double-braces}}
• No conditional blocks — use HTML comments for optional sections: <!-- If {condition} -->...<!-- End {condition} -->

Collapsible Detail Blocks

Use for content exceeding 10 table rows, lengthy code, or reference material:

<details>
<summary>📋 {Section Title}</summary>

| Column | Column |
| ------ | ------ |
| ...    | ...    |

</details>

Always include a blank line after <summary> and before </details>.

---

Template H2 Structures

01-requirements.md (Requirements Agent)

## Project Overview
## Functional Requirements
## Non-Functional Requirements (NFRs)
## Compliance & Security Requirements
## Budget
## Operational Requirements
## Regional Preferences
## Summary for Architecture Assessment
## References

02-architecture-assessment.md (Architect Agent)

## Requirements Validation ✅
## Executive Summary
## WAF Pillar Assessment
## Resource SKU Recommendations
## Architecture Decision Summary
## Implementation Handoff
## Approval Gate
## References

03-des-cost-estimate.md (Architect Agent)

## 💰 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

04-governance-constraints.md (Bicep Plan Agent)

## Discovery Source
## Azure Policy Compliance
## Plan Adaptations Based on Policies
## Deployment Blockers
## Required Tags
## Security Policies
## Cost Policies
## Network Policies
## References

04-implementation-plan.md (Bicep Plan Agent)

## Overview
## Resource Inventory
## Module Structure
## Implementation Tasks
## Deployment Phases
## Dependency Graph
## Naming Conventions
## Security Configuration
## Estimated Implementation Time
## Approval Gate
## References

04-preflight-check.md (Bicep Code Agent)

## Purpose
## AVM Schema Validation Results
## Parameter Type Analysis
## Region Limitations Identified
## Pitfalls Checklist
## Ready for Implementation

05-implementation-reference.md (Bicep Code Agent)

## Bicep Templates Location
## File Structure
## Validation Status
## Resources Created
## Deployment Instructions
## Key Implementation Notes

06-deployment-summary.md (Deploy Agent)

## Preflight Validation
## Deployment Details
## Deployed Resources
## Outputs (Expected)
## To Actually Deploy
## Post-Deployment Tasks
## References

07-documentation-index.md

## 1. Document Package Contents
## 2. Source Artifacts
## 3. Project Summary
## 4. Related Resources
## 5. Quick Links

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

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

07-resource-inventory.md

## Summary
## Resource Listing
## References

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

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

07-compliance-matrix.md

## Executive Summary
## 1. Control Mapping
## 2. Gap Analysis
## 3. Evidence Collection
## 4. Audit Trail
## 5. Remediation Tracker
## 6. Appendix
## References

PROJECT-README.md

## Template Instructions
## Required Structure
## 📋 Project Summary
## ✅ Workflow Progress
## 🏛️ Architecture
## 📄 Generated Artifacts
## 🔗 Related Resources

---

Step 7: Workload Documentation Generation

When to Generate

Trigger	Action
After Step 6 (Deploy)	Generate full documentation package
"Generate workload documentation"	Create all 7 document types
"Document the deployment"	Synthesize from deployment artifacts
"Create operations runbook"	Generate specific document
Conductor handoff	Auto-generate post-deployment docs

Output Files (Step 7)

File	Purpose	Required
07-documentation-index.md	Master index linking all docs	Yes
07-design-document.md	10-section technical design	Yes
07-operations-runbook.md	Day-2 operational procedures	Yes
07-resource-inventory.md	Complete resource listing	Yes
07-ab-cost-estimate.md	As-built cost analysis	Yes
07-compliance-matrix.md	Security control mapping	Optional
07-backup-dr-plan.md	Disaster recovery procedures	Optional

Source Artifacts for Step 7

Source	Information Extracted
01-requirements.md	Business context, NFRs, compliance
02-architecture-assessment.md	WAF scores, SKU recommendations
04-implementation-plan.md	Resource inventory, dependencies
06-deployment-summary.md	Deployed resources, outputs
infra/bicep/{project}/	Actual Bicep configuration values

Generation Workflow

1. Gather Context — Read project artifacts (01-06) and Bicep templates
2. Check H2 Structures — Reference the template sections above
3. Extract Resources — Parse deployed resources from 06-deployment-summary.md
4. Query Pricing — Use Azure Pricing MCP for cost estimates (if available)
5. Generate Documents — Create each document following H2 structure exactly
6. Cross-Reference — Ensure consistency across all documents
7. Create Index — Generate 07-documentation-index.md linking all documents

Step 7 DO / DON'T

• DO: Read ALL source artifacts before generating
• DO: Use actual SKU names and config from Bicep, not placeholders
• DO: Include specific Azure CLI/PowerShell commands in runbooks
• DO: Map compliance controls to actual resource configurations
• DO: Calculate costs from deployed SKUs, not estimates
• DON'T: Generate docs without reading source artifacts
• DON'T: Create generic runbooks without project-specific commands
• DON'T: Skip required documents (index, design, runbook, inventory, cost)
• DON'T: Generate cost estimates without checking actual SKUs

What This Skill Does NOT Do

• Generate Bicep or Terraform code (use bicep-code agent)
• Create architecture diagrams (use azure-diagrams skill)
• Deploy resources (use deploy agent)
• Create ADRs (use azure-adr skill)
• Perform WAF assessments (use architect agent)

---

Documentation Styling Standards

Callout Styles

> [!NOTE]
> Informational — background context, tips, FYI

> [!TIP]
> Best practice recommendation or optimization

> [!IMPORTANT]
> Critical configuration that must not be overlooked

> [!WARNING]
> Security concern, reliability risk, potential issue

> [!CAUTION]
> Data loss risk, breaking change, irreversible action

Status Emoji

Purpose	Emoji	Example
Success/Complete	✅	✅ Health check passed
Warning/Attention	⚠️	⚠️ Requires manual config
Error/Critical	❌	❌ Validation failed
Info/Tip	💡	💡 Consider Premium tier
Security	🔐	🔐 Requires Key Vault
Cost	💰	💰 Estimated: $50/month
Reference	📚	📚 See: Microsoft Learn
Time	⏰	⏰ Runs daily at 02:00 UTC
Pending	⏳	⏳ Awaiting approval

Category Icons

Category	Icon	Usage
Compute	💻	### 💻 Compute Resources
Data	💾	### 💾 Data Services
Networking	🌐	### 🌐 Networking Resources
Messaging	📨	### 📨 Messaging Resources
Security	🔐	### 🔐 Security Resources
Monitoring	📊	### 📊 Monitoring Resources
Identity	👤	### 👤 Identity & Access
Storage	📦	### 📦 Storage Resources

WAF Pillar Icons

Pillar	Icon
Security	🔒
Reliability	🔄
Performance	⚡
Cost	💰
Operations	🔧

Collapsible Sections

Use for lengthy content (>10 rows, reference material, code examples):

<details>
<summary>📋 Detailed Configuration</summary>

| Setting | Value |
| ------- | ----- |
| ...     | ...   |

</details>

References Section (Required on Most Artifacts)

---

## References

> [!NOTE]
> 📚 The following Microsoft Learn resources provide additional guidance.

| Topic      | Link                                            |
| ---------- | ----------------------------------------------- |
| Topic Name | [Display Text](https://learn.microsoft.com/...) |

Common Reference Links

Topic	URL
WAF Overview	https://learn.microsoft.com/azure/well-architected/
Security Checklist	https://learn.microsoft.com/azure/well-architected/security/checklist
Reliability Checklist	https://learn.microsoft.com/azure/well-architected/reliability/checklist
Cost Optimization	https://learn.microsoft.com/azure/well-architected/cost-optimization/checklist
Azure Backup	https://learn.microsoft.com/azure/backup/backup-best-practices
Azure Monitor	https://learn.microsoft.com/azure/azure-monitor/overview
Managed Identities	https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview
Key Vault Practices	https://learn.microsoft.com/azure/key-vault/general/best-practices
Azure Pricing Calculator	https://azure.microsoft.com/pricing/calculator/

---

Automated Validation

Templates and generated artifacts are validated by the unified validator in scripts/:

Script	Scope	npm Command
validate-artifact-templates.mjs	All 16 artifact types — H2 order, required headings, strictness, cost-specific Mermaid checks	npm run lint:artifact-templates

Run npm run validate:all to execute all validators together.

---

Quality Checklist

Before finalizing any artifact:

• H2 headings match this skill's template exactly (text + order)
• Attribution header present with agent name and date
• No placeholder text ("TBD", "Insert here", "TODO")
• Callout styles used for emphasis (not bold text alone)
• Status emoji consistent with the table above
• References section included (when template specifies it)
• Collapsible sections used for tables >10 rows
• File saved to agent-output/{project}/ with correct filename