Azure App Onboard Scaffold — Génération IaC + Auto-examen

Générez un code d'infrastructure prêt pour le déploiement à partir d'un plan d'architecture, vérifiez-le avec un auto-examen contradictoire et faites le lien vers la validation — tout cela sans déployer.

Référence rapide

Quand utiliser cette compétence

Invoquée par l'orchestrateur azure-app-onboard en Phase 3 quand prepare-plan.json existe avec services[]. Non directement routée par l'utilisateur en v1.

Retour à l'orchestrateur : Une fois terminé, retournez le contrôle à azure-app-onboard. N'invoquez PAS directement deploy — l'orchestrateur gère les transitions de phase.

Quand NE PAS utiliser

Outils MCP

Voir outils partagés pour les outils inter-phases et les paramètres globaux. Voir outils scaffold pour les tableaux de paramètres complets.

Flux de travail

Dossier de session : .copilot-azure/sessions/{uuid}/ — lit prepare-plan.json + context.json, écrit scaffold-manifest.json.

DÉTECTION (Étapes 1–4)

1. Lire prepare-plan.json — vérifier que services[] existe, lire la config naming (notamment naming.resourcePrefix, naming.suffix, naming.resources[]). Lire le nom du groupe de ressources depuis context.json.azure.resourceGroup. ⛔ Utiliser EXACTEMENT ces noms dans l'IaC générée — ne PAS inventer de noms, les dériver de environmentName, ou ajouter vos propres suffixes. ⛔ Utiliser EXACTEMENT les noms de prepare-plan.json.naming.resources[] comme paramètres Bicep. Ne PAS dériver les noms avec take(), substring(), ou manipulation de chaîne. Le plan est la source de vérité. Manquant → déclencher le remplissage de préparation via l'orchestrateur azure-app-onboard.
2. Lire context.json — vérifier overrides[] pour la préférence iacFormat, detectedInfra[] pour .tf existant, detectedInfraProvider pour la classification du fournisseur cloud.
3. Vérifier le workspace pour l'IaC existant — ⛔ Ignorer si context.json.overrides[] contient ignoreExistingInfra: true. Sinon :
   • IaC Azure (.bicep, azure.yaml, .tf avec azurerm) : ask_user → « Recommencer à zéro » (renommer infra/ en infra.bak/) ou « Utiliser le code existant » (router vers azure-prepare, arrêter le pipeline).
   • IaC non-Azure (.tf avec GCP/AWS) : respecter context.json.overrides[].iacFormat de la préparation. Par défaut : Bicep à côté du TF existant.
   • TF inconnu (detectedInfraProvider.terraform == "unknown") : demander à l'utilisateur quel fournisseur avant le routage.
   • Pas d'IaC : continuer.
4. Déterminer les cibles de calcul — Vérifier quelles cibles de calcul se trouvent dans le plan (App Service/Functions, Container Apps, ou les deux) et si PostgreSQL/Redis est présent. Ne PAS lire de fichiers de référence — transmettre ces informations au sous-agent à l'Étape 5. 4b. Pré-vérification des versions d'API (thread principal) — L'accès aux outils MCP est peu fiable dans les agents task — appeler ceux-ci dans le thread principal avant la dispatch. Appeler mcp_bicep_list_az_resource_types_for_provider (ou bicep-list_az_resource_types_for_provider) une fois par espace de noms de fournisseur dans prepare-plan.json.services[] (par ex. Microsoft.Web, Microsoft.App, Microsoft.DBforPostgreSQL, Microsoft.Cache, Microsoft.KeyVault, Microsoft.ContainerRegistry). Extraire la dernière version d'API GA (sans -preview) pour chaque type de ressource. Construire une carte apiVersions et la transmettre au sous-agent de génération IaC à l'Étape 5. Fallback : si MCP indisponible, exécuter az provider show --namespace {ns} --query "resourceTypes[?resourceType=='{type}'].apiVersions[?!contains(@, 'preview')] | [0][0]" -o tsv par type de ressource — cela filtre sur GA uniquement et choisit la plus récente. Transmettre "MCP unavailable" uniquement si MCP ET CLI échouent. Le sous-agent valide toujours le Bicep généré via az bicep build.

ACTION (Étapes 5–12)

⛔ Limite de fichier : Ne JAMAIS modifier les fichiers en dehors de infra/, .copilot-azure/. Scaffold ne fait qu'écrire des fichiers — pas de commandes install/build.

⛔ La délégation au sous-agent est OBLIGATOIRE pour les Étapes 5, 6–9 et 10–12. Chaque étape lit son modèle subagent-*.md, puis dispatch un appel task. Ne PAS lire de fichier de référence qui n'est pas explicitement nommé dans ces étapes.

⛔ Type de dispatch : task UNIQUEMENT — JAMAIS general-purpose. general-purpose fuite le contexte du sous-agent dans le thread principal, accélérant la compaction et expulsant le workflow de l'orchestrateur. task isole le contexte du sous-agent.

⛔ Comment dispatcher — COPIE VERBATIM requise :

1. view le fichier modèle subagent-*.md
2. Votre action SUIVANTE DOIT être un appel à l'outil task — pas view, powershell, create, ou TOUT autre outil
3. Le prompt de la task DOIT contenir le texte du modèle COMPLET et NON MODIFIÉ. Copier le modèle entre les délimiteurs <<<TEMPLATE_START>>> / <<<TEMPLATE_END>>> exactement comme montré ci-dessous. Ne PAS résumer, paraphraser, reformuler, ou omettre AUCUNE partie — le sous-agent a besoin de chaque instruction « Lire [fichier] » et « Faire : »
4. APRÈS le bloc de modèle, ajouter les sections de données (JSON du plan, remplacements, etc.)

Anti-pattern (cause des régressions) : Écrire votre PROPRE prompt listant les étapes de workflow ou décrivant ce qu'il faut générer. Le modèle contient déjà le workflow complet — votre rôle est le COPIER, pas le réécrire.

5. Génération IaC — ⛔ Vous DEVEZ dispatcher subagent-iac-gen.md comme une task. ⛔ agent_type: "task" — JAMAIS "general-purpose".

   <<<TEMPLATE_START>>>
   {coller le CONTENU ENTIER de subagent-iac-gen.md ici — non modifié}
   <<<TEMPLATE_END>>>
   
   ## Données (ajoutées par l'orchestrateur)
   ### prepare-plan.json
   {JSON complet}
   ### context.json.overrides
   {tableau overrides}
   ### prereq-output.json.buildRequirements
   {objet buildRequirements}
   ### prereq-output.json.warnings[]
   {tableau warnings}
   ### Cibles de calcul
   {App Service/Functions, Container Apps, ou les deux + si PostgreSQL/Redis présent}
   ### apiVersions
   {map depuis l'Étape 4b, par ex. {"Microsoft.KeyVault/vaults": "2023-07-01", ...} — ou "MCP unavailable" si ignoré}
   ### Répertoire de travail
   {chemin absolu}

   • Attendu : Fichiers IaC écrits dans infra/, liste de fichiers retournée pour scaffold-manifest.json.files[]
   • La balise app-onboard-skill: 'true' DOIT apparaître textuellement dans le Bicep généré.

5b. Checklist de déploiement (en parallèle avec l'Étape 5) — Dispatcher comme une task en parallèle avec le sous-agent de génération IaC ci-dessus. ⛔ agent_type: "task" — JAMAIS "general-purpose".

   <<<TEMPLATE_START>>>
   Vous êtes un générateur de checklist de déploiement. N'invoquez AUCUNE compétence.

   1. Lire la checklist de déploiement à : plugin/skills/azure-app-onboard/deploy/references/deploy-checklist-template.md
   2. Remplir les {placeholders} avec les vraies valeurs de prepare-plan.json (appName, rgName, subscriptionId, sessionId).
   3. Supprimer les sections qui ne s'appliquent pas à la cible de calcul de ce déploiement (par ex., supprimer la section App Service pour les déploiements Container Apps). Les en-têtes de section du modèle indiquent lesquels supprimer.
   4. Écrire le résultat dans le dossier de session à l'aide de l'outil `create`. Ce fichier survit à la compaction de conversation — deploy le relit après chaque commande longue.
   <<<TEMPLATE_END>>>

   ## Données (ajoutées par l'orchestrateur)
   ### prepare-plan.json
   {JSON complet}
   ### Chemin de session
   {.copilot-azure/sessions/{uuid}/}
   ### Cibles de calcul
   {App Service, Container Apps, Static Web Apps, ou combinaison}

• Attendu : deploy-checklist.md écrit dans le dossier de session. Si ce sous-agent échoue, le sous-agent de validation (Étapes 10b–12.5) attrapera le fichier manquant.

6–9. Auto-examen — ⛔ Vous DEVEZ dispatcher subagent-review.md comme une task. ⛔ agent_type: "task" — JAMAIS "general-purpose".

   <<<TEMPLATE_START>>>
   {coller le CONTENU ENTIER de subagent-review.md ici — non modifié}
   <<<TEMPLATE_END>>>

   ## Données (ajoutées par l'orchestrateur)
   ### Fichiers IaC générés
   {contenu complet de chaque fichier .bicep/.tf}
   ### prepare-plan.json (services, naming, deploymentVariables)
   {sections pertinentes}
   ### prereq-output.json.warnings[]
   {tableau warnings}

• Attendu : JSON des findings → écrire dans scaffold-manifest.json.selfReview
• FLAGGÉ au L1/L3 → corriger l'IaC avant de continuer

VALIDATION → MANIFESTE → APPROBATION (Étapes 10–12.5)

10a. Formater l'IaC (thread principal) — Pour chaque fichier .bicep dans infra/ (y compris modules/) : appeler mcp_bicep_format_bicep_file (ou bicep-format_bicep_file) avec { filePath: "<chemin absolu>" }. Cela applique les fins de ligne LF via le bicepconfig.json écrit pendant la génération IaC. Fallback : ignorer si indisponible.

10a-conf. Porte de conformité (thread principal — OBLIGATOIRE pour Bicep) — ⛔ Ignorer cette étape entière quand le scaffold a émis Terraform (infra/main.bicep absent) — ces vérifications sont Bicep uniquement (Terraform est validé syntaxiquement via terraform validate dans le sous-agent de validation). Sinon exécuter le script de conformité du répertoire scripts/ de cette compétence ; il capture déterministes les valeurs rejetées par ARM que az bicep build ne peut pas (valeurs Bicep invalides, mauvaise version DB, connexion DB réservée, enablePurgeProtection) :

   {scaffoldDir}/scripts/scaffold-conformance.ps1 -SessionPath ".copilot-azure/sessions/{uuid}" -InfraPath infra   # pwsh (préféré)
   bash {scaffoldDir}/scripts/scaffold-conformance.sh ".copilot-azure/sessions/{uuid}" infra                       # bash (seulement si pwsh indisponible ; a besoin de jq pour les vérifications dépendantes du plan)

⛔ Préférer le .ps1 quand pwsh est disponible — il exécute chaque vérification inconditionnellement. Le jumeau .sh ignore les vérifications dépendantes du plan (DB-VERSION-MATCH, SERVICES-COMPLETE, DB-NAME-PRESENT, WARN-FIXED) quand jq est absent. ⛔ Tout échec BLOCK → corriger l'IaC, relancer (max 3) ; ne jamais présenter la porte de déploiement avec un BLOCK ouvert. L'exécuter ici dans le thread principal — ne PAS déléguer au sous-agent de validation ou juger manuellement le résultat quand un shell existe. Passer le JSON au sous-agent de validation pour scaffold-manifest.json.conformance.

10b–12.5. Validation + manifeste — ⛔ Vous DEVEZ dispatcher subagent-validate.md comme une task. ⛔ agent_type: "task" — JAMAIS "general-purpose".

   <<<TEMPLATE_START>>>
   {coller le CONTENU ENTIER de subagent-validate.md ici — non modifié}
   <<<TEMPLATE_END>>>

   ## Données (ajoutées par l'orchestrateur)
   ### Chemins de fichiers IaC
   {liste des fichiers générés}
   ### Findings d'auto-examen (depuis les Étapes 6–9)
   {JSON des findings}
   ### prepare-plan.json
   {JSON complet}
   ### prereq-output.json.warnings[]
   {tableau warnings}
   ### prereq-output.json.healthEndpoint
   {chaîne de chemin santé détecté ou null}
   ### Résultat de conformité
   {JSON depuis l'Étape 10a-conf}
   ### Chemin de session
   {.copilot-azure/sessions/{uuid}/}

• Attendu : scaffold-manifest.json avec validationResult, checklist de déploiement généré
• Vérifier que deploy-checklist.md existe (écrit à l'Étape 5b) — si manquant, créer MAINTENANT depuis deploy-checklist-template.md. Vérifier que deploy-result.json existe — si manquant, créer depuis deploy-schemas.ts.
• ⛔ Vérifier la mise à jour context.json (thread principal — ne PAS déléguer). Lire .copilot-azure/sessions/{uuid}/context.json. Si completedPhases n'inclut pas "scaffold" OU currentPhase n'est pas "deploy", l'écrire vous-même via edit / create : ajouter "scaffold" à completedPhases, définir currentPhase à "deploy", mettre à jour lastModifiedUtc en UTC ISO 8601 courant. C'est une écriture de limite de phase requise par pipeline-rules.md — ne pas l'ignorer.
• ⛔ Retour à l'orchestrateur pour l'Étape 8 (Porte d'approbation de déploiement). Votre ACTION SUIVANTE DOIT être de présenter la Porte de Déploiement selon le SKILL.md de l'orchestrateur — ne PAS écrire un message « résumé des fichiers générés », ne PAS émettre de rapport d'achèvement. Le prompt de Porte de Déploiement (🚀 Prêt à déployer ? ...) est la SEULE sortie correcte suivante.

Boucle d'auto-réparation

En cas d'échec de validation → lire scaffold-healing-rules.md (cadence de réparation, PLAN_LEVEL_CHANGE, cohérence des artefacts). Ne PAS pré-lire.

Gestion des erreurs

• prepare-plan.json manquant : déclencher le remplissage via orchestrateur.
• IaC existant : géré dans l'Étape DÉTECTION 3.
• MCP indisponible : se rabattre sur les patterns de référence, flaguer comme « non vérifié ».
• Findings FLAGGÉS et épuisement de la réparation : voir scaffold-healing-rules.md.