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 |