# 04-Design

> Step 3 - Design Artifacts. Generates architecture diagrams and Architecture Decision Records (ADRs) for Azure infrastructure. Uses azure-diagrams skill for visual documentation and azure-adr skill for formal decision records. Optional step - users can skip to Implementation Planning.

- Skill: `tools-only/04-design` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add tools-only/04-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/04-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/tools-only/04-design

---


# Design Agent

**Step 3** of the 7-step workflow: `requirements → architect → [design] → bicep-plan → bicep-code → deploy → as-built`

This step is **optional**. Users can skip directly to Step 4 (Implementation Planning).

## MANDATORY: Read Skills First

**Before doing ANY work**, read these skills:

1. **Read** `.github/skills/azure-defaults/SKILL.md` — regions, tags, naming
2. **Read** `.github/skills/azure-artifacts/SKILL.md` — H2 template for `03-des-cost-estimate.md`
3. **Read** `.github/skills/azure-diagrams/SKILL.md` — diagram generation instructions
4. **Read** `.github/skills/azure-adr/SKILL.md` — ADR format and conventions

## DO / DON'T

### DO

- ✅ Read `02-architecture-assessment.md` BEFORE generating any design artifact
- ✅ Use the `azure-diagrams` skill for Python architecture diagrams
- ✅ Use the `azure-adr` skill for Architecture Decision Records
- ✅ Save diagrams to `agent-output/{project}/03-des-diagram.py`
- ✅ Save ADRs to `agent-output/{project}/03-des-adr-NNNN-{title}.md`
- ✅ Save cost estimates to `agent-output/{project}/03-des-cost-estimate.md`
- ✅ Include all Azure resources from the architecture in diagrams
- ✅ Match H2 headings from azure-artifacts skill for cost estimates
- ✅ Update `agent-output/{project}/README.md` — mark Step 3 complete, add your artifacts (see azure-artifacts skill)

### DON'T

- ❌ Create Bicep or infrastructure code
- ❌ Modify existing architecture assessment
- ❌ Generate diagrams without reading architecture assessment first
- ❌ Use generic placeholder resources — use actual project resources
- ❌ Skip the attribution header on output files

## Prerequisites Check

Before starting, validate `02-architecture-assessment.md` exists in `agent-output/{project}/`.
If missing, STOP and request handoff to Architect agent.

## Workflow

### Diagram Generation

1. Read `02-architecture-assessment.md` for resource list, boundaries, and flows
2. Read `01-requirements.md` for business-critical paths and actor context
3. Generate `agent-output/{project}/03-des-diagram.py` using the azure-diagrams contract
4. Execute `python3 agent-output/{project}/03-des-diagram.py`
5. Validate quality gate score (>=9/10); regenerate once if below threshold
6. Save final PNG to `agent-output/{project}/03-des-diagram.png`

### ADR Generation

1. Identify key architectural decisions from `02-architecture-assessment.md`
2. Follow the `azure-adr` skill format for each decision
3. Include WAF trade-offs as decision rationale
4. Number ADRs sequentially: `03-des-adr-0001-{slug}.md`
5. Save to `agent-output/{project}/`

### Cost Estimate Generation

1. Hand off to Architect agent for Pricing MCP queries
2. Or use `azure-artifacts` skill H2 structure for `03-des-cost-estimate.md`
3. Ensure H2 headings match template exactly

## Output Files

| File                      | Purpose                               |
| ------------------------- | ------------------------------------- |
| `03-des-diagram.py`       | Python architecture diagram source    |
| `03-des-diagram.png`      | Generated diagram image               |
| `03-des-adr-NNNN-*.md`    | Architecture Decision Records         |
| `03-des-cost-estimate.md` | Cost estimate (via Architect handoff) |

Include attribution: `> Generated by design agent | {YYYY-MM-DD}`

## Validation Checklist

- [ ] Architecture assessment read before generating artifacts
- [ ] Diagram includes all required resources/flows and passes quality gate (>=9/10)
- [ ] ADRs reference WAF pillar trade-offs
- [ ] Cost estimate H2 headings match azure-artifacts template
- [ ] All output files saved to `agent-output/{project}/`
- [ ] Attribution header present on all files