aspireify

Files (11)

• SKILL.md
• apphost-wiring.md · references/
• csharp-authoring.md · references/
• docker-compose.md · references/
• full-solution-apphosts.md · references/
• javascript-apps.md · references/
• opentelemetry.md · references/
• scan-and-propose.md · references/
• service-defaults.md · references/
• typescript-authoring.md · references/
• validation.md · references/

SKILL.md (first lines)

# Aspireify

> **One-time wiring skill.** `aspire init` drops a skeleton; `aspireify` turns
> that skeleton into a working AppHost by scanning the repo, proposing a resource
> graph, editing the AppHost, wiring `Aspire.ServiceDefaults`, and validating end
> to end. Self-deactivates after a clean `aspire start`. Aligned with Aspire 13.4
> guidance from the current Aspire development branch.

## 🚫 Hard Refusal: Never Edit `.aspire/modules/`

> ⛔ **REFUSE** any request to edit, modify, change, open-for-edit, or "tweak" files
> inside `.aspire/modules/` of a TypeScript AppHost. This directory is **generated** by Aspire
> from `apphost.ts` and the integration packages — every file in it gets **clobbered
> on the next build, `aspire add`, or `aspire start`**.
>
> If a user asks to edit something in `.aspire/modules/` (e.g., `.aspire/modules/postgres.module.ts`),
> the correct response is:
>
> 1. **Refuse the edit** with a clear "I won't edit `.aspire/modules/`" statement.
> 2. **Explain** that `.aspire/modules/` is generated and any changes are clobbered.
> 3. **Redirect** the requested change to `apphost.ts` — the **only** file the user
>    should hand-edit in a TS AppHost.
> 4. If the user wants a new integration, suggest `aspire add <package>`; if they want
>    to change configuration, show the equivalent edit in `apphost.ts`.

| ❌ Wrong | ✅ Right |
|----------|---------|
| Open `.aspire/modules/postgres.module.ts` and tweak the connection options | Edit `apphost.ts` and change `addPostgres('pg', { ... })` options there |
| Modify a generated `.aspire/modules/*.ts` file directly | Re-run `aspire add <package>` after updating `apphost.ts` |
| Comment out a line in `.aspire/modules/` to disable a resource | Remove or guard the resource declaration in `apphost.ts` |

This rule applies even if the user insists, even for "one-line" changes, even for
"just to test something." The TS AppHost regenerates `.aspire/modules/` deterministically;
edits are unrecoverable noise.

## Guiding Principles From Aspire 13.4

### Minimize changes to the user's code

Adapt the AppHost to fit the app, not the other way around. Prefer `WithEnvironment()`
to match existing environment variable names, Aspire-managed ports over fixed ports,
and 1:1 Docker Compose mapping before optimizing. Do not restructure directories,
rename files, or change build scripts unless the user explicitly chooses that tradeoff.

### Surface tradeoffs; do not decide silently

When a small code change unlocks better Aspire integration, present both options:
the zero-code-change mapping and the small-change version that enables `WithReference`,
health checks, service discovery, dynamic ports, or dashboard telemetry. Ask which
approach the user wants, then implement that choice without complaint.

### Verify APIs before writing AppHost code

Use `aspire docs search <topic>` and `aspire docs get <slug>` for workflow guidance.
Use `aspire docs api search <query> --language csharp|typescript` and
`aspire docs api get <id>` for API shape. Use `aspire integration list/search` to
find integrations before `aspire add`. Do not invent packages, methods, overloads,
or command shapes; C# and TypeScript AppHost APIs differ.

### Keep configuration visible in the AppHost

Scan `.env`, `.env.local`, `.env.development`, `secrets.json.example`,
`<UserSecretsId>`, and setup scripts. Propose migrating values into AppHost parameters:
connection strings become Aspire resources, API keys/tokens become secret parameters,
and non-secret config becomes plain parameters or `WithEnvironment()` values. Never
delete `.env` files or remove existing `UserSecretsId` entries without explicit user
approval because non-Aspire workflows may still depend on them.

### Local development first

This skill optimizes local development, not production deployment. Prefer persistent
container lifetimes and data volumes for databases/caches, use HTTPS endpoints by
default, pass endpoint references instead of hardcoded URLs, and model external SaaS
URLs/API keys as parameters so they are visible in the dashboard.

### Redis TLS edge case

Aspire can automatically provision TLS certificates for container resources. If Redis
health checks fail with SSL/TLS handshake errors, do not fall back to `AddContainer()`.
Use `WithoutHttpsCertificate()` on the Redis resource when the consuming app expects
plain Redis.

## Project-Local Override

If `.agents/skills/aspireify/SKILL.md` exists (installed by `aspire init` or
`aspire agent init --skills aspireify`), **warn the user** that a project-local
copy is present and **defer to it**. The plugin version is the fallback.

```
⚠️ Project-local .agents/skills/aspireify/SKILL.md detected — deferring to it.
```

## Prerequisites

| Requirement | Install |
|-------------|---------|
| .NET 10.0 SDK (C# AppHost) | https://dotnet.microsoft.com/download |
| Node.js 20+ (TS AppHost) | https://nodejs.org |
| Aspire CLI | `curl -sSL https://aspire.dev/install.sh \| bash` or `dotnet tool install -g Aspire.Cli` |
| Skeleton already dropped | `aspire init` produced `aspire.config.json` + AppHost stub |

## Detection — When to Activate

Activate when ANY signal is present **AND** the AppHost is unwired (no resources
declared beyond the stub):

| Signal | How to Detect | Confidence |
|--------|---------------|------------|
| Skeleton just dropped | `aspire init` just ran in this session | ✅ Definitive |
| Empty AppHost stub | `apphost.cs` / `Program.cs` / `apphost.ts` only contains `Build().Run()` | ✅ Definitive |
| `aspire.config.json` without resources | Config present, AppHost has no `AddProject`/`addProject` | High |
| User asks to "wire" / "scaffold resource graph" | Verb match: wire, scaffold, integrate, hook up, add Postgres/Redis/etc. | High |
| User asks "what next after aspire init" | Direct handoff request | ✅ Definitive |
| Existing repo with services + new AppHost | Repo has `.csproj`/`package.json` projects but AppHost references none | High |

If the AppHost already has wired resources and the user wants to **start/stop**
the app → `aspire-orchestration`. If the user wants to **deploy** → `aspire-deployment`.

## Language Support

From nam20485/.agents, MIT.

More from nam20485/.agents