SE playbook
Solutions engineer playbook
A short, prospect-driven map: what the prospect just asked → which scenario you should run. Every scenario in this playbook is one runnable Terraform root under examples/scenarios/ that finishes inside a single discovery call. If the prospect needs the full stack with every integration wired, the reference is still examples/complete/ — but lead with one of these first.
When to reach for 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. |
| PoC handoff: you have configured a tenant in the UI and the customer wants it in code. | Yes — capture it | Use tools/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 and agents / workflows / skills | The diagram + building-block guide is faster than reading 15 module READMEs. |
Prospect-question → scenario
Drop the prompts below in your talk track. Each one points at a single scenario; resist composing on the fly during the call.
Slack / Teams chat wiring: one Event Subscription URL per tenant — {gateway}/slack/events → aiden-router. Set gateway_base_url in scenario terraform.tfvars to print checklist outputs. See Omnichannel triage.
| The prospect said… | Run | Why it lands |
|---|---|---|
| “Can your thing actually fix an AWS incident?” | aws-sre-demo |
Connects AWS, registers the SRE agents, hands you a chat to type “EC2 i-… is unhealthy” into. ~5 min to first reply. |
| “A Datadog monitor fires at 2am — what does your thing do?” | datadog-aws-rca |
Datadog alert → investigate on AWS → RCA written back to Datadog → policy-gated GitHub fix PR, plus a weekly FinOps review. Pairs with stackgen-sre-app for ingest + investigation UI. aiden-demo PoC: POC-DEMO-RUNBOOK.md + stackgen-demo/order-service run-incident-triage-demo.sh. |
| “Can an agent triage Datadog into a notebook without rewriting our shared ones?” | datadog-notebook-triager |
Standalone notebook-triager agent (not the SRE investigator): gather monitors/metrics/logs, create a new investigation notebook; co-located OPA hard-denies edit existing notebooks and dashboard upsert. |
| “A Grafana alert fires — can you tie it to a bad deploy?” | grafana-github-rca |
Grafana alert → correlate telemetry with GitHub commits → RCA written back to Grafana → policy-gated GitHub fix PR. Pairs with stackgen-sre-app for ingest + investigation UI. No cloud creds required — Grafana + GitHub only. |
| “We are drowning in cloud spend.” | finops-weekly |
Cost optimizer + resource janitor + weekly Slack summary. The pitch the team flagged as “comes way later” — now it is a 5-min demo. |
| “Our CI is a mess, what do you actually see?” | pipeline-insights |
Read-only — no prod creds needed. Lowest-friction first demo; safe even mid-call when you do not have the prospect’s AWS yet. |
| “Just get me a preview URL — I don’t care how it deploys.” | shipyard-cce-preview |
Cloud-access summary, packaging PR, temporary preview link. A person must approve stop/rebuild/snapshot. |
| “Can Aiden refine a GitHub Project card without another kanban/agent product?” | github-project-assistant |
One item per run: Specify / Research / Plan → issue comment → optional one Status hop. GitHub + Aiden only — no Fabrik, Claude CLI, or code/PR automation. |
| “Can you generate the right CI/CD YAML when a team pushes a new service?” | cicd-yaml-generator |
GitHub push to main triggers service inspection, stack-specific workflow generation, and a PR with .github/workflows/ci.yml. |
| “Teams keep using raw CDK instead of our golden constructs.” | cdk-golden-construct-adoption |
Scans CDK stacks for raw s3.Bucket, ec2.Vpc, and iam.Role / Role, then opens a PR migrating to approved platform constructs. |
| “How does Aiden secure Jenkins and prevent unauthorized production triggers?” | jenkins-sre-demo |
Jenkins CI/CD integration with OPA-governed trigger permissions and Human-in-the-Loop approvals for production builds. |
| “We get 200 Grafana alerts a day.” | incident-triage |
Grafana ingest filter → prior-incident search → PromQL probe → ReAcTree hypothesis RCA → Slack narrative. Demonstrates the “alert fatigue → triaged narrative” pitch. Optional per-agent PII overlays on rca-investigator (deny EMP badges / allow Grafana UIDs) — see pii-redaction-overlays.md. |
| “Can you hide employee badges but keep Grafana UIDs for Explore?” | incident-triage |
pii_redaction.tf + ./scripts/demo-pii-redaction.sh on the shared shared:incidents root (provider >= 0.1.32; synthetic seed only). |
| “Can your agent use our docs to know where to look, then prove it with Grafana?” | appcd-ai-knowledge-sre |
Knowledge-Guided SRE: Aiden Knowledge supplies Environment Context and troubleshooting guidance, Grafana supplies Evidence, optional remote-runner kubectl adds developer-cluster Evidence. |
| “Our runbooks and docs live in a GitHub repo — can the agent use them?” | github-knowledge-source |
Point a Knowledge Base at a GitHub repo, directory, or file; eligible files sync as Knowledge Documents or Runbook SOPs (incremental by blob SHA). Private repos work through the GitHub integration’s PAT. |
| “How does the agent remember past incidents?” | episodic-memory |
Two-act chat demo: memory_store in session A, memory_search in a new thread session B. No integrations — teaches property glossary and pull-based recall gotchas. For production shared:incidents, follow with incident-triage. |
| “Users get confident wrong answers from our agentic / NLQ system — can Aiden classify code vs prompt vs domain rules?” | accuracy-rca |
Langfuse + SigNoz/OTel → horizontal accuracy_bucket ∈ {code, prompt, domain_rules} → Slack RCA; pull-based memory on shared:accuracy-debug; optional domain-rules knowledge. Scenario README. |
| “Can you throttle runaway agents before they burn the budget?” | agent-autonomy-budget |
sg_agent.autonomy_budget thresholds (LLM calls + tokens per execution); computed autonomy_tier / autonomy_tier_snapshot after enrichment. Scenario README. |
| “We have a legacy repo. Can your platform take it from here?” | repo-to-iac |
Paste a GitHub URL, get IaC. Already runnable today as examples/repo-to-iac/. |
| “We have a monolith codebase — can you tell us how to split it?” | monorepo-services-split |
Run monorepo-services-split-analysis first (guidance PR with service-catalog.yaml). Extract only after plan approval. Pairs with db-state-splitter for IaC + app code. Module guide. CCE workflows. |
| “We have one huge Terraform state file — can you split it into service-owned stacks?” | tfstate-monolith-splitter |
Put the state file on a remote runner, run tfstate-split-and-generate, and review the generated split-projects/ PR with logical service-style groupings. |
| “New AWS calls slip into prod without IAM review.” | pre-deploy-iam-gate |
CCE PR delta → GitHub comment with file:line entitlements. |
| “We page everyone when KMS fails.” | incident-triage |
Enable CCE + github_default_repos — scope RCA to repos that call the failing API. |
| “Auditors want continuous evidence.” | compliance-evidence-factory |
Multi-repo CCE pack scan + regulatory digest. |
| “Argo rollback took down unrelated apps.” | gitops-incident-scope |
CCE directory → Argo app correlation. |
| “We’re landing on Azure — show InfraOps / IfC, not Argo or a monitoring bake-off.” | azure-infraops |
Acme Azure InfraOps: IfC from IDE (StackGen MCP) + repo→Azure IaC (repository-to-iac); optional Azure SaaS SRE second act. |
| “Dependabot alert fatigue.” | cve-reachability-fix |
CCE f-SBOM prioritization + fix PRs. |
“Teams want S3 buckets without s3:*.” |
agentic-infra-entitlements |
CCE on repo-to-iac before developer-request execute. |
| “We want Claude on AWS Bedrock, not a separate Anthropic key.” | bedrock-sonnet-demo |
aios-foundation-bedrock + AWS SRE agent on claude-sonnet-bedrock. IAM role or static AWS keys. Scenario README. |
| “Developers describe infra; we need CloudFormation that matches our catalog and opens a PR.” | cfn-author |
aios-agent-cfn-author intent-to-infrastructure on Bedrock. Scenario README. |
| “CloudFormation stacks drift — classify risk and reconcile valid changes via PR.” | cfn-author |
Drift management workflow + optional daily cron. Same scenario root. |
| “I want to clean state between demos.” | clean-tenant-reset |
Minimal foundation + policies, used as a known baseline you can re-apply over a previous demo. |
| “We use Spec Kit / OpenSpec — can Aiden OS run the full SDD pipeline?” | spec-symphony |
Stage 5 factory: GitHub + Linear webhooks → remote runner → spec bootstrap → implement → validate → PR. Docs. |
| “We have an SRE agent — can you add GitHub, AWS, and on-prem shell?” | sre-boost |
New GitHub + AWS integrations from github_token / aws_role_arn + aiden-runner; merged onto an existing agent (no new models). Runner attach via sg_remote_runner_attachments. Scenario README. |
| “Can Vault pull from AWS Secrets Manager instead of stuffing keys in metadata?” | vault-external-secrets |
sg_external_secret_store + formats catalog + optional referencing sg_secret (provider >= 0.1.54). Scenario README. |
| “We live in Microsoft Teams — can Aiden join as a first-class bot?” | teams-omnichannel |
sg_teams_connection + Azure Bot event_url; optional Teams chat channel with attach_channel_context. Do not dual-control Teams via sg_chat_platform. Scenario README. |
| “Turn a one-liner product idea into requirements and market fit — without Terraform?” | product-idea-ai-apply |
Kinded YAML + stackgen ai apply (CLI ≥ v0.82.0-rc.1): two agents, movie+plain skill (pirate kept for skill-swap exercise), tandem workflow. Docs · Scenario. Not make demo. |
| “Can Aiden write Playwright e2e tests against our signed-in app?” | chrome-e2e |
Remote-runner Chrome + vault browser session (cookies or storage state) → explore → Jest/Playwright spec → draft PR. StackGen UI session is one preset. Provider >= 0.1.52. Guide · Scenario. |
Demo runbook (one screen)
- Sanity-check creds —
make demo-doctorwill tell you what is missing before the prospect sees a stack trace. - Pick the scenario from the table above.
make demo SCENARIO=<name>. - Open the Aiden URL printed in the outputs. The scenario README’s Talk track section is the 5-bullet talk you walk through.
- After the call, run
make demo-reset SCENARIO=<name>so the next prospect lands on a clean slate.
Review a failed / stuck run
When a prospect (or you) exports an offline debug ZIP from the execution watch page:
- Open the Execution Trace Viewer (client-side only — the ZIP never leaves the browser).
- Drop the
execution-*.zip(or the unzipped files). Use Overview + Judge for the one-screen story, Timeline / Tools for the first hard failure, Events for AG-UI detail. - For a written SE report, follow the Cursor skill
se-execution-run-review(bundle-only evidence, no source spelunking).
If your prospect wants the export instead of a fresh demo — i.e. they already played with Aiden in the UI and want to keep it — point them at tools/aios-export/. Phase 1 emits raw sg_* HCL plus a JSON snapshot; phase 2 rewrites that HCL into module form.
Office hours & feedback
This page is edited by the solutions team — plus the bot. Open a scenario-request issue (template) when a prospect asks something we do not yet have a one-command answer for. The scenario-author agent triages every such issue within minutes: it either points you at the existing scenario that fits or scaffolds a draft PR (with this table updated as part of the PR’s reviewer checklist). The owners for each scenario are listed in CONTRIBUTORS-SE.md; ping them directly when their scenario’s PR needs review. Office-hour cadence and Slack channel are in docs/se-feedback.md.