feat: Add Aspire skill and reference documentation for orchestration, CLI, agent integration, and deployment pipelines

Author: aalmada

.github/skills/aspire/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: aspire
+description: Use for any request involving Aspire orchestration, AppHost (C# or TypeScript), Aspire CLI, agent integration, MCP server, or distributed app workflows. Always trigger when the user mentions Aspire, AppHost, MCP, agent setup, distributed orchestration, or asks about multi-service, multi-language, or cloud-native .NET/TypeScript solutions—even if not named explicitly.
+---
+
+# Aspire Skill
+
+This skill enables AI coding agents to:
+- Create, manage, and orchestrate distributed applications using Aspire (C# or TypeScript AppHost)
+- Use the Aspire CLI for project creation, orchestration, logs, and resource management
+- Integrate with agent workflows (skill files, MCP server, Playwright, etc.)
+- Support both .NET and TypeScript/Node.js stacks
+
+## Reference Structure
+- [CLI Reference](./references/cli.md)
+- [Agent Integration](./references/agent.md)
+- [TypeScript AppHost](./references/typescript-apphost.md)
+- [Pipelines](./references/pipelines.md)
+- [Health Checks](./references/health-checks.md)
+- [Resource Model](./references/resource-model.md)
+- [Resource Hierarchies](./references/resource-hierarchies.md)
+- [Resource API Patterns](./references/resource-api-patterns.md)
+
+## Usage Patterns
+- Start/stop AppHost, view resource status, logs, and traces
+- Add integrations, search docs, automate workflows
+- Configure agent environments with `aspire agent init`
+
+## For More
+- See reference files above for details, commands, and examples
+- For latest docs, always consult https://aspire.dev and Microsoft Learn
+
+## Example Prompts
+- "Create a new Aspire solution with a TypeScript AppHost and set up agent integration."
+- "Show me how to start the AppHost and view logs using the Aspire CLI."
+- "How do I migrate from AGENTS.md to the new skill file for agents?"
+- "Add a Redis cache to my Aspire app and update the agent config."
+
+---
+
+For advanced CLI usage, troubleshooting, and multi-language orchestration, see the reference files in `./references/` and the official Aspire documentation.

.github/skills/aspire/references/agent.md

@@ -0,0 +1,17 @@
+# Aspire Agent Integration
+
+## Why Aspire for Agents
+- Agents get the same visibility as developers: resource data, logs, traces
+- MCP server and CLI expose all runtime info
+- Skill file (`aspire agent init`) teaches agents CLI patterns and workflows
+- Agent-native CLI: All commands are non-interactive, support `--format Json`, and are designed for automation and agent workflows
+- **Detached mode (`--detach`)**: Agents (and users) can run the AppHost in the background using `aspire run --detach` or `aspire start`. This frees up the terminal and enables parallel, non-blocking workflows. Use `aspire ps` to list running apphosts and `aspire stop` to terminate them. Detached mode is ideal for agent-driven automation, CI, and multi-app scenarios.
+- Agents can also use isolated mode (`--isolated`) for parallel, conflict-free runs, and wait for resource health.
+
+## MCP Setup
+1. Run `aspire agent init` in your project directory
+2. Select:
+   - Aspire skill file (recommended)
+   - Playwright CLI (for browser automation)
+   - Aspire MCP server (for runtime access)
+3. Use `aspire agent mcp` to start the MCP server for agent communication

.github/skills/aspire/references/cli.md

@@ -0,0 +1,34 @@
+# Aspire CLI Reference
+
+## Installation & Upgrade
+- Install: `curl -sSL https://aspire.dev/install.sh | bash`
+- Upgrade: `aspire update --self`
+- Validate: `aspire --version`
+- Docs: https://aspire.dev/get-started/install-cli/
+
+## Key CLI Enhancements (13.2+)
+- **Language-aware templates:** `aspire new` and `aspire init` support C#, TypeScript, Python, and multi-language setups.
+- **Detached/background mode:** `aspire run --detach` or `aspire start` runs the AppHost in the background. Use `aspire ps` to list, `aspire stop` to stop.
+- **Isolated mode:** `--isolated` flag runs parallel apphosts with isolated ports/secrets for agent/CI/test workflows.
+- **Resource commands:** Unified `aspire resource <name> <command>` (start/stop/restart/rebuild) for fine-grained control.
+- **Resource monitoring:** `aspire describe` and `aspire describe --follow` stream resource state and config.
+- **Environment diagnostics:** `aspire doctor` checks certs, containers, SDKs, agent config, and more.
+- **Fuzzy search for integrations:** `aspire add` supports fuzzy search for packages.
+- **Secrets/certs management:** `aspire certs` and `aspire secret` for dev certs and user secrets (no .NET CLI needed).
+- **Wait/export:** `aspire wait` blocks until resource is healthy; `aspire export` captures telemetry and config.
+- **Agent integration:** `aspire agent init` sets up agent skill files and MCP; `aspire agent mcp` starts the MCP server.
+- **Docs from CLI:** `aspire docs list|search|get` brings official docs into the terminal (supports `--format Json`).
+- **Unified config:** `aspire.config.json` replaces legacy config files; auto-migrates on first run.
+- **Option standardization:** `-v` for version, `--format` for output, `--log-level`/`-l` for log filtering.
+- **Other:** `aspire run --no-build`, improved JSON output, better error/logging, and multi-language support.
+
+## Agent-Friendly Features
+- All commands support `--format Json` for structured output
+- Non-interactive and automation-ready
+- CLI exposes all dashboard/apphost data for scripts, editors, and agents
+- See: https://aspire.dev/get-started/ai-coding-agents/
+
+## More
+- Full CLI docs: https://aspire.dev/reference/cli/overview/
+- Troubleshooting: https://aspire.dev/get-started/troubleshooting/
+- What's new: https://aspire.dev/whats-new/aspire-13-2/#%EF%B8%8F-cli-enhancements

.github/skills/aspire/references/health-checks.md

@@ -0,0 +1,11 @@
+# Aspire Health Checks Reference
+
+See the official documentation for full details: [Aspire Health Checks](https://aspire.dev/fundamentals/health-checks/)
+
+Health checks in Aspire provide observability into the health and readiness of application resources. They enable proactive monitoring and automated recovery.
+
+- Configure health checks for services, databases, and external dependencies.
+- Integrate health checks with orchestration and deployment pipelines.
+- Use health check endpoints for liveness and readiness probes.
+
+For configuration options and patterns, refer to the official docs above.

.github/skills/aspire/references/pipelines.md

@@ -0,0 +1,98 @@
+# Aspire Pipelines Reference
+
+## Overview
+Aspire uses a pipeline-based deployment system that enables extensible, composable deployment workflows. Pipelines break deployment into discrete, well-defined steps that can be optimized for performance and reliability while maintaining clear visibility into the deployment process.
+
+### Why pipelines matter
+- **Intelligent concurrency:** Independent operations run in parallel, maximizing resource utilization and minimizing total deployment time.
+- **Granular control:** Each step can be executed, monitored, and retried independently with specific error reporting and targeted recovery capabilities.
+- **Smart dependency management:** Steps wait only for their actual dependencies, ensuring optimal execution order while maintaining correctness.
+- **Comprehensive observability:** Real-time progress reporting at both step and sub-task levels provides clear visibility into deployment operations.
+- **Flexible execution:** Run complete deployments or selective step execution based on your specific needs.
+
+### Core capabilities
+- **Extend deployments:** Add custom deployment steps for specific resources or scenarios.
+- **Control execution order:** Declare dependencies between steps to ensure proper sequencing.
+- **Run selective steps:** Execute only specific steps and their dependencies for faster iterations.
+- **Parallelize operations:** Independent steps can run concurrently for improved performance.
+- **State persistence:** Cache deployment state and parameters across multiple deployment runs.
+- **Intelligent granularity:** Balance between fine-grained control and deployment efficiency.
+
+## Core Concepts
+
+### Pipeline Steps
+A pipeline step represents a discrete unit of work in the application pipeline. Each step encapsulates a specific aspect of the deployment process, making the overall operation more manageable and debuggable.
+
+Each step has:
+- **Name:** A unique identifier for the step
+- **Action:** The work to be performed during deployment
+- **Dependencies:** Other steps that must complete before this step runs
+- **Resource context:** Access to the application’s resource model and configuration
+
+#### Example pipeline steps
+**Infrastructure steps (can run in parallel):**
+- `provision-cosmosdb`: Provision the CosmosDB database
+- `provision-storage`: Provision Azure Storage account
+- `provision-aca-env`: Provision Azure Container Apps environment
+- `provision-container-registry`: Set up the container image registry
+
+**Build steps (can run in parallel):**
+- `build-apiservice`: Build container image for the API service
+- `build-webfrontend`: Build container image for the frontend
+
+**Deployment steps (depend on builds and infrastructure):**
+- `push-apiservice`: Push API service image to registry
+- `push-webfrontend`: Push frontend image to registry
+- `deploy-apiservice`: Deploy API service to compute platform
+- `deploy-webfrontend`: Deploy frontend to compute platform
+
+### Step Execution Phases
+The pipeline system operates through three distinct phases:
+1. **Registration phase:** Steps are collected from resource annotations and pipeline API calls.
+2. **Resolution phase:** The system validates dependencies, calculates execution order, and identifies concurrency opportunities.
+3. **Execution phase:** Steps run according to the resolved plan, with parallel execution, dependency waiting, progress reporting, and error isolation.
+
+### Dependency Management
+Dependencies in Aspire pipelines are explicit and purpose-driven. Steps declare their relationships using:
+- `PipelineStep.DependsOn`: This step must run after another step completes successfully
+- `PipelineStep.RequiredBy`: Another step must run after this step (inverse dependency declaration)
+
+The pipeline system validates dependencies to ensure:
+- No circular dependencies
+- All references exist
+- Logical consistency
+
+### Optimal Granularity Design
+Resource-level granularity: Each infrastructure resource is provisioned as a separate step, enabling precise error reporting, targeted retry, progress transparency, and flexible recovery.
+Operation-level organization: Related operations are grouped logically while maintaining independence (e.g., build, push, deploy).
+
+## Well-known Steps
+
+### Entry Point Steps
+- `WellKnownSteps.Deploy`: Orchestrates the complete deployment process.
+- `WellKnownSteps.Publish`: Generates deployment artifacts without executing the actual deployment.
+- `WellKnownSteps.Build`: Builds container images for compute resources.
+- `WellKnownSteps.Push`: Pushes container images to registries.
+
+### Prerequisite Steps
+- `WellKnownSteps.BuildPrereq`: Pre-requisites for building (dependency resolution, environment setup).
+- `WellKnownSteps.DeployPrereqs`: Pre-requisites for deployment (authentication, environment validation).
+- `WellKnownSteps.PublishPrereqs`: Pre-requisites for publishing (build environment setup).
+- `WellKnownSteps.PushPrereq`: Pre-requisites for pushing images (registry authentication).
+
+### Resource-contributed Steps
+Resources can contribute their own pipeline steps through annotations. For example, a static site resource might contribute steps for building, configuring storage permissions, uploading files, and configuring a CDN.
+
+### Application-specific Steps
+Applications can add custom steps directly through the pipeline API for scenarios like database migrations, smoke tests, configuration updates, and notification workflows.
+
+## Execution Control
+
+### Running Specific Steps
+The `aspire do` command allows you to execute individual steps and their dependencies, providing fine-grained control over the deployment process. Use cases include incremental deployments, troubleshooting, development workflows, and selective operations.
+
+### Parallel Execution and Performance Optimization
+The pipeline system maximizes deployment performance through intelligent parallel execution, resource grouping, critical path optimization, and resource-aware scheduling. It provides robust failure handling, error isolation, and comprehensive logging for efficient debugging and recovery.
+
+---
+For more, see the official Aspire documentation for pipelines.

.github/skills/aspire/references/resource-api-patterns.md

@@ -0,0 +1,11 @@
+# Aspire Resource API Patterns Reference
+
+See the official documentation for full details: [Aspire Resource API Patterns](https://aspire.dev/architecture/resource-api-patterns/)
+
+Resource API patterns in Aspire guide the design and implementation of APIs for resources managed by the orchestration platform.
+
+- Standardizes resource interaction and management.
+- Promotes consistency and reusability across services.
+- Supports automation and integration with external systems.
+
+For design patterns and implementation details, refer to the official docs above.

.github/skills/aspire/references/resource-hierarchies.md

@@ -0,0 +1,11 @@
+# Aspire Resource Hierarchies Reference
+
+See the official documentation for full details: [Aspire Resource Hierarchies](https://aspire.dev/architecture/resource-hierarchies/)
+
+Resource hierarchies in Aspire describe the relationships and dependencies between resources in a distributed application.
+
+- Parent-child relationships define orchestration and lifecycle.
+- Enables dependency management and startup ordering.
+- Supports grouping and logical organization of resources.
+
+For patterns and best practices, refer to the official docs above.

.github/skills/aspire/references/resource-model.md

@@ -0,0 +1,11 @@
+# Aspire Resource Model Reference
+
+See the official documentation for full details: [Aspire Resource Model](https://aspire.dev/architecture/resource-model/)
+
+The Aspire resource model defines how application components and infrastructure are represented, managed, and orchestrated.
+
+- Resources represent services, databases, caches, and other components.
+- Resources can be composed, configured, and orchestrated declaratively.
+- Supports extensibility for custom resource types.
+
+For modeling guidance and examples, refer to the official docs above.

.github/skills/aspire/references/typescript-apphost.md

@@ -0,0 +1,59 @@
+
+# Aspire AppHost: C# and TypeScript
+
+Aspire supports both **C#** and **TypeScript** AppHosts for orchestrating distributed applications. Both are first-class options—choose based on your stack:
+
+- **C# AppHost**: For .NET/C#-centric solutions
+- **TypeScript AppHost**: For Node.js/React/JS-centric solutions
+
+See official docs:
+- [C# AppHost Quickstart](https://aspire.dev/get-started/first-app/)
+- [TypeScript AppHost Quickstart](https://aspire.dev/get-started/first-app-typescript-apphost/)
+
+---
+
+## Create a New Aspire App
+
+| Language     | Command Example                                                                 |
+|--------------|---------------------------------------------------------------------------------|
+| **C#**       | `aspire new aspire-starter -n aspire-app -o aspire-app`                         |
+| **TypeScript** | `aspire new aspire-ts-starter -n aspire-app -o aspire-app`                      |
+
+Both commands prompt to configure AI agent environments (select 'y'). Each generates a solution with API, frontend, and AppHost in the respective language.
+
+---
+
+## AppHost Example
+
+### C#
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+var api = builder.AddProject("api", "./api/Api.csproj").WithHttpEndpoint(env: "PORT");
+var frontend = builder.AddProject("frontend", "./frontend/Frontend.csproj").WithReference(api).WaitFor(api);
+builder.Build().Run();
+```
+
+### TypeScript
+```typescript
+import { createBuilder } from './.modules/aspire.js';
+const builder = await createBuilder();
+const app = await builder.addNodeApp("app", "./api", "src/index.ts").withHttpEndpoint({ env: "PORT" }).withExternalHttpEndpoints();
+const frontend = await builder.addViteApp("frontend", "./frontend").withReference(app).waitFor(app);
+await app.publishWithContainerFiles(frontend, "./static");
+await builder.build().run();
+```
+
+---
+
+## Run the App
+
+```bash
+cd ./aspire-app
+aspire run
+# Dashboard URL appears in terminal
+```
+
+---
+
+**Note:** Aspire treats C# and TypeScript AppHosts as equal options. Use the one that best fits your technology stack.
+