--- 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 >/dev/null` | | `*.bicep` | `bicep build --stdout >/dev/null` | | `*.tf` | `terraform fmt -check ` + `terraform validate` (in module dir) | | `challenge-findings-*.json` (sidecar JSON) | `node tools/scripts/validate-challenger-findings.mjs ` | | `challenge-findings-*-decisions.json` (per-finding sidecar) | `node tools/scripts/validate-challenge-findings-decisions.mjs ` | | `*.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 -- # defaults to 01-requirements.md npm run check:h2-order -- 04-implementation-plan.md node tools/scripts/check-h2-order.mjs agent-output//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 |