azure-artifacts

name	azure-artifacts
description	**UTILITY SKILL** — Artifact template structures, H2 compliance rules, and documentation styling for agent outputs (Steps 1-7). WHEN: "generate artifact", "check H2 structure", "artifact template", "step 7 as-built". USE FOR: generating any agent artifact, checking H2 structure compliance. DO NOT USE FOR: Azure resource configuration (use azure-defaults), Bicep/Terraform patterns (use azure-bicep-patterns or terraform-patterns).
compatibility	Works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool.
license	MIT
metadata	{"author":"jonathan-vella","version":"2.0","category":"workflow-automation"}

Azure Artifacts Skill

Single source of truth for artifact template structures and styling. Per-step H2 definitions live in references/ — load only the step you are generating.

Rules

Mandatory Compliance

Rule	Requirement
Template skeleton	Read step template from references/ and replicate
Exact text	Use H2 text from templates verbatim
Exact order	Required H2s appear in the order listed
Anchor rule	Extra sections allowed ONLY after last required H2
No omissions	Every H2 listed must appear in output
Attribution	> Generated by {agent} agent | {YYYY-MM-DD}

DO / DON'T

• DO: Read the step-specific template before generating
• DO: Copy H2 text character-for-character (including emoji)
• DO: Save all output to agent-output/{project}/
• DON'T: Reorder H2 headings from the listed sequence
• DON'T: Use placeholder text like "TBD" or "Insert here"
• 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.

After saving step artifact(s), update the README:

1. Mark your step as complete in ## ✅ Workflow Progress
2. Add artifact files to ## 📄 Generated Artifacts
3. Update Last Updated date and progress bar percentage

Steps

Artifact generation flow (per Step N):

1. Read template — load the matching references/0N-*-template.md for the step you are generating
2. Copy H2 skeleton — replicate every required H2 in the listed order, character-for-character
3. Fill content — replace {placeholder} tokens; never use "TBD" or "Insert here"
4. Add attribution — > Generated by {agent} agent | {YYYY-MM-DD}
5. Save to agent-output/{project}/ with the prescribed filename
6. Update README — mark step complete, list artifacts, refresh Last Updated date
7. Delegate validation — do not invoke npm run lint:artifact-templates, npm run lint:h2-sync, or markdownlint-cli2 directly against agent-output/**. The lefthook artifact-validation pre-commit hook (which wraps these scripts) and the 10-Challenger review own the artifact contract. See agent-authoring.instructions.md.

For revisions (challenger findings, user-decision Apply/Skip/Defer, approval-gate fixes), see references/revision-workflow.md — bundle all fixes into a single multi_replace_string_in_file call.

Post-write validation

Run a one-line shape check immediately after writing any non-markdown artifact, before moving to the next step. Catches malformed output at source instead of at deploy time. Markdown artifacts are owned by the lefthook artifact-validation hook — do not duplicate that check here.

Artifact type	Validation command (run after write)
*.json	python -m json.tool <file> >/dev/null
*.bicep	bicep build --stdout <file> >/dev/null
*.tf	terraform fmt -check <file> + terraform validate (in module dir)
challenge-findings-*.json (sidecar JSON)	node tools/scripts/validate-challenger-findings.mjs <file>
challenge-findings-*-decisions.json (per-finding sidecar)	node tools/scripts/validate-challenge-findings-decisions.mjs <file>
*.md	delegated to lefthook artifact-validation — do not run inline

Fail closed: if the validator exits non-zero, fix the artifact and re-validate before continuing. Do not record the artifact in the project README or hand off to the next step until it passes.

Placeholder Syntax

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

• Lowercase, hyphen-separated: {project-name}, {monthly-cost}
• No Mustache/Handlebars {{double-braces}}

Automated Validation

These npm scripts are invoked by the lefthook artifact-validation pre-commit hook and by CI — not by agents directly (see agent-authoring.instructions.md).

npm run lint:artifact-templates   # H2 order and required headings (pre-commit + CI only)
npm run lint:h2-sync              # Template ↔ artifact sync (pre-commit + CI only)
npm run validate:all              # All validators together (humans / CI only)

Fast H2-order sanity check (agent-safe)

When an agent needs a quick "did I get the H2 structure right?" check before invoking the challenger, use the dedicated helper instead of improvising node -e '…' one-liners (which trip shell quoting and waste context on retries):

npm run check:h2-order -- <project>                       # defaults to 01-requirements.md
npm run check:h2-order -- <project> 04-implementation-plan.md
node tools/scripts/check-h2-order.mjs agent-output/<project>/02-architecture-assessment.md

Exit 0 = match (prints OK: …). Exit 1 = mismatch (prints structured JSON with expected/got/missingAt). Exit 2 = bad arguments or unknown artifact filename. The helper reads the canonical heading registry from tools/scripts/_lib/artifact-headings.mjs so it never drifts from the template source of truth.

Quality Checklist

Critical (always check):

• H2 headings match template exactly (text + order)
• Attribution header present with agent name and date
• No placeholder text (e.g. "TBD", "Insert here", task markers)
• File saved to agent-output/{project}/ with correct name

For the full structural / styling checklist (TOC, cross-nav table, traffic lights, Mermaid, collapsible blocks) read references/styling-standards.md.

Reference Index

When generating a Step N artifact, read the corresponding template:

Reference	When to Load
references/01-requirements-template.md	Generating Step 1 requirements
references/02-architecture-template.md	Generating Step 2 assessment or Step 3 cost estimate
references/04-plan-template.md	Generating Step 4 plan, governance, or preflight
references/05-code-template.md	Generating Step 5 implementation reference
references/06-deploy-template.md	Generating Step 6 deployment summary
references/07-docs-template.md	Generating Step 7 workload documentation
references/styling-standards.md	Applying callouts, badges, emoji, navigation
references/cost-estimate-sections.md	Cost estimate H2 structure and formatting rules
references/revision-workflow.md	Detailed targeted-edit revision procedure (Step 7+)