Prepare — Architecture Planning & Cost Estimation

Quick Reference

Property	Value
Best for	Mapping app components to Azure services with cost estimation and quota validation
Inputs	`prereq-output.json` + `context.json` from `.copilot-azure/sessions/{id}/`
Outputs	`prepare-plan.json` written to session directory
Parent	azure-app-onboard

When to Use This Skill

Invoked by the azure-app-onboard orchestrator at Phase 2 when prereq-output.json exists. Not directly user-routable.

Return to orchestrator: When complete, return control to azure-app-onboard. Do NOT directly invoke scaffold or deploy.

When NOT to Use

Scenario	Use Instead
Code readiness or prereq scanning	`azure-app-onboard` Step 3 (prereq)
IaC generation from a completed plan	`azure-app-onboard` Step 7 (scaffold)
Deploying resources to Azure	`azure-app-onboard` Step 9 (deploy)
Optimizing existing Azure spend	`cost-optimization` from the optional `azure-cost` plugin
Estimating VM-specific costs	`azure-compute`
Enterprise landing zone architecture	`azure-enterprise-infra-planner`

If cost-optimization is unavailable, explain that it is provided by the optional azure-cost plugin and direct the user to their client's supported plugin installation flow; do not imply the handoff completed.

MCP Tools

Tool	Purpose
`mcp_azure_mcp_pricing` / `azure-pricing` (router → `command: pricing_get`)	Cost estimation (inline — see Step 6). Fallback: dispatch `subagent-pricing.md`
`mcp_azure_mcp_policy`	Subscription policy constraints
`az rest`	Quota validation (via sub-agent — see Step 5)
`mcp_azure_mcp_cloudarchitect` → `cloudarchitect_design`	WAF-aligned architecture design
`mcp_azure_mcp_wellarchitectedframework`	Per-service WAF guidance
`mcp_azure_mcp_advisor` → `advisor_recommendation_list`	Optimization recommendations

Workflow

#	Step	Action	Reference
1	Read session state	Load `prereq-output.json` + `context.json`. Resolve subscription	Cross-ref subscription-resolution.md if needed
2	Query policy constraints	Inline MCP: fetch policy + advisor recommendations	`mcp_azure_mcp_policy` + `mcp_azure_mcp_advisor`
3	Map components to services	Per-component Azure service selection, Dockerfile routing, deploy-as-is	⛔ You MUST read service-mapping.md and deploy-strategy.md
4	Select SKUs + WAF analysis	Budget-aware SKU selection, inline WAF service guidance	⛔ You MUST read sku-matrix.md
5	Validate quotas + region capacity	⛔ Read `subagent-quota.md` → dispatch as `task` (NEXT action MUST be `task`, ⛔ agent_type: `"task"` — NEVER `"general-purpose"`). Copy the COMPLETE and UNMODIFIED template text into the task prompt between `<<<TEMPLATE_START>>>` / `<<<TEMPLATE_END>>>` delimiters — do NOT summarize. Append the caller-provided inputs listed in `subagent-quota.md`'s Input table AFTER the template block. ⛔ After dispatching, proceed to Step 6 (cost estimation) while the subagent runs. Do NOT run quota checks yourself — the subagent handles it. Collect subagent results before Step 9 (write plan).	⛔ You MUST read `subagent-quota.md`
6	Estimate costs	⛔ You MUST read pricing-guide.md for methodology, then pricing-guide-services.md for per-service filters. Call the pricing router (`mcp_azure_mcp_pricing`/`azure-pricing`) with `command: "pricing_get"` + a `parameters{}` object inline per paid service. If MCP unavailable or fails → ⛔ Read `subagent-pricing.md` → dispatch as `task` (NEXT action MUST be `task`, ⛔ agent_type: `"task"` — NEVER `"general-purpose"`). Copy the COMPLETE and UNMODIFIED template text into the task prompt between `<<<TEMPLATE_START>>>` / `<<<TEMPLATE_END>>>` delimiters — do NOT summarize. Append data (services[], region, budget tier) AFTER the template block. Write results to `prepare-plan.json.costEstimate`.	pricing-guide.md
7	Generate naming	Centralized naming: suffix, prefix, all resource names	⛔ You MUST read naming-patterns.md
8	Determine IaC format	Existing non-Azure `.tf` → `ask_user` Bicep vs TF, write to `overrides[].iacFormat`. No `.tf` → default Bicep.	(inline)
9	Write prepare-plan.json	Per `PreparePlan` schema. Include postDeployRecommendations, deploymentVariables	⛔ You MUST read prepare-schemas.ts for `PreparePlan` schema
10	Return summary	Structured summary for orchestrator approval gate	(inline — 1 line)
11	Validate plan	4-dimension check: Goal Alignment, WAF Alignment, Dependency Completeness, Deployment Viability. Fix inline on failure, document tradeoffs in `assumptions[]`.	All must pass before writing

Step 5 — Post-Quota Validation

⛔ NEVER present a region without checking quota first. Skipping quota validation causes cascading deploy failures and extended healing loops. ⛔ If plan includes PostgreSQL/MySQL, verify offerRestrictionsVerified: true — if false/missing, region is blocked. Do NOT proceed to scaffold with unchecked DB services. ⛔ Free ≠ unlimited. Every compute SKU — including F1, Consumption, and Serverless tiers — has a per-subscription, per-region quota. Do NOT skip quota checks because a SKU is free. ⛔ After region fallback, update ALL services[].region in prepare-plan.json. Do not leave stale values.

Error Handling

Error	Remediation
Pricing API 400	Verify `--sku` included. Free tiers: skip API
MCP pricing unavailable	Dispatch `subagent-pricing.md` as `task` fallback (uses direct HTTP to `prices.azure.com`)
Prereq output missing	Trigger prereq backfill
Quota check fails	Fall back to best-effort estimate + disclaimer
Override conflicts	Re-run from Step 3 with new constraints