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

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.

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
## Runtime Flow Diagram
## 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

Output Files (Step 7)

Source Artifacts for Step 7

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

Category Icons

WAF Pillar Icons

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

Automated Validation

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

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