The-transit-Project/.github/agents/azure-debug-generate/instructions.md

Important: This skill provides guidance and recommended instructions to assist the AI system. Outputs are not guaranteed to be complete, correct, secure, or applicable to every scenario. Results should be reviewed and validated by a human before being applied. The AI model may choose not to follow all instructions exactly, and additional verification may be required.

Azure Debug Generate

AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE

This document is the official, canonical source for generating VS Code debug configuration from an approved plan. You MUST follow these instructions exactly as written. When in doubt, defer to this document. Do not improvise, infer, or substitute steps.

---

Global Rules (NO EXCEPTIONS)

1. Plan is the source of truth — Read .azure/vscode-debug-plan.md and generate exactly what it specifies. Only generate artifacts for rows where Generate is checked ([x]).
2. Update plan progressively — Mark steps complete as you go; update Last Updated timestamp on every status change
3. ❌ Destructive actions require ask_user — Always confirm before overwriting, deleting, or modifying existing files
4. Preserve existing config — Never silently overwrite project configuration files or docker-compose.yml. Merge or ask first.
5. Scope — VS Code debug setup only — These instructions are for generating local debug configurations in VS Code. Cloud architecture, IaC generation, provisioning, and deployment are handled by the azure-deploy agent through the complete azure-app-onboard pipeline.
6. Warn on limited support — When a project type, runtime, or emulator declared in the plan has no matching reference file, emit a ⚠️ LIMITED SUPPORT: warning — limited-support.md.

---

Autopilot mode

Active when the invoking chat query begins with [AUTOPILOT MODE], or .azure/vscode-debug-plan.md contains executionMode: auto or equivalent. When active, run fully unattended:

• Do NOT call ask_user. This is the tail of an autopilot chain over a freshly generated project, so overwriting/merging the scaffolded config files is expected and safe — proceed without prompting (still preserve and merge existing configs rather than blindly overwriting).
• Validation (Phase 3) still runs in full — autopilot never skips validation or the Implemented status write. Setting status to Implemented is what signals the workflow is complete (the extension restores its auto-approve setting at that point).

---

Phase 1: Pre-Flight

Verify the plan and environment before generating any files.

#	Action	Reference
1	Verify plan — Confirm .azure/vscode-debug-plan.md exists with status Approved. Set status to Executing and update Last Updated.	.azure/vscode-debug-plan.md
2	Load references — For each service in the plan's Services table (where Generate is checked), load the corresponding project-type and runtime reference files. If no reference file exists, emit a limited-support warning.	limited-support.md
3	Run pre-flight checks — Stale data directories and port conflicts.	preflight.md

---

Phase 2: Generate

The plan drives implementation. Read each section of .azure/vscode-debug-plan.md and generate the corresponding artifacts. Use the reference files for implementation details — the plan specifies WHAT to generate, the references specify HOW.

Follow the generation steps in generate.md in order.

---

Phase 3: Validate

⚠️ CRITICAL: You MUST complete every validation step before proceeding. Do NOT mark the task as complete, do NOT set status to Implemented, and do NOT deliver a closing message until validation is finished and the checklist is updated with real results.

#	Action	Reference
1	Validate each launch configuration — Follow every step in validation.md for each non-compound config.	validation.md
2	Validate the compound configuration — Faithfully run each compound's orchestration per validation.md § Step 9, never inferring the result from the individual configs.	validation.md § Step 9
3	Tear down validation processes — Stop every process and emulator validation spawned (docker compose down) and verify all app HTTP, debug, and emulator ports are free again, so a subsequent user F5 starts from a clean slate.	validation.md § Final Teardown
4	Update Debug Configuration Checklist — Create or update the ## Debug Configuration Checklist section in .azure/vscode-debug-plan.md with real ✅ or ❌ results for each configuration.	validation.md § Plan Integration
5	Set status — Only after every checklist stub has been replaced with a real result, set plan status to Implemented and update Last Updated.	.azure/vscode-debug-plan.md

⛔ VALIDATION IS NOT OPTIONAL. Do NOT set status to Implemented until every stub in the Debug Configuration Checklist has been replaced with a real ✅ or ❌ result. A checklist with any remaining stubs or missing entries means validation is incomplete — go back and finish it. This is the single most common failure mode.

---

Outputs

Artifact	Location
Plan (updated)	.azure/vscode-debug-plan.md
Docker Compose	docker-compose.yml
VS Code Debug Config	.vscode/launch.json — see project-types/ and runtimes/
VS Code Build Config	.vscode/tasks.json — see project-types/ and runtimes/
VS Code Extensions	.vscode/extensions.json — see generate.md § assembly protocol
VS Code Settings	.vscode/settings.json — see generate.md § assembly protocol
Connection Strings	local.settings.json or .env
Convenience Scripts	Runtime-specific script runner (see runtimes/)
API Test Collections	api-test-collections/{service-id}/<test-name>/invoke.{sh,ps1}

---

Post-Generation

After validation completes with status Implemented, stop. Do not present next steps or a closing message — the azure-debug-generate agent handles post-generation guidance and interactive next steps.

Troubleshooting

For Edge or Chrome related startup issues, consult chromium.md.