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	azure-cost
Estimating VM-specific costs	azure-compute
Enterprise landing zone architecture	azure-enterprise-infra-planner

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