**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 con

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? stopped or notRunning Report the result; take no further stop action No alreadyStopping , controller editor Report that the editor stop is already in progress; take no further stop action No alreadyStarting , controller editor Retry aspire apphost stop once; if it repeats, report that startup is still in progress and take no further stop action No notEditorOwned , controller external If the user requested that exact AppHost be stopped, resolve it to its filesystem path and run aspire stop non interactive apphost <filesystem path Yes failed , controller unknown Retry aspire apphost stop once; if the same result repeats, use the same exact target CLI command above Only after the retry ambiguousSession Stop nothing and have the user disambiguate in the editor Never Any other refusal or failure Resolve or report that result; do not change mechanisms No The rows are mutually exclusive. Act only on the current result; do not offer a command from another row as a speculative future workaround. Re evaluate only after a new tool result is returned. ambiguousSession is a terminal safety refusal. Do not run or offer a CLI fallback, and do not ask whether the user wants one. User confirmation cannot make an ambiguous editor session safe to terminate from the CLI. Use direct Aspire CLI lifecycle commands only when the matching editor tool is unavailable, for isolated worktree starts, or for a stop result explicitly marked as allowed above. When a CLI fallback is allowed, keep the target exact by resolving the selected AppHost to its filesystem path first. Safety Guardrails Situation ✅ ALWAYS Do ❌ NEVER Do Start an Aspire app aspire apphost start with mode run and the exact selected appHostPath when available; in a git worktree, use aspire start non interactive isolated apphost <filesystem path even when aspire apphost start is available dotnet run on AppHost Wait for resource ready aspire wait <resource curl / HTTP polling loops Code changed in a resource Prefer resource commands, runtime watch/HMR, dashboard actions, or IDE managed debugging dotnet build against locked files Task complete aspire apphost stop with the exact selected appHostPath when available; follow its result matrix Use an unapproved CLI fallback Check running AppHosts aspire ps Manual process inspection Check resource status aspire describe aspire ps resources (removed in 13.5) Remove persistent resources Confirm data loss and exact AppHost before aspire stop force apphost <filesystem path Combining force with all , or using it for an ordinary stop Working in git worktree aspire start non interactive isolated apphost <filesystem path aspire apphost start when it cannot request isolation Running from AI agent Load available lifecycle tools first; resolve CLI apphost fallbacks to <filesystem path ; add non interactive Assuming interactive terminal Editing unfamiliar API aspire docs search <topic then aspire docs api search <query for API reference Guessing API shape C AppHost API inspection Use dotnet inspect skill (if available) for local symbols Guessing overloads or builder chains Adding custom dashboard/resource commands aspire docs search "custom resource commands" first Inventing WithCommand patterns without docs Installing Aspire support Use aspire add or aspire init ~~ dotnet workload install aspire ~~ (obsolete) See [safety guardrails.md](references/safety guardrails.md) for detailed rules and recovery patterns. Default Workflow 1. Confirm workspace is Aspire — identify the AppHost 2. If the workspace is a git worktree, resolve the selected AppHost to a filesystem project path and use aspire start non interactive isolated apphost <filesystem path even when aspire apphost start is available, because the editor tool cannot request isolation. Otherwise, start with aspire apphost start in mode run using the exact selected appHostPath when available; if that tool is unavailable, resolve the selected AppHost to a filesystem project path and use aspire start non interactive apphost <filesystem path 3. aspire wait <resource before interacting with any resource 4. aspire describe to inspect state, then work 5. If AppHost code changed, restart through the same lifecycle routing; if only one resource changed, prefer the resource's commands/watch/HMR/debug workflow 6. Stop with aspire apphost stop using the exact selected appHostPath when available; use aspire stop non interactive apphost <filesystem path only for the documented fallback outcomes Quick Reference Task Command Start app (agents) Git worktree: aspire start non interactive isolated apphost <filesystem path even if aspire apphost start is available, because the tool cannot request isolation. Otherwise: aspire apphost start (mode run , exact selected appHostPath ); CLI fallback when the tool is unavailable: aspire start non interactive apphost <filesystem path Start app (human) aspire run (foreground, dashboard) Stop app aspire apphost stop (exact selected appHostPath ); result matrix fallback: aspire stop non interactive apphost <filesystem path Wait for resource aspire wait <resource List running AppHosts aspire ps Check resource status aspire describe Show hidden resources (proxies, helpers, migrations) aspire describe include hidden Resource operation aspire resource <resource name <command such as stop , start , or rebuild when exposed Discover resource commands aspire resource <resource name help Attach to an experimental resource terminal Enable features.terminalCommandsEnabled , then use aspire terminal ps / aspire terminal attach Create new project aspire new aspire starter Add Aspire to existing aspire init (then hand off to aspireify skill for wiring) Add integration aspire add <package Discover integrations aspire integration list format Json / aspire integration search <query format Json Upgrade the CLI itself aspire update self (managed installs may print the npm/.NET/Nix update command) Update project package refs aspire update yes non interactive after approval Migrate legacy TypeScript entry point Explain that package references, config, tsconfig, imports, and the entry point all change; after approval for the package update and migration, run aspire update migrate yes non interactive Restore generated files aspire restore Environment maintenance aspire cache clear , aspire certs trust , aspire certs clean Diagnose environment aspire doctor Machine readable output format Json (supported: ps , describe , start ) Look up API reference aspire docs api search <query language csharp\ typescript Browse API entries aspire docs api list <scope Get API detail aspire docs api get <id Error Handling Symptom Cause Action File lock errors during build ( MSB3491 , CS2012 ) Aspire is running and holds locks on bin/ , obj/ , and assemblies. Stop the AppHost through the lifecycle routing above , then rebuild or restart it. Do NOT conclude the project has a permanent build failure. "Port already in use" Previous instance running Stop, then restart through the lifecycle routing above Resource not found App not started or name wrong Use aspire ps to find the AppHost, then aspire describe to check resources Build errors in resource Code error, not Aspire issue Fix code, then use resource commands/watch/HMR/debug workflow or restart through the lifecycle routing if AppHost code changed Environment issues Missing SDK or tools aspire doctor to diagnose JSO

aspire-orchestration