azure-artifacts

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

For revisions (challenger findings, user-decision Apply/Skip/Defer, approval-gate fixes), see [`references/revision-workflow.md`](./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`](../../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):

-