aspire-orchestration

Manages Aspire AppHost lifecycle and recovers from file locks, port conflicts, and orphaned processes.

Updated Jun 2, 2026
One-click install
npx skills add https://github.com/codebytes/btt --skill aspire-orchestration-codebytes
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: aspire-orchestration
Source: https://github.com/codebytes/btt/tree/main/.agents/skills/aspire-orchestration
Command: npx skills add https://github.com/codebytes/btt --skill aspire-orchestration-codebytes

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? AI agents working in Aspire projects often cause file locks, orphaned processes, and port conflicts by running dotnet run or dotnet build against a live AppHost. This Skill enforces safe Aspire CLI workflows so agents start, wait on, inspect, and stop orchestrated apps without breaking the build or leaving stray processes. ## Core Features & Use Cases - Safe Lifecycle Management: Enforces aspire start, aspire wait, aspire stop, and aspire ps instead of dotnet run, curl polling loops, or manual process kills. - File-Lock Recovery: Diagnoses MSB3491 and CS2012 build errors as Aspire-held locks and prescribes aspire stop as the single correct recovery step. - Project Detection & Routing: Fingerprints C#, file-based, and TypeScript AppHosts, then hands off AppHost wiring to the aspireify skill and deployment to aspire-deployment. - Use Case: An agent hits "error MSB3491: Could not write to output file" while building a service. Instead of deleting bin/obj or declaring the project broken, it runs aspire stop, rebuilds, and restarts with aspire start. ## Quick Start Start my Aspire app in the background and wait until the API resource is ready before running any requests against it.

Frequently Asked Questions about aspire-orchestration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I start an Aspire app from an AI agent?

Use `aspire start` to run the AppHost in the background, adding `--non-interactive` for agent terminals and `--isolated` inside git worktrees. Never use `dotnet run` on the AppHost, since it bypasses orchestration, the dashboard, and resource management.

How do I fix MSB3491 or CS2012 file lock errors in an Aspire project?

These errors mean Aspire is running and holding locks on bin/ and obj/ outputs. Run `aspire stop` first, then rebuild or restart with `aspire start`. Do not delete bin/obj, kill dotnet processes, or treat it as a permanent build failure.

Should I use aspire run or aspire start?

Use `aspire start` for background, detached execution, which is the preferred mode for AI agents. Use `aspire run` only for interactive foreground sessions with a human at the terminal, since it blocks the terminal.

How do I detect whether a project uses Aspire?

Look for `Aspire.AppHost.Sdk` in a .csproj, an `apphost.cs` file with a `#:sdk Aspire.AppHost.Sdk` directive, or an `apphost.ts` file. Secondary signals include `aspire.config.json`, a `.aspire/` directory, and `Aspire.ServiceDefaults` references.

Why does aspire wait reject my resource name?

The `aspire wait` command expects the resource's `displayName`, not its `name` field, due to a known CLI issue. Run `aspire ps --format Json` and pass the `displayName` value to `aspire wait`.

When should I not restart the whole Aspire AppHost?

Avoid a full restart when only one resource's implementation changed. Use resource-scoped commands like `aspire resource <name> rebuild`, or rely on framework watch and hot module replacement for JavaScript frontends such as Vite.