---
applyTo: "**/agent-output/**/*.md"
description: "Template compliance rules for artifact generation"
---

# Artifact Generation Rules

Use exact H2 headings from the template files. Violations block commits and PRs.

The `azure-artifacts/SKILL.md` is authoritative — read it for templates, workflow, styling.

## Structural Elements (Beyond H2 Headings)

Templates define structural elements that agents reproduce.
Validated by `npm run lint:artifact-templates`.

| Element              | What to Copy from Template                               |
| -------------------- | -------------------------------------------------------- |
| Badge row            | `![Step]` / `![Status]` / `![Agent]` shields             |
| Collapsible TOC      | `<details open>` block with section links                |
| Attribution          | `> Generated by {agent} agent \| {date}`                 |
| Cross-navigation     | Header table with ⬅️ Previous / 📑 Index / Next ➡️       |
| Mermaid diagrams     | ` ```mermaid` blocks (keep or replace with real content) |
| Traffic-light status | Use ✅ / ⚠️ / ❌ in status columns (all three required)  |
| Collapsible sections | `<details>` blocks for expandable content                |

## Complete H2 Heading Reference

Copy-paste headings from the template files. Do not paraphrase.

Canonical H2 heading lists for all 15 artifact types live in the template files:

| Artifacts                            | Template Reference                       |
| ------------------------------------ | ---------------------------------------- |
| 01-requirements                      | `references/01-requirements-template.md` |
| 02-architecture, 03-cost-estimate    | `references/02-architecture-template.md` |
| 04-plan, 04-governance, 04-preflight | `references/04-plan-template.md`         |
| 05-implementation-reference          | `references/05-code-template.md`         |
| 06-deployment-summary                | `references/06-deploy-template.md`       |
| 07-\* (all Step 7 docs)              | `references/07-docs-template.md`         |

## Enforcement Layers

| Layer           | Mechanism                                      | When                 |
| --------------- | ---------------------------------------------- | -------------------- |
| 1. Instructions | This file auto-applies to all agent-output     | Generation time      |
| 2. Pre-commit   | `npm run lint:artifact-templates` via Lefthook | Before commit        |
| 3. CI/CD        | Same validation in GitHub Actions              | Before merge         |
| 4. Auto-fix     | `npm run fix:artifact-h2`                      | On-demand correction |

## Quick Fix Command

```bash
npm run fix:artifact-h2 agent-output/{project}/{file}.md          # analyze
npm run fix:artifact-h2 agent-output/{project}/{file}.md --apply  # auto-fix
```

## Common Errors and Fixes

- `missing required H2 headings: ## Outputs (Expected)`
  **Fix**: Use EXACT heading text. `## Outputs` ≠ `## Outputs (Expected)`.
- `contains extra H2 headings: ## Cost Summary`
  **Fix**: Remove, change to H3, or move after `## References`.

## Quick Reference Card

| Artifact               | First H2                             | Last Required H2                            |
| ---------------------- | ------------------------------------ | ------------------------------------------- |
| 01-requirements        | `## 🎯 Project Overview`             | `## 📋 Summary for Architecture Assessment` |
| 02-architecture        | `## ✅ Requirements Validation`      | `## 🔒 Approval Gate`                       |
| 04-implementation-plan | `## 📋 Overview`                     | `## 🔒 Approval Gate`                       |
| 04-governance          | `## 🔍 Discovery Source`             | `## 🌐 Network Policies`                    |
| 04-preflight           | `## 🎯 Purpose`                      | `## 🚀 Ready for Implementation`            |
| 05-implementation-ref  | `## 📁 IaC Templates Location`       | `## 📝 Key Implementation Notes`            |
| 06-deployment          | `## ✅ Preflight Validation`         | `## 📝 Post-Deployment Tasks`               |
| 07-doc-index           | `## 📦 1. Document Package Contents` | `## ⚡ 5. Quick Links`                      |
| 07-design              | `## 📝 1. Introduction`              | `## 📎 10. Appendix`                        |
| 07-runbook             | `## ⚡ Quick Reference`              | `## 📝 6. Change Log`                       |
| 07-inventory           | `## 📊 Summary`                      | `## 📦 Resource Listing`                    |
| 07-backup-dr           | `## 📋 Executive Summary`            | `## 📎 9. Appendix`                         |
| 07-compliance          | `## 📋 Executive Summary`            | `## 📎 6. Appendix`                         |
| 07-cost                | `## 💵 Cost At-a-Glance`             | `## 🧾 Detailed Cost Breakdown`             |
| 09-lessons-learned     | `## 📋 Summary`                      | `## 📎 Appendix: Full Lesson Details`       |
