| name | plan |
| description | Create plan.md (technical context, architecture, design decisions) from the spec. |
User Input
$ARGUMENTS
Outline
$ARGUMENTS (if any) = additional planning guidance: constraints, preferences, tech choices to honor. Empty = plan from the spec as-is.
-
Load context. Read specs/feature.json → <feature_directory>. Read specs/constitution.md (principles, non-negotiables, out-of-scope) and <feature_directory>/spec.md (source of truth for what and why). Stop if either is missing and name the command to run first (/speckit:constitution or /speckit:specify).
-
Create the plan based on assets/plan-template.md, stored in <feature_directory>/plan.md with these sections:
- Technical context — language(s), runtime, key dependencies, target platform(s), external services (especially cloud/Azure).
- Architecture — components and how they interact; brief diagram or component list.
- Project structure — top-level directory layout and where new code will live.
- Design decisions — each as Decision → Rationale → Alternatives considered. Cover data model, interfaces/contracts, cloud topology when relevant.
- Risks & open questions — anything that could derail implementation, plus any
[NEEDS CLARIFICATION: <question>] markers carried over from the spec or newly discovered.
Guidelines: honor every constitution non-negotiable — if user request conflicts, surface it explicitly rather than silently overriding; make informed defaults, marking genuine unknowns as [NEEDS CLARIFICATION: <question>] instead of guessing; focus on how — what/why belong in spec.md, don't restate it; don't enumerate individual tasks or write code (that's /speckit:tasks and /speckit:implement).
-
Create the Azure deployment plan based on assets/azure-template.md, stored at the workspace root /azure.md. Fill in every field defined by the template; in particular:
- AZD Template — propose the best match from the Use Case → AZD Template Mapping table below (e.g.
Azure-Samples/azd-ai-starter-basic, Azure-Samples/todo-csharp-cosmos-sql). ASK the user to choose one of:
- Accept the suggestion.
- Pick a different template from the catalog.
- Start from a minimal scaffold with no template (record
minimal in azure.md; step 5 will use azd init --minimal).
- Opt out of
azd init entirely (record none in azure.md).
- AZD Environment — default to
dev; ASK the user to confirm.
- Azure Subscription Id / Name — read the current default with
az account show -o json and ASK the user to confirm both id and display name.
- Resource Group — propose
rg-<feature-name> and verify it doesn't already exist with az group exists --name <name>. If it exists, suggest an alternative (e.g. append a short suffix). ASK the user to confirm the final name before writing it to azure.md.
- Azure Region — suggest a region appropriate for the chosen AZD template and ASK the user to confirm.
- Other sections — keep only the sections required by the chosen template / use case; delete the rest per the template's guidance.
Where possible, group above asks to the user to simplify interactions.
Never invent a subscription, region, or resource group. Mark anything still unresolved as [NEEDS CLARIFICATION: <question>].
-
Install skills — Skills required to plan and implement the feature. Using the Skills → AZD Templates Mapping table below, derive the recommended skill set for the chosen AZD template and fill-in the table in the Skills section.
- Minimal set (always recommended):
azure-cost.
- Add template-specific skills based on the mapping (e.g.
microsoft-foundry, azure-ai for Azure-Samples/azd-ai-starter-basic; azure-messaging when the template provisions Service Bus / Event Grid; etc.).
Present the proposed list (minimal + template-specific) to the user and ASK for confirmation before filling in the Skills section.
gh skills install <SKILL repository> <SKILL name> --dir .github/skills --agent github-copilot
If a skill is already present under .github/skills/, ASK the user whether to reinstall (update to the latest version) or keep the existing version; skip the install when the user chooses to keep it.
-
Execute skills to populate values in /azure.md that depend on a skill execution. If a field's value must be produced by a skill, run that skill in-place, ASK the user to confirm the skill output suggestion and write the resolved value into /azure.md. Do not leave [NEEDS CLARIFICATION: populate via <skill-name>] markers behind — /speckit:plan must exit with /azure.md fully resolved.
-
Report the paths to <feature_directory>/plan.md and <feature_directory>/azure.md, a one-line summary of the chosen approach (including the selected AZD template), the list of recommended skills (installed by /speckit:implement), and any unresolved [NEEDS CLARIFICATION] items from either file.
AZD Templates Reference
Use the catalog and mapping tables below as the source of truth when selecting the AZD Template value in step 3. Prefer the use-case mapping first; fall back to the full catalog only when no mapping row fits.
Catalog
The following Azure Developer CLI (azd) templates are available from the Azure Developer CLI templates overview:
| GitHub repo | Template Name | Language | App host | Tech Stack |
|---|
| Azure-Samples/azd-ai-starter-basic | Microsoft Foundry resources for building and running AI agents | IaC only | — | Microsoft Foundry, Azure Container Registry, Application Insights, Log Analytics Workspace |
| Azure-Samples/todo-csharp-cosmos-sql | React Web App with C# API and MongoDB on Azure | C# | Azure App Service | Azure Cosmos DB for NoSQL, Bicep |
| Azure-Samples/todo-csharp-sql | React Web App with C# API and SQL Database on Azure | C# | Azure App Service | Azure SQL Database, Bicep |
| Azure-Samples/todo-csharp-sql-swa-func | Static React Web App + Functions with C# API and SQL Database on Azure | C# | Azure Static Web Apps, Azure Functions | Azure SQL Database, Bicep |
| Azure-Samples/todo-java-mongo | React Web App with Java API and MongoDB on Azure | Java | Azure App Service | Azure Cosmos DB API for Mongo, Bicep |
| Azure-Samples/todo-java-mongo-aca | Containerized React Web App with Java API and MongoDB on Azure | Java | Azure Container Apps | Azure Cosmos DB API for Mongo, Bicep |
| Azure-Samples/todo-nodejs-mongo | React Web App with Node.js API and MongoDB on Azure | Node.js | Azure App Service | Azure Cosmos DB for MongoDB, Bicep |
| Azure-Samples/todo-nodejs-mongo-terraform | React Web App with Node.js API and MongoDB (Terraform) on Azure | Node.js | Azure App Service | Azure Cosmos DB for MongoDB, Terraform |
| Azure-Samples/todo-nodejs-mongo-aca | Containerized React Web App with Node.js API and MongoDB on Azure | Node.js |
Use Case → AZD Template Mapping
Match the feature's primary use case and language preference to a recommended template:
Skills → AZD Templates Mapping
The following table maps the Azure skills catalog to the AZD templates where each skill is most relevant. Use it to install the right set of skills alongside the chosen template.
Install a skill with:
gh skills install <SKILL repository> <SKILL name> --dir .github/skills --agent github-copilot
For every skill below, <SKILL repository> is microsoft/azure-skills and <SKILL name> is the value in the SKILL name column.
Default skill set (always recommended)
Install these on every feature regardless of the chosen AZD template. All come from microsoft/azure-skills.
Template-specific skills
Add these on top of the default set when the chosen AZD template matches.
