brianj/silver-octo-spoon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added A-Frame Architecture Sample.

Browse Source
This commit is contained in:
brianj
2026-06-08 20:19:41 +02:00
parent b2d7e7e26b
commit 6760f90336
63 changed files with 5075 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AFrameArchitectureSample/.agents/skills/aspire-init/SKILL.md
+146
View File
@@ -0,0 +1,146 @@
---
name: aspire-init
description: >-
**WORKFLOW SKILL** - First-run flow for adding Aspire to a repo. Picks `aspire new`
(greenfield) or `aspire init` (existing repo), drops the AppHost skeleton, then hands
off to `aspireify` for resource wiring.
USE FOR: aspire init, aspire new, aspire-starter, aspire-ts-starter, aspire-py-starter,
add Aspire to existing repo, scaffold Aspire app, bootstrap Aspire, no AppHost detected,
install aspireify, generated .aspire/modules.
DO NOT USE FOR: AppHost wiring on an existing AppHost (use aspireify), start/stop/wait
(use aspire-orchestration), deploy/publish (use aspire-deployment), logs/traces (use
aspire-monitoring), repo that already has an AppHost.
INVOKES: aspire CLI (init, new, doctor), aspireify (handoff after skeleton drop).
FOR SINGLE OPERATIONS: Run `aspire init` or `aspire new TEMPLATE` directly.
license: MIT
metadata:
author: Microsoft
version: "0.0.1"
---
# 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
AFrameArchitectureSample/.agents/skills/aspire-init/references/init-workflow.md
+123
View File
@@ -0,0 +1,123 @@
# `aspire init` Workflow
Reference for the `aspire init` flow on existing repositories. Source:
https://aspire.dev/reference/cli/commands/aspire-init/.
## What `aspire init` Does
`aspire init` initializes Aspire support in an existing repo or workspace. It scaffolds a
**minimal AppHost skeleton** plus an `aspire.config.json`, then optionally installs the
**`aspireify`** agent skill so the AI coding agent can complete the wiring.
It does **not**:
- Wire resources, projects, or integrations into the AppHost
- Modify existing project files
- Change the repo's .NET SDK version (`global.json` is left alone)
- Trust the developer certificate (run `aspire certs trust` separately if needed)
## Command and Options
```bash
aspire init [options]
```
| Option | Purpose |
|--------|---------|
| `--language` | `csharp` or `typescript`. Required in `--non-interactive` mode if both paths are available |
| `--channel` | `stable` (default), `staging`, `daily` |
| `--non-interactive` | **Required for agent execution.** Disables prompts and spinners |
| `--nologo` | Suppress startup banner / telemetry notice |
| `--banner` | Show the animated welcome banner |
| `-l, --log-level` | `Critical`, `Debug`, `Error`, `Information`, `None`, `Trace`, `Warning` |
| `--wait-for-debugger` | Pause until a debugger attaches |
| `-?, -h, --help` | Print help |
## What Gets Dropped
### C# Path (`--language csharp`)
- **`apphost.cs`** — single-file AppHost using `#:sdk Aspire.AppHost.Sdk` and `#:package`
directives. No `.csproj` is created in the file-based mode.
- **`aspire.config.json`** at repo root.
### TypeScript Path (`--language typescript`)
- **`apphost.ts`** at repo root.
- **`.aspire/modules/`** generated folder (do not edit by hand — regenerate with `aspire add`).
- **`aspire.config.json`** at repo root.
### `aspireify` Skill
- A Markdown skill file is installed into the AI agent's skill directory — the same
directory chosen by `aspire agent init` (e.g., `.agents/skills/aspireify/`,
`.github/skills/aspireify/`, `.claude/skills/aspireify/`, or `.opencode/skill/aspireify/`).
- The skill instructs the agent to scan the repo, propose a resource graph, edit the
AppHost, and validate via `aspire start`.
## `aspire.config.json` Layout
| Field | Values | Meaning |
|-------|--------|---------|
| `appHost.language` | `"csharp"` or `"typescript/nodejs"` | Which AppHost syntax to use |
| `appHost.path` | Path to AppHost file or directory | Where the AppHost lives |
C# has two sub-modes the agent may encounter:
- **Single-file** — `appHost.path` points at `apphost.cs` (uses `#:sdk` directive).
- **Full project** — `appHost.path` points at a directory containing a `.csproj` plus
`Program.cs`. In solution-backed repos, full project mode lets the AppHost participate in IDE and solution workflows.
## End-to-End Sequence
1. **Pre-flight** — verify no AppHost already exists. If one does, stop and route to
`aspireify` or `aspire-orchestration`.
2. **Run init**:
```bash
aspire init --language <csharp|typescript> --non-interactive
```
3. **Confirm artifacts** — `apphost.cs` (or `apphost.ts` + `.aspire/modules/`) and
`aspire.config.json` should be in the repo root.
4. **Confirm `aspireify` skill installed** — the agent's skill directory contains
`aspireify/SKILL.md`. If missing, run `aspire agent init` to install it.
5. **Hand off to `aspireify`** for wiring:
- Scan repo and discover existing projects, services, containers
- Ask the user clarifying questions (which services to orchestrate, hardcoded ports,
whether to map env vars or switch to Aspire service discovery)
- Wire resources with `WithReference`, `WaitFor`, endpoints, volumes
- Optionally configure OpenTelemetry
- Validate with a smoke-test `aspire start`
6. **Validate** — once `aspireify` finishes wiring, run `aspire start` (handled by
`aspire-orchestration`) and confirm resources reach a healthy state.
## Project-Local Skill Precedence
`aspire init` installs `aspireify` into the project's skill directory when an agent skill location is detected.
When a project-local `.agents/skills/aspireify/SKILL.md` (or equivalent location) is
present, **defer to it and warn the user** — the project-local copy may carry repo-specific
guidance.
The same precedence applies to a legacy `.agents/skills/aspire-init/SKILL.md` from older
`aspire init` runs: warn and defer.
## Failure Modes and Recovery
| Symptom | Cause | Recovery |
|---------|-------|----------|
| `aspire init` reports an AppHost already exists | Repo is already an Aspire app | Stop. Route to `aspireify` or `aspire-orchestration` |
| `aspire init` fails without `--language` in `--non-interactive` | CLI needs the language explicitly when prompts are disabled | Re-run with `--language csharp` or `--language typescript` |
| Skeleton dropped but no `aspireify` skill | Agent skill directory not detected during init | Run `aspire agent init` to install `aspireify`, then continue |
| `apphost.cs` references a missing `#:package` | Channel mismatch or transient feed issue | Re-run with `--channel stable` (or `daily` for pre-release) |
| `aspire start` after wiring fails immediately | Wiring incomplete or wrong AppHost path | Re-invoke `aspireify`; confirm `aspire.config.json` `appHost.path` is correct |
## Don't Do This
- **Don't run `aspire init` if any AppHost signal already exists** — it duplicates the
skeleton and confuses subsequent tooling.
- **Don't edit `.aspire/modules/`** in TypeScript AppHosts. Use `aspire add` to regenerate APIs;
use `aspire restore` if files are missing.
- **Don't install the obsolete Aspire workload** (`dotnet workload install aspire`). Use
`aspire init`, `aspire new`, or `aspire add` instead.
- **Don't perform the resource wiring inside this skill.** Hand off to `aspireify`. This
skill's job ends when the skeleton + `aspire.config.json` + `aspireify` skill are in
place.
AFrameArchitectureSample/.agents/skills/aspire-init/references/templates.md
+92
View File
@@ -0,0 +1,92 @@
# `aspire new` Templates
Reference for choosing and invoking templates with `aspire new`. Source:
https://aspire.dev/reference/cli/commands/aspire-new/
## Template List
| Template | Description | AppHost Language |
|----------|-------------|------------------|
| `aspire-starter` | Starter App (ASP.NET Core / Blazor) | C# |
| `aspire-ts-cs-starter` | Starter App (ASP.NET Core / React) | C# |
| `aspire-py-starter` | Starter App (FastAPI / React) | **TypeScript** (drives Python) |
| `aspire-ts-starter` | Starter App (Express / React) | TypeScript |
| `aspire-empty` | Minimal scaffold, no resources pre-wired | C# |
| `aspire-ts-empty` | Minimal scaffold, no resources pre-wired | TypeScript |
> **Important — Python starter changed in 13.3.** `dotnet new aspire-py-starter` was removed.
> The current path is `aspire new aspire-py-starter`, and the AppHost is **TypeScript**, not
> C#. The TypeScript AppHost orchestrates the FastAPI service plus the React frontend.
## Common Options
| Option | Purpose |
|--------|---------|
| `-n, --name` | Name of the project to create |
| `-o, --output` | Output path. Defaults to `./<template-name>` (auto-suffixed if non-empty) |
| `-s, --source` | NuGet source for the project templates |
| `-v, --version` | Version of the project templates to use |
| `--channel` | Template channel: `stable` (default), `staging`, `daily` |
| `--non-interactive` | **Required for agent execution.** Disables prompts and spinners |
| `--nologo` | Suppress startup banner / telemetry notice |
| `--suppress-agent-init` | Skip the post-create prompt to configure AI agent environments |
| `-l, --log-level` | `Critical`, `Debug`, `Error`, `Information`, `None`, `Trace`, `Warning` |
## Template-Specific Options
### `aspire-py-starter`
| Option | Values | Default |
|--------|--------|---------|
| `--use-redis-cache` | `true` / `false` | Prompts interactively |
```bash
aspire new aspire-py-starter --use-redis-cache true --non-interactive
```
## Interactive Prompts (avoid by passing flags)
| Prompt | What It Decides | Skip With |
|--------|------------------|-----------|
| Project name | Output directory name | `--name <value>` |
| Template version | Which release to use | `--version <value>` |
| Output folder | Where files land | `--output <value>` |
| Use `*.dev.localhost` URLs? | HTTPS subdomain launch profile vs `http://localhost:<port>` | Pass `--non-interactive` to take the default (No, standard localhost) |
If a project picks `*.dev.localhost`, the user must trust the developer certificate first:
```bash
aspire certs trust
```
## Output Path Validation
- Invalid characters (e.g., null bytes) are rejected with an error.
- Existing **non-empty** directories are rejected — pick a new `--output` or empty the target.
- When `--output` is omitted, the CLI derives the directory from the template name and
appends a numeric suffix (`./aspire-starter-2`, `./aspire-starter-3`, ...) if the default
already exists.
## Examples
```bash
# Interactive — CLI prompts for name, output, version
aspire new aspire-starter
# Non-interactive C# empty scaffold pinned to a specific version
aspire new aspire-empty --version <version> --name aspireapp --output ./dev --non-interactive
# Pre-release templates from the daily channel
aspire new aspire-starter --channel daily
# TypeScript-AppHost-driven Python starter with Redis cache
aspire new aspire-py-starter --use-redis-cache true --name py-shop --output ./py-shop --non-interactive
```
## When `aspire new` Is Wrong
| Situation | Use Instead |
|-----------|-------------|
| Repo already contains services to model | `aspire init` (Workflow B in [SKILL.md](../SKILL.md)) |
| AppHost already exists in the repo | `aspireify` (re-wire) or `aspire-orchestration` (lifecycle) |
| Need to add an integration to an existing AppHost | `aspire add <package>` (handled by `aspire-orchestration`) |