Aspire OrchestrationCAUTION

An Aspire reference architecture for cloud-native microservices and agentic AI with MCP, A2A & AG-UI

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: aspire-orchestration
description: >-
  **WORKFLOW SKILL** — Manage Aspire lifecycle in VS Code or the CLI.
  WHEN: "start or stop my Aspire app", "aspire_apphost_start",
  "aspire_apphost_stop", "notEditorOwned", "ambiguousSession", "aspire start",
  "aspire stop", "aspire wait", resource restart, file-lock errors (MSB3491 or
  CS2012), port conflicts, git worktrees, "--isolated", "aspire update --self",
  "aspire update --migrate", "aspire describe --include-hidden", "aspire stop --force",
  "aspire terminal", integration discovery, default watch, or hot reload.
  INVOKES: VS Code lifecycle tools first when exposed; Aspire CLI for readiness,
  inspection, resource operations, isolated worktree starts, and allowed fallbacks.
  DO NOT USE FOR: deploy/publish/destroy (aspire-deployment), logs/traces/metrics
  (aspire-monitoring), or AppHost code and resource wiring (aspireify).
  FOR SINGLE OPERATIONS: Load the matching editor tool first, then obey the
  exact-target, worktree-isolation, and stop-result rules below.
license: MIT
metadata:
  author: Microsoft
  version: "0.0.3"
---

# Aspire Orchestration

> **MANDATORY COMPLIANCE** — This skill prevents agent self-harm in Aspire projects.
> Violating these rules causes file locks, orphaned processes, and user frustration ([#15801](https://github.com/microsoft/aspire/issues/15801)).

## Prerequisites

| Requirement                                 | Install                                           |
| ------------------------------------------- | ------------------------------------------------- |
| .NET 10.0 SDK                               | https://dotnet.microsoft.com/download             |
| Aspire CLI (curl/PowerShell)                | `curl -sSL https://aspire.dev/install.sh \| bash` |
| Aspire CLI (npm)                            | `npm install -g @microsoft/aspire-cli`            |
| Aspire CLI (NativeAOT global tool, .NET 10) | `dotnet tool install -g Aspire.Cli`               |

Use the installation method owned by the user's environment. npm, Nix, Homebrew, WinGet,
mise, and the install scripts are supported alongside the NativeAOT .NET global tool.

## Detection

Activate when ANY signal is present:

| Signal                | How to Detect                                                | Confidence    |
| --------------------- | ------------------------------------------------------------ | ------------- |
| C# AppHost            | `.csproj` containing `Aspire.AppHost.Sdk`                    | ✅ Definitive |
| File-based C# AppHost | `apphost.cs` or `.cs` file with `#:sdk Aspire.AppHost.Sdk`   | ✅ Definitive |
| TypeScript AppHost    | Current `apphost.mts` or legacy `apphost.ts` file in project | ✅ Definitive |
| Aspire config         | `aspire.config.json` in project root                         | High          |
| Aspire settings       | `.aspire/` directory present                                 | High          |
| Generated TS modules  | `.aspire/modules/` directory present                         | High          |
| Service defaults      | `Aspire.ServiceDefaults` in project references               | Medium        |

See [detection.md](references/detection.md) for detailed fingerprinting.

## VS Code AppHost Lifecycle

When the agent host exposes `aspire_apphost_start` or `aspire_apphost_stop`, use the
matching tool before running `aspire start` or `aspire stop` in a terminal, except when
starting from a git worktree requires `--isolated` and the tool cannot request it. If the
tool is listed as deferred, load its contract with the host's tool-discovery mechanism
first; do not treat an unloaded deferred tool as unavailable.

Pass the exact selected `appHostPath` discovered by Aspire to editor lifecycle tools. In a
multi-root workspace, that tool contract may require a selector such as
`repo-a~1/MyApp.AppHost/MyApp.AppHost.csproj`.

The CLI `--apphost` flag does not understand that selector namespace. Before any CLI
start/stop fallback, resolve the selected AppHost to its actual filesystem project path
and pass that path to `--apphost`; never copy a multi-root selector verbatim. That CLI
project path may be workspace-relative (`MyApp.AppHost/MyApp.AppHost.csproj`) or
absolute (`/workspaces/repo-a/MyApp.AppHost/MyApp.AppHost.csproj` or
`C:\workspaces\repo-a\MyApp.AppHost\MyApp.AppHost.csproj`); use the current platform's
native path syntax. If several AppHosts are discovered and the user's target is unclear,
ask which one to use instead of guessing, invoking the tool for every AppHost, or
issuing an unscoped CLI command.

If the selected `appHostPath` is already a normal workspace-relative project path such
as `MyApp.AppHost/MyApp.AppHost.csproj`, reuse it unchanged for CLI fallbacks; do not
convert it to an absolute path just for the CLI.

**An unclear target is a hard stop.** Ask one clarifying question and wait for the user to
name an AppHost. Do not call a lifecycle tool or terminal command until the target is
resolved, and do not offer commands that bypass this gate. Stop multiple AppHosts only
when the user explicitly requests all of them.

For starts, call `aspire_apphost_start` with mode `run` and the exact selected
`appHostPath` unless the user explicitly asks to attach a debugger. In a git worktree, the
editor tool does not currently request Aspire's isolated state. Resolve the selected
AppHost to its filesystem path and use
`aspire start --non-interactive --isolated --apphost <filesystem-path>` instead.

`run` mode has no debugger attached, but it still has an editor-owned Aspire session that
`aspire_apphost_stop` can stop. After a stop call, follow this result matrix exactly:

| Tool result                             | Next action                                                                                                                                                | CLI stop allowed?    |
| --------------------------------------- | -------------------------------------------------------------

CAUTIONgrade C · trust 79/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

> `bin/`/`obj/`, do not "reboot to release the lock", and do not tell the user the

| Aspire CLI (curl/PowerShell)                | `curl -sSL https://aspire.dev/install.sh \| bash` |

Gates applied: instruction_override, no_behavioural_pass.