1# Artifact Generation
2 
3Generate infrastructure and configuration files based on selected recipe.
4 
5## ⛔ CRITICAL: Check for .NET Aspire Projects FIRST
6 
7**MANDATORY: Before generating any files, detect .NET Aspire projects:**
8 
9```bash
10# Method 1: Find AppHost project files
11find . -name "*.AppHost.csproj" -o -name "*AppHost.csproj"
12 
13# Method 2: Search for Aspire packages
14grep -r "Aspire\.Hosting\|Aspire\.AppHost\.Sdk" . --include="*.csproj"
15```
16 
17**If Aspire is detected:**
181. ⛔ **STOP** - Do NOT manually create `azure.yaml`
192. ⛔ **STOP** - Do NOT manually create `infra/` files
203. ✅ **USE** - `azd init --from-code -e <env-name>` instead
214. 📖 **READ** - [aspire.md](aspire.md) and [recipes/azd/aspire.md](recipes/azd/aspire.md) for complete guidance
22 
23**Why this is critical:**
24- Aspire AppHost auto-generates infrastructure from code
25- Manual `azure.yaml` without `services` section causes "infra\main.bicep not found" error
26- `azd init --from-code` correctly detects AppHost and generates proper configuration
27 
28> ⚠️ **Manually creating azure.yaml for Aspire projects is the most common deployment failure.** Always use `azd init --from-code`.
29 
30## Check for Other Special Patterns
31 
32After verifying the project is NOT Aspire, check for these patterns:
33 
34| Pattern | Detection | Action |
35|---------|-----------|--------|
36| **Complex existing codebase** | Multiple services, existing structure | Consider `azd init --from-code` |
37| **Existing azure.yaml** | File already present | MODIFY mode - update existing config |
38 
39> **CRITICAL:** After running `azd init --from-code`, you **MUST** immediately set the user-confirmed subscription with `azd env set AZURE_SUBSCRIPTION_ID <id>`. Do NOT skip this step. See [aspire.md](aspire.md) Step 3 for the complete sequence.
40 
41## CRITICAL: Research Must Be Complete
42 
43**DO NOT generate any files without first completing the [Research Components](research.md) step.**
44 
45The research step loads service-specific references and invokes related skills to gather best practices. Apply all research findings to generated artifacts.
46 
47## Research Checklist
48 
491. ✅ Completed [Research Components](research.md) step
502. ✅ Loaded all relevant `services/*.md` references
513. ✅ Invoked related skills for specialized guidance
524. ✅ Documented findings in `.azure/deployment-plan.md`
53 
54## Generation Order
55 
56| Order | Artifact | Notes |
57|-------|----------|-------|
58| 1 | Application config (azure.yaml) | AZD only—defines services and hosting |
59| 2 | Application code scaffolding | Entry points, health endpoints, config |
60| 3 | Dockerfiles | If containerized |
61| 4 | Infrastructure (Bicep/Terraform) | IaC templates in `./infra/` |
62| 5 | CI/CD pipelines | If requested |
63 
64## Recipe-Specific Generation
65 
66Load the appropriate recipe for detailed generation steps:
67 
68| Recipe | Guide |
69|--------|-------|
70| AZD | [AZD Recipe](recipes/azd/README.md) |
71| AZCLI | [AZCLI Recipe](recipes/azcli/README.md) |
72| Bicep | [Bicep Recipe](recipes/bicep/README.md) |
73| Terraform | [Terraform Recipe](recipes/terraform/README.md) |
74 
75## Common Standards
76 
77### File Structure
78 
79```
80project-root/
81├── .azure/
82│   └── deployment-plan.md
83├── infra/
84│   ├── main.bicep (or main.tf)
85│   └── modules/
86├── src/
87│   └── <component>/
88│       └── Dockerfile
89└── azure.yaml (AZD only)
90```
91 
92### Directory Creation
93 
94> ⚠️ **Warning:** The `create` tool fails with `Parent directory does not exist` when intermediate directories are missing. Always create the full directory tree before writing files.
95 
96**Before creating nested files** (e.g., `src/frontend/src/App.jsx`), create all parent directories first:
97 
98```bash
99mkdir -p src/frontend/src src/api
100```
101 
102- Use **absolute paths** in `mkdir -p` when the working directory may differ from the project root
103- Create directories for **all components** in a single command before writing any files
104- Do **not** rely on the `create` tool to create parent directories — it will not
105 
106### Security Requirements
107 
108- No hardcoded secrets
109- Use Key Vault for sensitive values
110- Managed Identity for service auth
111- HTTPS only, TLS 1.2+
112- SQL Server Bicep MUST use Entra-only auth — omit `administratorLogin` and `administratorLoginPassword` entirely, including from conditional/ternary branches (see [services/sql-database/bicep.md](services/sql-database/bicep.md)). These property names must not appear anywhere in a generated `.bicep` file.
113- **SQL + Managed Identity: MUST add postprovision hook** — ARM role assignments only grant control-plane access; you MUST also generate `scripts/grant-sql-access.sh` + `.ps1` and add a `postprovision` hook in `azure.yaml` to run T-SQL grants. See [services/sql-database/bicep.md](services/sql-database/bicep.md).
114- **App Service Bicep: MUST include `azd-service-name` tag** — Every App Service `Microsoft.Web/sites` resource MUST have `tags: union(tags, { 'azd-service-name': serviceName })`. Without this tag, `azd deploy` cannot locate the resource. See [services/app-service/bicep.md](services/app-service/bicep.md).
115 
116### Runtime Configuration
117 
118Apply language-specific production settings for containerized apps:
119 
120| Runtime | Reference |
121|---------|-----------|
122| Node.js/Express | [runtimes/nodejs.md](runtimes/nodejs.md) |
123 
124## After Generation
125 
1261. Update `.azure/deployment-plan.md` with generated file list
1272. Run validation checks
1283. Proceed to **azure-validate** skill
129