azure-scaffold-wizard

name

azure-scaffold-wizard

description

Scaffold a complete, production-ready Azure project from scratch for ANY use case: RAG chatbots, multi-agent systems, API backends, data pipelines, Azure Functions, full-stack web apps, ML training/inference, or event-driven microservices. USE FOR: gathering requirements through adaptive questioning, generating complete project folder structures with all source files, Azure Bicep infrastructure, azure.yaml for azd-up deployment, Docker configuration, CI/CD workflows, README with architecture diagrams, and Responsible AI documentation. Produces fully deployable Azure projects targeting Azure Container Apps, Azure AI Foundry, Azure Functions, or Azure ML. DO NOT USE FOR: modifying existing projects, deploying to Azure (use azure-deploy skill), managing Azure resources (use azure-prepare skill).

Azure Scaffold Wizard — Universal Project Generator

This skill generates a complete, production-ready Azure project deployable with azd up. It is fully domain-agnostic and applies to any use case. It produces every file needed: requirements documentation, project structure with all source files, README, Azure Bicep infrastructure, azure.yaml, Docker configuration, CI/CD workflows, architecture diagrams, observability setup, and Responsible AI documentation.

---

Required Workflow

Follow these steps in order. Do not skip or reorder steps. Each step's output feeds the next.

---

Step 1 — Identify Project Type and Gather Requirements

This is the most critical step. Do not generate any files until this step is complete.

1A — Project Type Selection

Ask the user: "What type of Azure project do you want to build?"

Present these options:

#	Project Type	Description	When to Choose
1	RAG Chatbot	Retrieval-Augmented Generation chatbot with vector search	Conversational AI grounded in your own data
2	Multi-Agent System	Multiple AI agents coordinated by an orchestrator	Parallel/sequential AI reasoning pipeline (Foundry compatible)
3	API Backend	REST or GraphQL API service	Backend service with database and Azure deployment
4	Data Pipeline	ETL/ELT data processing pipeline	Batch or streaming data transformation
5	Azure Functions	Serverless event-driven functions	Lightweight event triggers and integrations
6	Full-Stack Web App	Frontend + Backend web application	Complete web application with UI
7	ML Training & Inference	Model training and serving endpoint	Custom ML model lifecycle on Azure ML
8	Event-Driven Microservices	Message-based distributed system	Async decoupled services at scale

If the user's request does not fit these categories exactly, choose the closest match or combine patterns. For detailed descriptions, read references/project-types.md.

1B — Universal Requirements (ask for ALL project types)

#	Question	Guidance
U1	What business problem does this solve?	One sentence. Drives README opening and all documentation.
U2	Who are the end users?	Drives UI design, access control decisions, RBAC roles.
U3	What is the project name?	kebab-case slug for folder names, azure.yaml, and resource naming.
U4	Programming language?	Python (default), TypeScript, C#, or multi-language. Drives all source file templates.
U5	Azure region?	Default: eastus2. Constrain by AI model availability if applicable.
U6	Authentication required?	None (default scaffold), Microsoft Entra ID (production).
U7	What Azure services beyond the defaults?	e.g., Cosmos DB, Service Bus, Key Vault, Storage, Redis. Drives extra Bicep modules.
U8	Frontend required?	Yes/No. If yes: Next.js (default), React SPA, or other.
U9	What compliance or regulatory requirements?	e.g., HIPAA, SOC2, GDPR. Drives TRANSPARENCY_FAQ.md and security docs.
U10	Target deployment platform?	Azure Container Apps (default), Azure Functions, AKS, App Service.
U11	Use Azure AI Foundry Agent Service?	Yes (default for AI-capable types): AI processing via Foundry Hosted Agents with structured output, managed deployment, and MAF. No: hand-rolled code using Azure OpenAI SDK directly. When to ask: Type 1 (RAG) — always ask. Types 3, 4, 5, 6, 8 — ask only after the type-specific "Include AI?" question is answered Yes. Skip for: Type 2 (Multi-Agent, always Foundry) and Type 7 (ML Training, uses Azure ML).

1C — Type-Specific Requirements

Based on the project type selected in 1A, read the corresponding reference file and ask the type-specific questions defined there:

Project Type	Reference File	What It Adds
RAG Chatbot	references/rag-chatbot.md	Vector store, embedding model, chunking strategy, data sources, conversation memory
Multi-Agent System	references/multi-agent.md	Agent names/roles, orchestration topology, MCP tools, Foundry model choice
API Backend	references/api-backend.md	Endpoints, database, API style (REST/GraphQL), rate limiting
Data Pipeline	references/data-pipeline.md	Data sources/sinks, scheduling, batch vs. stream, transformations
Azure Functions	references/function-app.md	Triggers, bindings, Durable Functions, runtime stack
Full-Stack Web App	references/full-stack-app.md	Frontend framework, SSR/SPA, state management, API integration
ML Training & Inference	references/ml-training.md	ML framework, compute targets, model registry, managed endpoints
Event-Driven Microservices	references/event-driven.md	Message broker, event schemas, KEDA scaling rules

The selected reference file contains:

• Type-specific qualifying questions
• The project folder structure for that type
• Source file templates and generation instructions
• Required Bicep modules list
• Type-specific quality checklist

1C-bis — Load Foundry Agent Patterns (Conditional)

If U11 = Yes (or if the project type is Multi-Agent), also read references/foundry-agent-patterns.md. This file provides the shared Foundry agent scaffolding patterns (agent.yaml, MAF main.py, schemas.py, skills, two-mode dispatcher, registration script) used by the type-specific reference file's "Foundry Mode" section. Exception: Multi-Agent projects use their own complete patterns in references/multi-agent.md — do not load foundry-agent-patterns.md for Multi-Agent.

1D — Document the Requirements

Create docs/requirements.md with a structured summary of ALL answers organized by section: Universal (U1–U11) and Type-Specific.

---

Step 2 — Generate Project Structure

Based on the requirements from Step 1, generate the folder layout.

Every project, regardless of type, includes these common root files and directories:

<project-slug>/
├── azure.yaml                          # azd project descriptor + hooks
├── docker-compose.yml                  # Local dev: all containers without Azure
├── docker-compose.override.yml         # Local overrides (ports, volumes, hot-reload)
├── .env.example                        # All env vars documented with descriptions
├── README.md
├── TRANSPARENCY_FAQ.md                 # Responsible AI FAQ
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
├── SUPPORT.md
├── LICENSE                             # MIT
│
├── .github/
│   └── workflows/
│       ├── ci.yml                      # PR validation: lint, type-check, test, Bicep build
│       └── deploy.yml                  # Push to main: build, push, deploy
│
├── infra/
│   ├── main.bicep                      # Subscription-scoped entry point
│   ├── main.parameters.json            # azd parameter bindings
│   ├── abbreviations.json              # Azure resource name prefix map
│   └── modules/                        # (varies by project type + U7 choices)
│
├── scripts/
│   ├── preprovision.sh                 # Region + model validation (posix)
│   ├── preprovision.ps1                # Region + model validation (windows)
│   ├── postprovision.sh                # Build, push, register (posix)
│   └── postprovision.ps1               # Build, push, register (windows)
│
├── docs/
│   ├── requirements.md                 # Output of Step 1
│   ├── architecture.md                 # Narrative architecture description
│   ├── DeploymentGuide.md              # Step-by-step azd up walkthrough
│   ├── production-migration.md         # Scaffold → production gaps
│   ├── troubleshooting.md              # Common errors + fixes
│   └── images/
│       └── readme/
│           ├── solution-architecture.svg
│           └── pipeline-flow.svg       # (if applicable)
│
└── <type-specific directories from reference file>

Read the type-specific reference file (loaded in Step 1C) for the additional directories and files specific to the selected project type.

---

Step 3 — Generate Type-Specific Source Files

Follow the generation instructions in the type-specific reference file loaded in Step 1C. This step produces the core application code.

Examples of what each type generates:

• RAG Chatbot: ingestion pipeline, vector store client, retrieval chain, chat API, prompt templates
• Multi-Agent System: agent containers with agent.yaml, schemas, skills, orchestrator backend, two-mode dispatcher
• API Backend: routers, models, services, middleware, database migrations
• Data Pipeline: pipeline definitions, transformers, connectors, scheduling config
• Azure Functions: function triggers, bindings, orchestrations, shared utilities
• Full-Stack Web App: frontend components, API client, backend endpoints, shared types
• ML Training: training scripts, model definitions, inference endpoints, evaluation
• Event-Driven: message handlers, event schemas, saga orchestrators, dead-letter processors

Generate ALL source files with complete, functional code — not placeholders or stubs.

When U11 = Yes (Foundry mode): The Foundry agent patterns from references/foundry-agent-patterns.md produce additional files: an agents/ directory with agent.yaml, main.py, schemas.py, skills/, plus a dispatcher (hosted_agents.py) and registration script (register_agents.py). The type-specific reference file specifies exactly which parts of the existing code the Foundry agent replaces vs which parts it augments.

---

Step 4 — Generate Azure Infrastructure and Deployment

4A — Bicep Infrastructure

Read references/bicep-patterns.md for universal Bicep patterns.

Generate infra/main.bicep (subscription-scoped) and all required modules.

Base modules for ALL project types:

• monitoring.bicep — App Insights + Log Analytics workspace
• container-registry.bicep — ACR (if containerized, which is most types)
• container-apps-env.bicep — Managed Environment (if U10 = ACA)
• container-app.bicep — Reusable per-app module
• role-assignments.bicep — RBAC for all managed identities

Add type-specific modules as listed in the loaded reference file (e.g., ai-foundry.bicep for RAG/Multi-Agent, ai-search.bicep for RAG, function-app.bicep for Functions).

Add optional service modules based on U7 answers: cosmos.bicep, storage.bicep, keyvault.bicep, servicebus.bicep, etc.

4B — azure.yaml and Hook Scripts

Read references/azure-yaml-patterns.md.

Generate:

• azure.yaml with preprovision and postprovision hooks
• scripts/preprovision.sh + scripts/preprovision.ps1 — validate region, model availability, exit non-zero on failure
• scripts/postprovision.sh + scripts/postprovision.ps1 — ACR login, image build with timestamp tag, registration

4C — Docker Configuration

Read references/docker-patterns.md.

Generate:

• Dockerfile for each service (multi-stage, non-root user, health checks)
• docker-compose.yml for local development
• docker-compose.override.yml for local overrides
• .dockerignore per service

4D — Observability Setup

Read references/observability-patterns.md for OpenTelemetry + Azure Monitor patterns.

Configure observability in all backend/API entry points:

• Azure Application Insights integration via OpenTelemetry
• Structured JSON logging
• Custom trace attributes for domain-specific telemetry
• FastAPI/Express lifespan integration

---

Step 5 — Generate Documentation and Architecture

5A — README.md

Read references/readme-template.md for the section template and conventions.

Generate a complete README with all required sections populated from requirements — no placeholder text.

5B — Architecture Diagrams

Read references/architecture-diagrams.md for SVG generation prompts and conventions.

Generate:

• docs/images/readme/solution-architecture.svg — Azure resource topology diagram
• docs/images/readme/pipeline-flow.svg — Data/agent flow diagram (if applicable)

SVG requirements: viewBox + preserveAspectRatio, system-ui fonts, no external imports, under 50KB.

5C — Responsible AI Documents

Read references/responsible-ai.md for the TRANSPARENCY_FAQ.md template.

Generate TRANSPARENCY_FAQ.md addressing all 6 required questions, populated with project-specific content from Step 1.

5D — CI/CD Workflows

Read references/cicd-patterns.md.

Generate .github/workflows/ci.yml and .github/workflows/deploy.yml with language-appropriate steps.

5E — Supporting Documents

Generate:

• docs/architecture.md — narrative description of the architecture
• docs/DeploymentGuide.md — step-by-step azd up walkthrough
• docs/production-migration.md — gaps between scaffold and production (auth, storage, scaling, security)
• docs/troubleshooting.md — common errors and fixes
• CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, SUPPORT.md

5F — Production Security Documentation

Read references/security-patterns.md for authentication, RBAC, Key Vault, and network isolation patterns.

Use these patterns to populate docs/production-migration.md with specific guidance for:

• Microsoft Entra ID integration (app registration, token validation)
• Role-based access control aligned with end users (U2)
• Azure Key Vault secret management
• VNet injection and private endpoints
• Input validation and sanitization

---

Step 6 — Quality Checklist

Run through this checklist before delivering. Every item must pass.

Universal Checks (all project types)

Requirements & Documentation:

• docs/requirements.md exists with all U1–U11 + type-specific answers
• TRANSPARENCY_FAQ.md covers all 6 required questions
• README includes all required sections with no placeholder text
• docs/production-migration.md documents all production gaps

Infrastructure:

• main.bicep is subscription-scoped (targetScope = 'subscription')
• All secrets use @secure() — no plain-text secret outputs
• main.parameters.json binds all params to ${AZURE_*} azd env vars
• Role assignments grant appropriate roles to all managed identities

azure.yaml & Deployment:

• IMAGE_TAG is always a timestamp (YYYYMMDDHHmmss), never latest
• Preprovision hook validates region and exits non-zero on failure
• Postprovision hook validates images before registration
• Hooks have both windows (pwsh) and posix (sh) variants

Docker:

• All Dockerfiles use non-root user
• docker-compose.yml enables full local development without Azure
• .env.example documents ALL required environment variables

CI/CD:

• ci.yml has lint + type-check + test + Bicep validation steps
• deploy.yml builds, pushes, and deploys on main branch

Architecture Diagrams:

• All SVGs use viewBox + preserveAspectRatio="xMidYMid meet"
• No external font imports (use system-ui)
• SVGs render correctly in a browser

Observability:

• App Insights connection string configured in all containers
• OTel trace setup in backend/API entry point

Type-Specific Checks

Run the quality checklist defined in the loaded type-specific reference file from Step 1C.

Foundry Agent Checks (if U11 = Yes)

Run these in addition to Universal and Type-Specific checks:

• agent.yaml has meaningful description: (2-3 sentences, not a placeholder)
• main.py uses default_options={"response_format": Schema} for structured output
• schemas.py has confidence_score, confidence_level, summary, and errors fields
• skill.md defines role, input contract, step-by-step instructions, and output requirements
• register_agents.py passes description=agent_def["description"] to create_version()
• hosted_agents.py correctly switches between Foundry mode and direct HTTP mode
• docker-compose.yml does NOT set AZURE_AI_PROJECT_ENDPOINT on the backend (enables local mode)
• ai-foundry.bicep module is included in infra/main.bicep
• RBAC includes both Cognitive Services OpenAI User and Azure AI User roles
• Postprovision hook calls register_agents.py