aspire-init

# Aspire Init > **First-run only.** This skill owns the skeleton drop and template choice for repositories > that do not yet have an Aspire AppHost. Once the skeleton is in place, hand off to > [`aspireify`](../aspireify/SKILL.md) for the actual resource wiring. ## Prerequisites | Requirement | Install | |-------------|---------| | .NET 10.0 SDK | https://dotnet.microsoft.com/download | | Aspire CLI (curl installer) | `curl -sSL https://aspire.dev/install.sh \| bash` | | Aspire CLI (NativeAOT global tool) | `dotnet tool install -g Aspire.Cli` (.NET 10 required) | | Diagnose missing prerequisites | `aspire doctor` | > Aspire ships the CLI as a NativeAOT .NET global tool — instant startup, no JIT warmup. > The curl/PowerShell installer remains supported for environments without .NET 10. ## Detection Activate **only** when adding Aspire to a workspace that does not yet have one. Confirm ALL of the following before running `aspire init`: | Signal | How to Detect | Meaning | |--------|---------------|---------| | No C# AppHost | No `.csproj` containing `Aspire.AppHost.Sdk` | OK to init | | No file-based AppHost | No `apphost.cs` with `#:sdk Aspire.AppHost.Sdk` | OK to init | | No TypeScript AppHost | No `apphost.ts` in repo root | OK to init | | No Aspire config | No `aspire.config.json` in repo root | OK to init | | User intent | Explicit "add Aspire", "scaffold Aspire", "aspire init" | OK to init | If **any** AppHost signal is already present, **do not run `aspire init`**. Route to [`aspireify`](../aspireify/SKILL.md) (re-wire) or [`aspire-orchestration`](../aspire-orchestration/SKILL.md) (lifecycle). ## Decision: `aspire new` vs `aspire init` | Situation | Command | Why | |-----------|---------|-----| | Empty directory or brand-new project | `aspire new <template>` | Generates a full starter solution | | Existing repo with services to model | `aspire init` | Drops minimal skeleton + `aspire.config.json` next to existing code | | User wants a sample to learn from | `aspire new aspire-starter` | Includes ApiService + Web + ServiceDefaults | | User wants the smallest possible scaffold | `aspire new aspire-empty` (C#) or `aspire new aspire-ts-empty` (TS) | No resources pre-wired | | User wants Python services | `aspire new aspire-py-starter` (TypeScript AppHost drives Python) | **Not** `dotnet new` — that template was removed in 13.3 | See [references/templates.md](references/templates.md) for the complete template list and options. ## Workflow A — `aspire new <template>` (new project) For brand-new projects in an empty or non-existent directory: 1. Confirm prerequisites with `aspire doctor` if the CLI install is uncertain. 2. Pick a template from [references/templates.md](references/templates.md). 3. Run the template, append `--non-interactive` for agent flows: ```bash aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive ``` 4. The new directory is fully wired by the template — **no aspireify handoff needed**. 5. Route to [`aspire-orchestration`](../aspire-orchestration/SKILL.md) for first run (`aspire start`). ## Workflow B — `aspire init` (existing repo) For repositories that already contain services (Express API, .NET API, Python service, etc.) and need an AppHost added alongside them: 1. Verify the [Detection](#detection) table — confirm **no** AppHost is present. 2. Run `aspire init`, choosing language explicitly for non-interactive flows: ```bash aspire init --language csharp --non-interactive # or aspire init --language typescript --non-interactive ``` 3. `aspire init` drops: - The AppHost skeleton (`apphost.cs` with `#:sdk` directives, **or** `apphost.ts` with the generated `.aspire/modules/` folder) - AppHost configuration describing language + AppHost path - The **`aspireify`** agent skill into the project's skill directory (same one `aspire agent init` uses) 4. **Hand off to `aspireify`** — `aspire init` does **not** wire resources, projects, or integrations on its own. 5. After `aspireify` finishes wiring, validate via `aspire start` ([`aspire-orchestration`](../aspire-orchestration/SKILL.md)). See [references/init-workflow.md](references/init-workflow.md) for the full sequence including what `aspire.config.json` contains and what to do if `aspire init` fails partway. ## Handoff Rules | After `aspire init` / `aspire new` finishes... | Route To | |------------------------------------------------|----------| | Skeleton dropped, resources need wiring | → `aspireify` skill (in-plugin or project-local) | | Skeleton dropped, validate it starts | → `aspire-orchestration` (run `aspire start`) | | New project from template, ready to run | → `aspire-orchestration` | | User asks to deploy after init | → `aspire-deployment` | | User asks for logs/traces after init | → `aspire-monitoring` | | Existing AppHost detected — do NOT run init | → `aspireify` (re-wire) or `aspire-orchestration` (lifecycle) | ## Project-Local Skill Override If `.agents/skills/aspire-init/SKILL.md` exists project-locally (legacy install from an older `aspire init` run), **warn the user and defer to it**. The legacy project-local skill may carry repo-specific guidance that should not be overridden by this in-plugin skill. The project-local `aspireify` skill (installed by `aspire init`) takes precedence over this plugin's in-plugin `aspireify` for the same reason — defer to the project-local copy and warn. ## Error Handling | Symptom | Cause | Action | |---------|-------|--------| | `aspire init` reports AppHost already exists | Repo already has an AppHost | Stop. Route to `aspireify` (re-wire) or `aspire-orchestration` (lifecycle) | | `aspire init` fails in non-interactive mode without `--language` | Multiple language paths available | Re-run with `--language csharp` or `--language typescript` | | `aspire new` rejects `--output` path | Path exists and is non-empty | Use a different `--output` or empty the directory | | `aspire` command not found | CLI not installed | `dotnet tool install -g Aspire.Cli` (.NET 10) or `curl -sSL https://aspire.dev/install.sh \| bash` | | `aspire doctor` reports missing .NET 10 | SDK missing | Install .NET 10 SDK before retrying | | `aspire init` succeeded but no `aspireify` skill installed | Agent skill directory not detected | Run `aspire agent init` to install `aspireify`, then continue wiring | | Skeleton dropped but resources not wired | Expected — `aspire init` does not wire | Hand off to `aspireify` | ## References - [templates.md](references/templates.md) — `aspire new` templates and options - [init-workflow.md](references/init-workflow.md) — `aspire init` flow, `aspire.config.json` layout, and `aspireify` handoff