The-transit-Project/.github/agents/azure-debug-generate/references/runtimes/_template.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.

{Runtime} — Debug & Build Configuration

Template — Copy this file to runtimes/{rt}.md when adding a new runtime.

---

Prerequisites

Tool	Detection Command	Required For	Install Link
{tool}	{tool} --version	{purpose}	{install-url}

---

Debugger Properties

Property	Value	Notes
Debug protocol	{protocol}	The wire protocol the runtime exposes (e.g., Node Inspector, CoreCLR DAP, debugpy DAP, JDWP, Delve DAP).
VS Code debugger type	{type}	The VS Code debugger adapter identifier (e.g., node, coreclr, debugpy, java, go).
Base debug port	{port}	Default debug port for this runtime; overridden per-service in monorepos

VS Code Problem Matchers

Task	Watch Problem Matcher	Build Problem Matcher
{task}	{matcher}	{matcher}

---

Build Chain

Chain shape (startup task comes from the project type):

"{service-id}: {startup task}"              ← from project-types/{type}.md Runtime Wiring
       ├── dependsOn: "{service-id}: {build/watch step}"  ← this file
       └── dependsOn: "Start Emulators"     ← only when emulators are required

Task label scoping: All task labels MUST be prefixed with the service ID derived from the plan's Service Label column. See generate.md § Service ID Derivation.

Build Commands

Step	Command	Purpose	Background?
Start Emulators	docker compose up -d	Start all emulator services (idempotent — no-op if already running)	No

See generate.md § Task runOptions Rules for how these build steps are rendered into VS Code task configuration.

---

Convenience Scripts

The plan's Convenience Scripts table specifies WHICH scripts to generate. This section covers HOW to register them for this runtime.

Script runner: {file} (e.g., package.json scripts, scripts/ directory, Makefile, pyproject.toml) Run command pattern: {command} (e.g., npm run {script}, ./scripts/{script}.sh)

When the runtime's script runner is not inherently cross-platform (e.g., standalone scripts vs package.json), generate platform-appropriate scripts or document cross-platform alternatives.

Script Format

Common Script Implementations

Use these implementations when building scripts from the plan:

Script Purpose	Typical Command	Notes
Start emulators	docker compose up -d	Idempotent — safe to re-run
Stop emulators	docker compose down	Stops and removes containers
Clean emulator data	Stop containers with volumes, then remove bind-mount data directories	Run docker compose down -v (-v also drops named volumes like Postgres's postgres_data), then remove {data-dirs} = ./.{name} bind-mount directories derived from docker-compose.yml volumes: mounts. Use platform-appropriate removal.
Run migrations	{migration tool CLI command}	See migrations.md for how to determine the command

---

VS Code Extension Recommendations (.vscode/extensions.json)

Extension ID	Why Required
{extension-id}	{reason}

---

VS Code Workspace Settings (.vscode/settings.json)

Setting	Value	Why
{setting.key}	{value}	{reason}

---

Checklist — {Runtime} Validation

⛔ MANDATORY — runs during Phase 3 validation after all artifacts are generated. You MUST verify every item below. Do NOT skip, assume, or approximate results.

After generating VS Code configuration, verify the following were produced correctly:

Post-Generation Checks

1. ✅ Build task exists in tasks.json with the correct problem matcher
2. ✅ launch.json uses the correct debugger type and request mode
3. ✅ .vscode/extensions.json includes runtime extensions listed above

Live Validation Checks

Project-type-specific checks (e.g., startup task, connection strings) are defined in project-types/{type}.md.