From 3d1c0c06ef6b1a406f1cdb802e0efceed9da456a Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Thu, 24 Sep 2026 15:09:19 -0500 Subject: [PATCH] Document Aspire agent lifecycle options Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 41298945-9592-4284-be9e-be0c58f31fad --- .../docs/get-started/ai-coding-agents.mdx | 2 ++ .../docs/get-started/aspire-skills.mdx | 23 +++++++++++-------- .../get-started/aspire-vscode-extension.mdx | 13 ++++++++++- 3 files changed, 27 insertions(+), 11 deletions(-) diff --git a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx index dfb17d337..a1f8734b3 100644 --- a/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx +++ b/src/frontend/src/content/docs/get-started/ai-coding-agents.mdx @@ -69,6 +69,8 @@ With the [Aspire VS Code extension](/get-started/aspire-vscode-extension/#let-co > Use #aspireStartAppHost to start my AppHost in debug mode, then inspect the resource status. +The start tool can also select a launch profile or request isolated ports and user secrets. When the agent omits the isolation choice, linked Git worktrees start isolated automatically to avoid conflicts with the primary checkout. + The extension checks for an existing AppHost session before launching, so the agent doesn't need to start a second CLI process. These VS Code tools manage the AppHost lifecycle; they are separate from the optional runtime MCP tools that inspect its resources and telemetry. Use the Aspire CLI workflow when your agent runs outside VS Code or doesn't have access to the extension's tools. diff --git a/src/frontend/src/content/docs/get-started/aspire-skills.mdx b/src/frontend/src/content/docs/get-started/aspire-skills.mdx index 97cc405a8..87c53c35c 100644 --- a/src/frontend/src/content/docs/get-started/aspire-skills.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-skills.mdx @@ -12,7 +12,7 @@ import { Kbd } from 'starlight-kbd/components'; Aspire skills are Markdown instruction bundles for AI coding agents. Each skill lives in a folder with a `SKILL.md` file that describes when the skill applies and what workflow the agent should follow. Skills don't run services or expose application data; they teach the agent how to use Aspire tools correctly. -Aspire ships multiple skills for different parts of the app lifecycle. The exact list can vary by Aspire CLI version and project type, but the [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) bundle includes six workflow skills: `aspire`, `aspire-init`, `aspire-orchestration`, `aspire-monitoring`, `aspire-deployment`, and `aspireify`. +Aspire ships multiple skills for different parts of the app lifecycle. The exact list can vary by Aspire CLI version and project type, but the [`microsoft/aspire-skills`](https://github.com/microsoft/aspire-skills) bundle includes seven workflow skills: `aspire`, `aspire-init`, `aspire-orchestration`, `aspire-monitoring`, `aspire-deployment`, `aspire-project-v2-migration`, and `aspireify`. To configure AI coding agents end to end, see [Use AI coding @@ -243,16 +243,17 @@ In that command, `-a github-copilot` selects the target agent, `-g` installs glo ## Aspire workflow skills -| Skill | Use it for | What it teaches | -| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `aspire` | Routing Aspire tasks to the right workflow | Detect the AppHost, apply Aspire safety guardrails, and choose the appropriate workflow for the user's request | -| `aspire-init` | Starting a new Aspire app or adding Aspire to an existing repo | Choose `aspire new` or `aspire init`, create the AppHost skeleton, and hand off existing-codebase wiring to `aspireify` | -| `aspire-orchestration` | Managing the local AppHost lifecycle | Start, stop, restart, wait for, and inspect Aspire resources, including recovery from port conflicts and orphaned processes | -| `aspire-monitoring` | Observing running Aspire apps | Inspect resource state, logs, traces, metrics, browser telemetry, and dashboard data before making changes | -| `aspire-deployment` | Publishing, deploying, and tearing down Aspire apps | Use AppHost-modeled deployments for targets such as Docker Compose, Kubernetes, Azure, and AWS | -| `aspireify` | Completing Aspire initialization in an existing codebase after `aspire init` drops an AppHost skeleton | Scan the repo, propose a resource graph, wire projects and containers into the AppHost, connect resources, configure telemetry when appropriate, and validate the wiring | +| Skill | Use it for | What it teaches | +| ----------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `aspire` | Routing Aspire tasks to the right workflow | Detect the AppHost, apply Aspire safety guardrails, and choose the appropriate workflow for the user's request | +| `aspire-init` | Starting a new Aspire app or adding Aspire to an existing repo | Choose `aspire new` or `aspire init`, create the AppHost skeleton, and hand off existing-codebase wiring to `aspireify` | +| `aspire-orchestration` | Managing the local AppHost lifecycle | Start, stop, restart, wait for, and inspect Aspire resources, including recovery from port conflicts and orphaned processes | +| `aspire-monitoring` | Observing running Aspire apps | Inspect resource state, logs, traces, metrics, browser telemetry, and dashboard data before making changes | +| `aspire-deployment` | Publishing, deploying, and tearing down Aspire apps | Use AppHost-modeled deployments for targets such as Docker Compose, Kubernetes, Azure, and AWS | +| `aspire-project-v2-migration` | Migrating eligible AppHosts to Project v2 resource APIs | Assess legacy project resources, require approval for exact edits, and preserve supported behavior while migrating to `DotnetProjectResource` APIs | +| `aspireify` | Completing Aspire initialization in an existing codebase after `aspire init` drops an AppHost skeleton | Scan the repo, propose a resource graph, wire projects and containers into the AppHost, connect resources, configure telemetry when appropriate, and validate the wiring | -Use the top-level `aspire` skill when the request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, or `aspireify` for existing-codebase AppHost wiring. +Use the top-level `aspire` skill when the request is about an Aspire app and the right workflow isn't obvious. Use a workflow-specific skill directly when the task is clear, such as `aspire-orchestration` for local lifecycle work, `aspire-monitoring` for telemetry investigation, `aspire-deployment` for publish and deploy workflows, `aspire-project-v2-migration` for eligible legacy project resources, or `aspireify` for existing-codebase AppHost wiring. ## GitHub Copilot app canvas extensions @@ -307,6 +308,8 @@ Install skills to a single location for the agent environment you actively use. - SKILL.md - aspire-deployment/ - SKILL.md + - aspire-project-v2-migration/ + - SKILL.md - aspireify/ - SKILL.md - playwright-cli/ diff --git a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx index 53af34674..f7ca9a54c 100644 --- a/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-vscode-extension.mdx @@ -93,9 +93,20 @@ Open a trusted workspace with the Aspire extension installed and an AppHost visi Both tools request confirmation for the resolved target. Review its path and, for start, the requested mode before approving. These are extension-provided tools; configuring a runtime MCP server isn't required to use them. +The start tool accepts these inputs: + +| Input | Required | Description | +| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `appHostPath` | Yes | The workspace-relative path of a discovered AppHost. | +| `mode` | Yes | Use `run` to start without a debugger or `debug` to attach supported debuggers. | +| `isolated` | No | Use `true` for randomized ports and isolated user secrets or `false` to disable isolation. Linked Git worktrees use isolation when omitted. | +| `launchProfile` | No | The exact profile name from the AppHost's `launchSettings.json` file. | + The tools accept only buildable AppHosts returned by the extension's discovery service, not arbitrary filesystem paths supplied by an agent. If a selector is unknown or ambiguous, the result includes `knownAppHosts` so the agent can choose a discovered target. Multi-root workspaces use folder-qualified selectors. -Before starting, the extension checks its own sessions and running AppHosts to avoid duplicate launches. Stop coordinates the editor's matching Aspire debug session when one exists; otherwise, it uses `aspire stop --apphost` for the resolved AppHost. It doesn't mean "stop every Aspire process." +Before starting, the extension checks its own sessions and running AppHosts to avoid duplicate launches. A successful new launch reports the effective isolation setting. Results for an AppHost that was already starting or running omit that setting because the tool didn't create a new process. + +Stop coordinates the editor's matching Aspire debug session when one exists; otherwise, it uses `aspire stop --apphost` for the resolved AppHost. It doesn't mean "stop every Aspire process." :::note[Tool availability] The workspace must be trusted, and the VS Code host must support the language model tool API. If the tools aren't available, update VS Code and the Aspire extension, confirm that discovery finds your AppHost, and check that your agent chat has access to these tools.