Kinded YAML apply (`stackgen ai apply`)

Create and update Aiden Agent, Workflow, Runbook, Skill, and Policy resources from kubectl-style YAML — without writing Terraform for the fast path.

CLI floor: stackgen-beta ≥ v0.82.0-rc.1 (command group stackgen ai). Product name is Aiden; wire apiVersion stays guild.stackgen.com/v1.

This is Adopt Path 4. For OpenTofu module demos see Path 1; for production roots prefer Path 3 (aios-* modules).

Why

Terraform is the durable controller for customer tenants. Scenario authors and operators still need a fast loop to stand up a small Agent + Workflow + Skill pack for demos and local bring-up. Kinded YAML + stackgen ai apply fills that gap the way kubectl apply does for Kubernetes objects.

Envelope

Every document must include:

apiVersion: guild.stackgen.com/v1
kind: Agent | Workflow | Runbook | Skill | Policy
metadata:
  name: my-resource
  domain: product          # required for Workflow
  tags: []
  approve: true            # Workflow / Runbook only
spec: {}

Multi-doc files use Kubernetes-style --- separators (optional # comment). Directories load *.yaml / *.yml. Apply order: Policy → Agent → Runbook → Skill → Workflow.

Upstream CLI reference: stackgen-cli docs/ai-apply.md.

Editor support (VS Code / Cursor)

Install the YAML extension (redhat.vscode-yaml). Then point it at the kinded-manifest schema so kind: and spec: validate and autocomplete instead of matching unrelated SchemaStore entries (for example CrowdSec scenario configs under examples/scenarios/*/*.yaml).

Schema file in this repo: docs/schemas/guild-kinded-manifest.schema.json — use a relative path from your manifest so validation works immediately after clone (no network).

Published URL (for repos outside this clone, after GitHub Pages deploy): guild-kinded-manifest.schema.json

Per-file modeline (travels with the manifest in git; adjust ../ depth to reach docs/schemas/):

# yaml-language-server: $schema=../../../docs/schemas/guild-kinded-manifest.schema.json
apiVersion: guild.stackgen.com/v1
kind: Agent
...

Workspace settings — this repo ships .vscode/settings.json with a relative schema path. For your own scenario repo, paste:

{
  "yaml.schemas": {
    "./docs/schemas/guild-kinded-manifest.schema.json": [
      "examples/**/manifests/*.yaml",
      "examples/scenarios/*/*.yaml"
    ]
  }
}

Copy docs/schemas/guild-kinded-manifest.schema.json into your repo, or reference the published URL instead of the relative path if you prefer a remote schema.

Exclude values*.yaml from schema mapping — those are plain values files, not kinded manifests.

Templated manifests: files with Go text/template directives (,) are not valid YAML until stackgen ai apply --values … renders them. Use --dry-run for the honest validation gate; expect template-syntax noise from the YAML language server on those files.

Commands

stackgen ai apply -f <file|dir> [--approve] [--dry-run] [-R]
stackgen ai get    kind/name | -f <file>
stackgen ai delete kind/name | -f <file>
stackgen ai list   agent|workflow|runbook|skill|policy
stackgen ai run    workflow/<name> --input 'key=value'

--dry-run validates and normalizes only (no Aiden API calls).

Dual controllers

Terraform (sg_agent, sg_workflow, …) and stackgen ai apply target the same Aiden names. Pick one controller per resource name to avoid last-writer-wins thrash.

Examples in this repo

Example	What it shows
Product idea → requirements + market fit	Two agents, movie+plain skill (pirate skill kept for swap exercise), tandem workflow

Scenario tree: examples/scenarios/product-idea-ai-apply/.

Kinded YAML apply (stackgen ai apply)