Adopt the solutions repo

This page is the single entry point for solutions engineers adopting this repository. Pick one path below and follow the numbered steps — you do not need to read everything on the site first.

New here? Gather credentials: Prerequisites. Unfamiliar terms: Glossary.

Should I use this repo at all?

Situation Use this repo? Why
Pre-sales demo: you have 15–30 min on Zoom and need a working Aiden in front of a prospect. Yes — run a scenario One make demo SCENARIO=… gets you to “first agent reply” faster than clicking through the UI.
Fast Agent/Workflow/Skill without Terraform: kubectl-style YAML apply. Yes — Path 4 Kinded YAML apply with stackgen-beta ≥ v0.82.0-rc.1.
PoC handoff: you configured a tenant in the UI and the customer wants it in code. Yes — capture it Use aios-export to snapshot the tenant to HCL the customer can own.
Multi-env rollout: the customer wants dev / staging / prod tenants from the same baseline. Yes — clone the scenario Each scenario is parameterized by stackgen_url / stackgen_token; same root, different terraform.tfvars.
Discovery call, no Aiden yet: the prospect wants to see what an “agent” even is. No — open Aiden OS UI Modules add latency you do not need. Come back here once they nod at the concept.
Internal eng explaining the platform to another eng team. Maybe — link Architecture The diagram doc is faster than reading 15 module READMEs.

Path 1 — Demo Aiden today (pre-sales)

Best when: you have a prospect on Zoom and need a working agent in under 30 minutes.

  1. Check credentials — run make demo-doctor from the repo root. It reports missing StackGen URL/token, LLM keys, or integration secrets before the prospect sees a stack trace.
  2. Pick a scenario — open the SE Playbook prospect-question table, or browse the scenario index.
  3. Run the demo — make demo SCENARIO=<name> (wrapper over tofu init && apply in examples/scenarios/<name>/).
  4. Walk the talk track — each scenario README has a Talk track section (5 bullets). Open the Aiden URL from tofu output.
  5. Reset between calls — make demo-reset SCENARIO=<name> so the next prospect starts clean.

Full stack fallback: if the prospect needs every integration wired, point at examples/complete/ — but lead with a single scenario first.

Path 2 — Capture a UI-clicked tenant (PoC handoff)

Best when: you or the customer configured agents in the Aiden OS UI and now need version-controlled Terraform.

  1. Export the tenant — follow aios-export (tools/aios-export/export.sh with STACKGEN_URL and STACKGEN_TOKEN).
  2. Review outputs — out/tenant-snapshot.json (diff-friendly), out/tenant.tf (raw sg_* HCL), out/import.sh (import commands).
  3. Create a customer root — copy tenant.tf, add provider.tf, run tofu init.
  4. Import existing resources — bash out/import.sh, then tofu plan.
  5. Hand-merge gaps — Phase 1 does not export integrations, policies, schedules, secrets, or webhooks. Add those from module READMEs or keep them in the UI until Phase 2 capture ships.
  6. Optional module rewrite — compare out/tenant.modules.tf (Phase 2 pattern-matching) against raw tenant.tf and commit whichever representation the customer prefers.

Path 3 — Compose modules in your own Terraform root

Best when: you are building or extending a customer stack from aios-* modules (not clicking through the UI).

New to Agent as Code? Start with the progressive tutorial Agent as Code — Zero to Hero (basic Terraform assumed). Then return here for module composition.

  1. Prerequisites — credentials checklist (StackGen PAT, provider registry token, LLM keys).
  2. Minimal pattern — Onboarding step 4: foundation → policies → agent, with provider "sg" in your root.
  3. Plan and apply — tofu init, tofu plan, tofu apply; verify agents appear in the Aiden OS UI.
  4. Pick modules by customer shape — Use-case catalog or Module Catalog.
  5. Full reference — examples/complete/ wires every layer; CI validates it via make validate.

Contributor path: if you are changing modules in this repo, continue with Onboarding steps 2–5 for local CI parity.

Path 4 — Apply kinded YAML (stackgen ai apply)

Best when: you want a kubectl-style Agent / Workflow / Skill pack for a demo or local bring-up without writing Terraform for those resources. Requires stackgen-beta ≥ v0.82.0-rc.1.

  1. Read the hub — Kinded YAML apply (envelope, dual-controller warning, commands).
  2. Pick an example — start with Product idea → requirements + market fit (scenario tree).
  3. Dry-run then apply — stackgen ai apply -f manifests/… --dry-run, then --approve for workflows.
  4. Run — stackgen ai run workflow/<name> --input 'idea=…'.
  5. Do not dual-control — the same resource name must not also be managed by sg_* Terraform in the same tenant.

Production customer roots still prefer Path 3 (aios-* modules). Use Path 4 for fast demos and iteration.

Migration paths (which guide do I need?)

Two different “migrations” exist — pick the row that matches your starting point:

Starting point Guide When to use
Tenant built in Aiden OS UI (SE-clicked demo) aios-export PoC handoff, customer wants IaC snapshot + import
Existing monolithic terraform/guild/main.tf Migration guide Refactor inline sg_* into composable aios-* modules
Fresh empty tenant Path 1 (scenario) or Path 3 (onboarding) above Greenfield demo or greenfield module composition

These guides are complementary, not interchangeable. Export captures what exists; the migration guide restructures Terraform you already maintain.

Production checklist

Before handing a root to a customer for prod:

  • Pin module ref= — use a tag or commit SHA, not ref=main, in every module block source.
  • Separate environments — same root, different terraform.tfvars (or workspaces) per dev / staging / prod tenant.
  • Secrets via env vars — prefer TF_VAR_stackgen_token and TF_VAR_* over committing terraform.tfvars.
  • Enterprise rollout — see Enterprise deployment profile for webhooks, skills sync, LLM egress, and milestone checklist.
  • New module/scenario from a customer ask — obfuscate names first, then Onboarding step 6 / Cursor skill author-aios-module-scenario. Skill card publish: Skills sync.

Where to get help

  • Scenario missing for a prospect question? — SE feedback and the scenario-request issue template; the scenario-author agent triages within minutes.
  • Module variable questions? — each module’s variables.tf and README.md under modules/<name>/.
  • IDE / agent composition rules? — AGENTS.md at the repo root.