Apex Azure Artifacts

---
name: apex-azure-artifacts
user-invocable: false
disable-model-invocation: false
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 apex-azure-defaults), Bicep/Terraform patterns (use apex-azure-bicep-patterns or apex-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

Owns artifact structures and styling, not workflow decisions. Required H2s
come from the heading registry; full templates live in `templates/` and
`references/` provide navigation summaries. Read the full template for current writes.
The workflow graph, role contract, current reviews and human approval own routing
and completion; templates never advance a step or authorize an operation.

## Rules

### Mandatory Compliance

| Rule                  | Requirement                                         |
| --------------------- | --------------------------------------------------- |
| **Template skeleton** | Read the full step template from `templates/`; summaries are navigation |
| **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. Reflect verified graph/session status in `## ✅ Workflow Progress`; a write alone is not completion
2. Add artifact files to `## 📄 Generated Artifacts`
3. Update `Last Updated` and derive progress from current required/optional graph nodes,
   including Governance. Partial output, pending reviews and approval remain incomplete.

## Steps

Artifact generation flow (per Step N):

1. **Read template** — use the matching reference to locate the full `templates/*.template.md`
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** — list validated artifacts and actual status; never mark complete
  before required checks, reviews and approval
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`](../../instructions/agent-authoring.instructions.md#no-direct-markdownlint-on-agent-output-rule).

For revisions (challenger findings, user decisions, approval-gate fixes), follow
[`references/revision-workflow.md`](./references/revision-workflow.md).
Use available targeted editing tools, preserve user work, and validate before dependent follow-up edits.

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

For incremental IaC, apply the readiness-aware build checkpoints in
[`codegen-shared-workflow.md`](../apex-iac-common/references/codegen-shared-workflow.md).
An incomplete scaffold has deferred checks, not successful validation;
all deferred checks must pass before completion or handoff. Use bounded validated batches
under the shared workflow; no routine per-file approval is required.

## 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`](../../instructions/agent-authoring.instructions.md#no-direct-markdownlint-on-agent-output-rule)).

```bash
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):

```bash
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`](../../../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`](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+)  |
| `references/sku-manifest-details.md`     | SKU manifest coverage, projection, TTL and sync tooling |