feat(agents): Proposal — Azure Architecture + Cost Estimation Agent

### Custom Agent Name

/azure-architecture-cost-researcher

### Type

Custom Agent

### Purpose

## Summary

I'd like to contribute an agent that transforms high-level business scenarios into Azure architecture proposals with itemized cost estimates and ADRs. Before submitting a PR, I want to discuss with maintainers whether this should be:

1. **A new agent** (`architecture-cost-researcher`) in `project-planning/`
2. **An enhancement** to existing `adr-creation` and/or `system-architecture-reviewer` agents

## Problem Being Solved

Teams frequently need to answer **"Can we do this on Azure? How much will it cost?"** before making architecture decisions. Today in hve-core:

- `adr-creation` coaches users through ADR writing (Socratic method) but has no cost analysis or Azure service research capabilities
- `system-architecture-reviewer` reviews existing designs against the Well-Architected Framework but does not generate new architectures or estimate costs
- Neither agent researches Azure service pricing or produces itemized cost breakdowns

## What the Proposed Agent Does

A 6-step workflow:

1. **Context gathering** — problem statement, current state, ideal state, gap analysis (with example answers to guide users)
2. **Requirements validation** — proactively suggests additional requirements, mandatory consolidation checkpoint
3. **Azure service research** — uses `microsoft-docs/*` to find relevant services, WAF recommendations, and pricing
4. **Cost estimation** — itemized monthly cost breakdown per Azure service with pricing sources
5. **Architecture synthesis** — generates 2-4 options (recommended, cost-optimized, enterprise, alternative)
6. **Cost-inclusive ADR generation** — creates numbered folder in `docs/adr/` with per-option ADR files and a `decision.md`

### Key Differentiators from Existing Agents

| Capability | `adr-creation` | `system-architecture-reviewer` | Proposed agent |
|-----------|----------------|-------------------------------|----------------|
| Generates new architecture options | No | No | Yes (2-4 options) |
| Azure service pricing research | No | No | Yes (via `microsoft-docs/*`) |
| Itemized cost breakdown table | No | No | Yes (per-service, with pricing links) |
| Cost optimization recommendations | No | Mentioned as WAF pillar | Yes (reserved instances, autoscaling, tiers) |
| Security info gathering | No | Delegates to `security-plan-creator` | Built-in questionnaire (data classification, auth, network, compliance) |
| Multiple ADR options per decision | No (single ADR) | No (single ADR) | Yes (option-001, option-002, etc. + decision.md) |
| Mermaid architecture diagrams | No | No | Yes (with validation) |

## Discussion Questions for Maintainers

1. **New agent vs. enhancement?** Given the distinct focus (Azure-specific cost research + multi-option generation), does this warrant a separate agent — or should these capabilities be added to `adr-creation` or `system-architecture-reviewer`?

2. **Overlap concerns?** The agent has some overlap in ADR generation. Would a handoff pattern (similar to how `system-architecture-reviewer` hands off to `adr-creation`) be preferred instead?

3. **Security section** — the agent includes a built-in security questionnaire. Should this instead delegate to `security-plan-creator` like `system-architecture-reviewer` does?

4. **Collection placement** — I'd expect `project-planning` + `hve-core-all`. Any other collections?

## Current State

I have a working agent file tested locally. I'm happy to adapt it to hve-core standards (frontmatter format, tool naming, attribution footer, collection manifests, etc.) once the approach is confirmed.

## References

- Existing `adr-creation` agent: `.github/agents/project-planning/adr-creation.agent.md`
- Existing `system-architecture-reviewer` agent: `.github/agents/project-planning/system-architecture-reviewer.agent.md`

### Requirements

1. **Azure service research with documentation backing** — The agent uses `microsoft-docs/*` to look up relevant Azure services, pricing pages, service limits, and Well-Architected Framework recommendations — grounding recommendations in official documentation rather than training data alone.

2. **Itemized cost estimation** — Each architecture option includes a per-service cost breakdown table with tier/SKU, usage assumptions, unit pricing, estimated monthly cost, and clickable links to Azure pricing pages. Cost ranges (low/typical/high) and optimization opportunities (reserved instances, autoscaling, tier selection) are included.

3. **Multi-option architecture generation** — The agent produces 2-4 architecture options per scenario (recommended, cost-optimized, enterprise/HA, and optionally an alternative approach), each with Mermaid diagrams, service rationale, and trade-off analysis.

4. **Cost-inclusive ADR output** — Each option is written as a standalone ADR file (`option-001-*.md`, `option-002-*.md`) in a numbered folder under `docs/adr/`, with a `decision.md` summarizing the recommendation. ADRs include full context (problem statement, current state, desired outcome, constraints, requirements), maintainability assessment, cost analysis, and security information.

Start by reading .github/agents/project-planning/adr-creation.agent.md and .github/agents/project-planning/system-architecture-reviewer.agent.md, then compare the proposed workflow with their responsibilities and handoff patterns. Confirm with maintainers whether this belongs as a new project-planning agent or an enhancement, and treat the work as done only when the placement, scope, security delegation, and collection manifests are agreed.

Written by the indexing model from the issue text.