diff --git a/docs/presentations/README.md b/docs/presentations/README.md new file mode 100644 index 0000000..8e637ed --- /dev/null +++ b/docs/presentations/README.md @@ -0,0 +1,223 @@ +# Presentations + +Leadership-facing presentation decks for the ACDL platform. + +## The 3-step slide creation process + +Every presentation in this folder is produced by the same three-step process. +**Never edit the Marp deck or the PPTX directly** — always start from the full +markdown source of truth (Step 1), synthesize the Marp deck (Step 2), then +export to PPTX (Step 3). This keeps a reviewable, plain-text source of truth +for every deck. + +``` +Step 1: full markdown Step 2: Marp deck Step 3: PPTX export +(source of truth) ──► (lean, no notes) ──► (presentation-ready) +*.md *-marp.md *.pptx ++ speaker notes + embedded PNG diagrams + embedded images ++ mermaid code blocks + Marp frontmatter +``` + +### Step 1 — Full markdown (source of truth) + +**File convention:** `.md` (e.g. `how-the-platform-works.md`). + +Write the complete deck as a standard markdown file. This is the **source of +truth** — it contains: + +- Every slide as an `## Slide N — Title` H2 section. +- Tight bullets with leadership-relevant content. +- A `> **Speaker notes:**` block at the end of each slide with the nuance, + the "who cares and why," and the honesty caveats. +- Mermaid diagrams as ```` ```mermaid ```` fenced code blocks (these render + on GitHub/Pages but not in Marp — Step 2 converts them to images). +- An honest "shipped vs. planned" framing: every "available today" claim is + grounded in shipped/verified work; every "planned" item is explicitly + marked. + +**Why this file is the source of truth:** it is reviewable in any markdown +viewer, diffs cleanly in git, and carries the full reasoning (speaker notes) +that a presenter needs. The Marp deck and PPTX are *derived artifacts* — if a +fact is wrong, fix it here and re-run Steps 2 and 3. + +### Step 2 — Marp deck synthesis + +**File convention:** `-marp.md` (e.g. `how-the-platform-works-marp.md`). + +Synthesize the full markdown into a lean Marp deck: + +- **Marp frontmatter** at the top: `marp: true`, `theme: default`, + `paginate: true`, `size: 16x9`, a header/footer, and an inline `style:` + block for fonts, colors, tables, badges. +- **No speaker notes.** The Marp deck is what the audience sees; the + speaker notes live only in the Step 1 source of truth. +- **Mermaid diagrams → PNG images.** Marp does not render mermaid fenced + blocks natively. Extract each mermaid block from Step 1 into a `.mmd` + source file under `assets/mmd/`, render it to PNG under `assets/png/`, + and embed it with `![w:1000](assets/png/.png)`. +- **`` + ``** on title and + closing slides for the dark-background title style. +- **Maturity badges** using inline spans: + `Available today` + `Planned` +- **Tighter prose** than Step 1 — strip the speaker-note nuance; keep the + leadership-relevant selling points. + +### Step 3 — PPTX export + +Export the Marp deck to PPTX for stakeholders who want a slide file: + +```bash +CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \ + npx --yes @marp-team/marp-cli@latest --allow-local-files \ + docs/presentations/-marp.md \ + -o .pptx +``` + +The `--allow-local-files` flag is **required** for PPTX export so the local +PNG diagrams are embedded in the file. + +## Directory layout + +``` +docs/presentations/ +├── README.md ← this file +├── how-the-platform-works.md ← Step 1: full source of truth +├── how-the-platform-works-marp.md ← Step 2: Marp deck +├── the-developer-experience.md ← Step 1: full source of truth +├── the-developer-experience-marp.md ← Step 2: Marp deck +└── assets/ + ├── puppeteer-config.json ← no-sandbox config for mmdc + ├── mmd/ ← mermaid source files (Step 2 input) + │ ├── platform-works-01-contract-driven.mmd + │ ├── platform-works-02-end-to-end-flow.mmd + │ ├── developer-experience-01-two-surfaces.mmd + │ ├── developer-experience-02-what-dev-does.mmd + │ └── developer-experience-03-no-cloning.mmd + └── png/ ← rendered PNGs (embedded in Marp) + ├── platform-works-01-contract-driven.png + ├── platform-works-02-end-to-end-flow.png + ├── developer-experience-01-two-surfaces.png + ├── developer-experience-02-what-dev-does.png + └── developer-experience-03-no-cloning.png +``` + +## Conventions + +### Maturity framing + +Every capability claim in a deck is tagged with one of two badges: + +| Badge | Meaning | +|---|---| +| `Available today` | Shipped and verified in the platform | +| `Planned` | On the roadmap, not yet shipped | + +This is non-negotiable for a leadership audience: never present a roadmap +item as a current capability, and never bury a shipped capability's +availability. When in doubt, check `.ciagent/ROADMAP.md` and the milestone +status in `.ciagent/PROJECT.md`. + +### Audience + +The audience for these decks is **Senior Leadership**: CTO, Head of Cloud, +Head of Infrastructure, Head of DevOps. The framing rules: + +- **No jargon.** Translate internal terms: "primitives/modules" not "L1/L2", + "intent" not "IR", "human attestation" not "HITL", "pattern" not + "composition." +- **Selling points forward.** Each slide leads with the leadership-relevant + outcome; the mechanism follows. +- **Zero-trust, security, observability, auditability, DX, citizen + developer** are the themes — not implementation details. + +### Diagrams + +Mermaid diagrams in the Step 1 source use the repo's existing `flowchart` +style (renders on GitHub/Pages). For the Marp deck (Step 2): + +1. Extract the mermaid block into `assets/mmd/--.mmd`. +2. Use **horizontal layouts** (`flowchart LR`) or **subgraph row-wrapping** + for wide diagrams so the PNG fits a 16:9 slide without shrinking to + illegibility. A 9-node sequential `flowchart TD` renders as a tall thin + strip — restructure it as 2-row subgraphs or `flowchart LR`. +3. Render with a 2x scale factor and transparent background for crisp slides. +4. Embed with `![w:1000](assets/png/.png)` (or `h:320` for tall images). + +## Build commands + +### Prerequisites + +- Node.js + npx (for `@marp-team/marp-cli` and `@mermaid-js/mermaid-cli`) +- A Chrome/Chromium binary (Marp PPTX export requires it) + +This environment has a working Chromium at: +`/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome` + +### Render all mermaid diagrams to PNG + +```bash +cd docs/presentations/assets +for f in mmd/*.mmd; do + name=$(basename "$f" .mmd) + PUPPETEER_EXECUTABLE_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \ + npx --yes @mermaid-js/mermaid-cli@latest \ + -i "$f" -o "png/$name.png" \ + -p puppeteer-config.json -s 2 -b transparent +done +``` + +The `puppeteer-config.json` passes `--no-sandbox` to the headless browser +(required when running as root in this environment). + +### Export a Marp deck to HTML (for browser preview) + +```bash +CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \ + npx --yes @marp-team/marp-cli@latest \ + docs/presentations/-marp.md \ + -o .html +``` + +HTML export inlines images as base64 data URIs — no `--allow-local-files` +needed. + +### Export a Marp deck to PPTX (for stakeholders) + +```bash +CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \ + npx --yes @marp-team/marp-cli@latest --allow-local-files \ + docs/presentations/-marp.md \ + -o .pptx +``` + +`--allow-local-files` is **required** for PPTX so local PNG diagrams are +embedded in the file. + +## Adding a new presentation + +1. **Write the full markdown** as `.md` following the + `## Slide N — Title` + `> **Speaker notes:**` structure. This is the + source of truth. +2. **Extract any mermaid diagrams** into `assets/mmd/--.mmd` + and render them to `assets/png/` (command above). +3. **Synthesize the Marp deck** as `-marp.md` with frontmatter, + no speaker notes, embedded PNGs, and maturity badges. +4. **Export to PPTX** with `--allow-local-files`. +5. **Verify** the PPTX slide count and that media files are embedded: + ```bash + python3 -c " + import zipfile, re + with zipfile.ZipFile('.pptx') as z: + slides = [n for n in z.namelist() if re.match(r'ppt/slides/slide\d+\.xml$', n)] + media = [n for n in z.namelist() if n.startswith('ppt/media/')] + print(f'{len(slides)} slides, {len(media)} media files') + " + ``` + +## Current decks + +| Deck | Source of truth (Step 1) | Marp deck (Step 2) | Audience | +|---|---|---|---| +| How the Platform Works | `how-the-platform-works.md` | `how-the-platform-works-marp.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps | +| The Developer Experience | `the-developer-experience.md` | `the-developer-experience-marp.md` | CTO, Head of Cloud, Head of Infra, Head of DevOps | \ No newline at end of file diff --git a/docs/presentations/assets/mmd/developer-experience-01-two-surfaces.mmd b/docs/presentations/assets/mmd/developer-experience-01-two-surfaces.mmd new file mode 100644 index 0000000..c82745a --- /dev/null +++ b/docs/presentations/assets/mmd/developer-experience-01-two-surfaces.mmd @@ -0,0 +1,7 @@ +flowchart LR + A["Technical developer"] --> C["Contract YAML"] + B["Citizen developer
(non-technical)"] --> D["Declares intent
in natural language"] + D --> E["Agent produces
the contract"] + C --> F["Same platform:
resolve → check → plan →
policy → confidence → apply"] + E --> F + F --> G["Same safety guarantees,
same audit trail"] \ No newline at end of file diff --git a/docs/presentations/assets/mmd/developer-experience-02-what-dev-does.mmd b/docs/presentations/assets/mmd/developer-experience-02-what-dev-does.mmd new file mode 100644 index 0000000..92aa160 --- /dev/null +++ b/docs/presentations/assets/mmd/developer-experience-02-what-dev-does.mmd @@ -0,0 +1,5 @@ +flowchart LR + A["1. App code
(top level of the repo)"] --> D["Push to main"] + B["2. Contract
(.acdl/contract.yaml)"] --> D + C["3. CI definition
(.github/workflows/deploy.yml
— one 'uses:' line)"] --> D + D --> E["Platform does the rest"] \ No newline at end of file diff --git a/docs/presentations/assets/mmd/developer-experience-03-no-cloning.mmd b/docs/presentations/assets/mmd/developer-experience-03-no-cloning.mmd new file mode 100644 index 0000000..1c52292 --- /dev/null +++ b/docs/presentations/assets/mmd/developer-experience-03-no-cloning.mmd @@ -0,0 +1,6 @@ +flowchart LR + A["Consumer repo
app + contract + 'uses:'"] -->|triggers on push to main| B["Platform runner"] + B -->|checks out the consumer repo| A + B -->|checks out the ACDL platform repo
into the workspace| C["Platform code
(modules, adapters, schemas)"] + C --> B + B -->|runs the pipeline against
the consumer's contract| D["Consumer's resources in AWS"] \ No newline at end of file diff --git a/docs/presentations/assets/mmd/platform-works-01-contract-driven.mmd b/docs/presentations/assets/mmd/platform-works-01-contract-driven.mmd new file mode 100644 index 0000000..ecbc9a5 --- /dev/null +++ b/docs/presentations/assets/mmd/platform-works-01-contract-driven.mmd @@ -0,0 +1,3 @@ +flowchart LR + A["Consumer
writes a contract"] --> B["Platform resolves,
compiles, checks,
deploys, records"] + B --> C["Resources running in AWS
+ tamper-evident evidence"] \ No newline at end of file diff --git a/docs/presentations/assets/mmd/platform-works-02-end-to-end-flow.mmd b/docs/presentations/assets/mmd/platform-works-02-end-to-end-flow.mmd new file mode 100644 index 0000000..194e015 --- /dev/null +++ b/docs/presentations/assets/mmd/platform-works-02-end-to-end-flow.mmd @@ -0,0 +1,10 @@ +flowchart TD + subgraph R1 [" "] + direction LR + A["Consumer
contract"] --> B["Validate
contract"] --> C["Resolve to
target stack"] --> D["Security
checks"] --> E["Infrastructure
plan"] + end + subgraph R2 [" "] + direction LR + F["Policy
checks"] --> G["Confidence
signal"] --> H["Evidence
event"] --> I["Infrastructure
apply"] + end + E --> F \ No newline at end of file diff --git a/docs/presentations/assets/png/developer-experience-01-two-surfaces.png b/docs/presentations/assets/png/developer-experience-01-two-surfaces.png new file mode 100644 index 0000000..58c4eeb Binary files /dev/null and b/docs/presentations/assets/png/developer-experience-01-two-surfaces.png differ diff --git a/docs/presentations/assets/png/developer-experience-02-what-dev-does.png b/docs/presentations/assets/png/developer-experience-02-what-dev-does.png new file mode 100644 index 0000000..39ce66c Binary files /dev/null and b/docs/presentations/assets/png/developer-experience-02-what-dev-does.png differ diff --git a/docs/presentations/assets/png/developer-experience-03-no-cloning.png b/docs/presentations/assets/png/developer-experience-03-no-cloning.png new file mode 100644 index 0000000..97c9872 Binary files /dev/null and b/docs/presentations/assets/png/developer-experience-03-no-cloning.png differ diff --git a/docs/presentations/assets/png/platform-works-01-contract-driven.png b/docs/presentations/assets/png/platform-works-01-contract-driven.png new file mode 100644 index 0000000..21629ea Binary files /dev/null and b/docs/presentations/assets/png/platform-works-01-contract-driven.png differ diff --git a/docs/presentations/assets/png/platform-works-02-end-to-end-flow.png b/docs/presentations/assets/png/platform-works-02-end-to-end-flow.png new file mode 100644 index 0000000..534fd49 Binary files /dev/null and b/docs/presentations/assets/png/platform-works-02-end-to-end-flow.png differ diff --git a/docs/presentations/assets/puppeteer-config.json b/docs/presentations/assets/puppeteer-config.json new file mode 100644 index 0000000..e52bfae --- /dev/null +++ b/docs/presentations/assets/puppeteer-config.json @@ -0,0 +1 @@ +{ "args": ["--no-sandbox", "--disable-setuid-sandbox"] } \ No newline at end of file diff --git a/docs/presentations/how-the-platform-works-marp.md b/docs/presentations/how-the-platform-works-marp.md new file mode 100644 index 0000000..56b2e92 --- /dev/null +++ b/docs/presentations/how-the-platform-works-marp.md @@ -0,0 +1,243 @@ +--- +marp: true +theme: default +paginate: true +size: 16x9 +header: "ACDL — How the Platform Works" +footer: "Confidential · For Senior Leadership" +style: | + section { + font-family: "Inter", "Segoe UI", "Helvetica Neue", sans-serif; + font-size: 22px; + } + h1 { color: #1a365d; font-size: 34px; margin-bottom: 0.3em; } + h2 { color: #1a365d; font-size: 26px; margin-bottom: 0.2em; } + section.title { background: #1a365d; color: #fff; } + section.title h1 { color: #fff; } + table { font-size: 18px; width: 100%; } + th { background: #edf2f7; } + blockquote { border-left: 4px solid #3182ce; color: #2d3748; font-size: 20px; } + img { display: block; margin: 0 auto; max-height: 320px; } + .badge { + display: inline-block; padding: 2px 8px; border-radius: 4px; + font-size: 14px; font-weight: 600; + } + .today { background: #c6f6d5; color: #22543d; } + .planned { background: #fef3c7; color: #78350f; } +--- + + + + +# How the Platform Works + +**ACDL — Agentic Cloud Delivery Platform** + +Senior Leadership Briefing + + + +--- + +# The Problem We Solve + +Software delivery scales with the **coordination surface around it**, not the engineering inside it. + +Two frictions slow every team: + +- **Cognitive load** — authoring the infrastructure that runs a service *correctly*. The long tail of services that are difficult to deploy, inconsistent in security and observability posture. +- **Operational work** — moving a merged change from "merged" to "running in production with policy, observability, and security enforced." Manual work that **scales with the system, not with the change.** + +The platform absorbs **both** frictions. + +--- + +# The North Star + +> Consumers **declare intent**; the platform delivers **safe production deployment** — automatically, safely, and with a complete audit trail. + +Success looks like: + +- A merged change progresses through lower environments **without a platform engineer joining a thread, approving a ticket, or triggering a stage.** +- A **non-technical consumer** ships a production deployment by declaring intent — without authoring a workflow, a configuration file, or an infrastructure module. +- Every production change is **traceable to a human attestation and an immutable evidence stream.** + +--- + +# The Contract-Driven Model + +One small YAML file is all a consumer writes. The platform owns everything else. + +![w:900](assets/png/platform-works-01-contract-driven.png) + +The contract names three things: + +- **Which module** — a catalog of pre-built, security-reviewed building blocks +- **Which environment** — the platform raises the safety bar automatically as sensitivity rises +- **Which inputs** — the handful of values that vary per deployment + +--- + +# The End-to-End Flow + +Every deployment runs the same stages, in the same order, with the same checks — no team-specific pipelines, no tribal runbooks. + +![w:1100](assets/png/platform-works-02-end-to-end-flow.png) + +- **Security and policy checks run *before* any infrastructure is created** +- **Every stage produces a record** that feeds the confidence signal and the evidence stream — there is no "unchecked" path + +--- + +# Zero-Trust by Default + +Consumer repositories hold **no long-lived cloud credentials.** Ever. + +- **Authentication — OIDC federation.** Each job mints a short-lived token; no credential is stored in the consumer repo or in a runner secret. Available today (GitHub Actions) Planned: all runners +- **Authorization — attribute-based (ABAC), not role-based.** Two attribute classes scope every action: + - **Repository identity** — the role's trust policy binds to the exact consumer repo + branch + - **Resource tags** — every resource is tagged `acdl:owner` + `acdl:contract`; the session policy grants access **only to matching tags** + +**The effect:** a consumer can only touch the resources it created. Blast radius is contained. One consumer can never affect another. + +--- + +# Safety is Computed, Not Assumed + +Every delivery action produces a **measurable, explainable confidence signal** — the platform's certified answer to *"is this safe to proceed?"* + +- **Six weighted inputs:** policy conformance, validation, freshness, source provenance, history, NFRs +- **Per-environment thresholds** that rise with sensitivity: + +| Environment | Threshold | Attester | +|---|---|---| +| dev | ≥ 0.50 | No one — autonomous | +| qa | ≥ 0.75 | QA | +| prod | ≥ 0.90 | SRE | +| dr | ≥ 0.95 | SRE + DR drill | + +- **A single critical finding hard-blocks the deployment** — critical findings are not averaged away +- **When the platform halts, it gives a measured reason** — never an opaque debugging exercise + +--- + +# Policy & Security Enforcement + +Checks run on **every** deployment, normalized to a single schema regardless of which engine produced them. + +- **Infrastructure policy** (Checkov) — secrets in plaintext, public ingress, IAM wildcards, KMS references, **required tagging standards** (`acdl:owner`, `acdl:contract`, `acdl:environment`, `acdl:cost-center`) Available today +- **Cloud security posture** (Wiz adapter) — translates cloud security findings into the same normalized record Adapter ready +- **Kubernetes-native policy** (Kyverno adapter) — ready for the GitOps reconciler Adapter ready + +Every check produces a record with **severity, rule ID, pass/fail status, and a human-readable message** — consumed uniformly by the confidence signal. + +--- + +# Secure by Default + +Security defaults that **do not require a team to opt in.** Available today + +- **Encryption on every resource** — at-rest encryption on by default for every primitive (S3, RDS, ECR, ECS, and more) +- **Per-stack customer-managed keys** — one key per deployment, 90-day rotation, **no shared keys across stacks** +- **Managed-key fallback with a loud warning** — silent use of cloud-managed keys is a security gap we refuse to hide +- **Deletion protection on by default** — `prevent_destroy` on unless a consumer explicitly disables it via a documented flag +- **Safe decommission** — a 2-step pipeline (disable protection → zero counts → destroy) with **two SRE attestation gates** and a **change-request validated against the CMDB** + +--- + +# Immutable Audit & Evidence + +Version control is a **coordination tool, not an evidentiary fortress.** True compliance requires an immutable, externally-stored ledger. + +- **Every deployment writes a hash-chained evidence event** — each event links to the previous via a cryptographic hash; tampering breaks the chain Available today +- **Tiered storage:** cold, tamper-proof source of truth (S3 Object Lock, 7-year retention) + a hot query index Outbox shipped Full ledger: planned +- **RPO = 0** — the evidence write is synchronous; a deployment is not acknowledged until the evidence event is durably recorded +- **Every production change is traceable to a human attestation** — approver identities are the only durable record outside the forge's audit log + +--- + +# Human-in-the-Loop Where It Matters + +Autonomy and accountability are **not in tension** — they apply at different environments. + +- **Dev is fully autonomous.** The confidence signal (≥ 0.50) is the only gate. Queue-based handoffs are eliminated from lower environments. +- **qa, prod, and dr require deliberate human attestation** — not rubber stamps, but policy-mandated acts of accountability via protected deployment approvals. +- **Separation of duties is enforced** — the QA approver **cannot** be the prod approver. The platform reads both identities from the outbox and **blocks on a match.** Design shipped Wiring: planned +- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit + +--- + +# Observability Built In + +Monitoring is **a platform default, not a per-team project.** Available today + +- **Uptime monitoring deployed automatically with every stack** — a dedicated monitoring instance is provisioned after any module deploy, in a separate state, with a feature flag to disable +- **Monitored endpoints passed from the deployment's own outputs** — no manual endpoint registration +- **Alert channels:** Microsoft Teams webhook, email, SMS, and GitHub issues +- **The uptime URL is published to the developer** via a PR comment — they don't hunt for it +- **Roadmap:** deeper observability bootstrap (dashboards, runbooks, on-call bindings) as first-class contract fields + +--- + +# Platform-Managed Environments + +A consumer provides **no AWS account, no VPC, no subnet, no state backend, no runner key.** The platform owns the blast radius. + +A named environment is a platform-owned bundle of: + +- An AWS account (or a scoped partition of one) +- A network (VPC + subnets) +- A state backend (S3 + DynamoDB for state + locking) +- An IAM role surfaced via ABAC, scoped to the consumer's identity and resource tags + +The consumer selects an environment **by name** in their contract. The platform resolves the name to the underlying resources at run time. **The consumer never sees raw credentials.** + +**Friendly onboarding:** the first run detects no environment and emits a guided prompt (not an opaque failure). Available today Self-service: planned + +--- + +# Portability & Future-Proofing + +The platform is **opinionated, but not painted into a corner.** + +- **Substrate-agnostic core.** The contract, the resolved stack, the policy results, the confidence signal, and the evidence stream are all defined *without reference to any specific infrastructure tool.* 1 adapter: Terraform OpenTofu / Pulumi / K8s +- **Forge-agnostic contract ingestion.** The platform Lambda reads a configurable API base for GitHub or Gitea. Available today +- **Portable contracts.** A second forge needs a forge adapter + a workflow translator — **no change to modules, contracts, confidence, or audit** +- **Pattern recognition compounds value over time.** As the platform observes recurring patterns, it can synthesize reusable modules. Future capability + +--- + + + + +# Roadmap: Shipped vs. Planned + + + +**Available today** + +- Contract-driven deploys with a versioned reusable workflow +- Module catalog (primitives + modules) with validated examples +- Zero-trust OIDC + ABAC on GitHub Actions runners +- Security + policy checks before infra creation (Checkov; Wiz + Kyverno ready) +- Confidence signal (6 inputs, per-env thresholds) gating promotion +- Hash-chained, tamper-evident evidence outbox (RPO = 0) +- Encryption by default + per-stack customer-managed keys +- Deletion protection by default + safe decommission with SRE gates +- Uptime monitoring deployed automatically with every stack +- Platform-managed environments + friendly onboarding +- Local reproducibility + forge-agnostic contract ingestion + +**Planned (on the roadmap)** + +- Real OIDC federation on all platform runners +- HITL wiring for qa / prod / dr environments +- Full regulatory ledger: S3 Object Lock + JWS signatures + daily checkpoints +- Compliance milestone: GDPR, SOX, SOC2, HIPAA, DORA extension points +- Environment self-service provisioning +- Dynamic module creation from a contract (agentic citizen-developer flow) +- Additional substrate adapters (OpenTofu, Pulumi, Kubernetes CRDs) \ No newline at end of file diff --git a/docs/presentations/the-developer-experience-marp.md b/docs/presentations/the-developer-experience-marp.md new file mode 100644 index 0000000..1bf1c91 --- /dev/null +++ b/docs/presentations/the-developer-experience-marp.md @@ -0,0 +1,304 @@ +--- +marp: true +theme: default +paginate: true +size: 16x9 +header: "ACDL — The Developer Experience" +footer: "Confidential · For Senior Leadership" +style: | + section { + font-family: "Inter", "Segoe UI", "Helvetica Neue", sans-serif; + font-size: 22px; + } + h1 { color: #1a365d; font-size: 34px; margin-bottom: 0.3em; } + h2 { color: #1a365d; font-size: 26px; margin-bottom: 0.2em; } + section.title { background: #1a365d; color: #fff; } + section.title h1 { color: #fff; } + table { font-size: 18px; width: 100%; } + th { background: #edf2f7; } + blockquote { border-left: 4px solid #3182ce; color: #2d3748; font-size: 20px; } + pre { font-size: 16px; line-height: 1.3; } + code { font-size: 16px; } + img { display: block; margin: 0 auto; max-height: 300px; } + .badge { + display: inline-block; padding: 2px 8px; border-radius: 4px; + font-size: 14px; font-weight: 600; + } + .today { background: #c6f6d5; color: #22543d; } + .planned { background: #fef3c7; color: #78350f; } +--- + + + + +# The Developer Experience + +**ACDL — Agentic Cloud Delivery Platform** + +Senior Leadership Briefing + + + +--- + +# Two Consumer Surfaces, One Platform + +The platform serves **two kinds of consumer** through two coordinated interfaces — both converge on the **same contract, the same policy envelope, and the same evidence stream.** + +![w:1000](assets/png/developer-experience-01-two-surfaces.png) + +- **Technical developer** — owns app code + a contract + a thin CI definition +- **Citizen developer** — declares intent in plain language; an agent produces a contract that passes the **same** safety envelope + +The platform is **opinionated in what it accepts, regardless of who is declaring.** There is no "citizen developer mode" with weaker checks. + +--- + +# What a Developer Actually Does + +Three things. That is the entire consumer-side surface. + +![w:900](assets/png/developer-experience-02-what-dev-does.png) + +The developer does **not**: + +- Write infrastructure modules +- Author workflow YAML beyond the one-line `uses:` wrapper +- Clone the platform repo +- Hold cloud credentials +- Maintain a state backend, a VPC, or a runner + +--- + +# The Citizen Developer Experience + +A non-technical consumer ships a production deployment **by declaring intent** — without authoring a workflow, a configuration file, or an infrastructure module. + +- The consumer opens an issue describing what they need (e.g. "a web API for the pricing service") +- An agent maps the intent to a contract referencing a module from the **reviewed skill catalog** +- The contract enters the **same pipeline** and must clear the **same confidence gate** before promotion + +**Guardrails that make this safe:** + +- Skills are **versioned, signed, and reviewed for sensitive data before release** (Infra & Ops owns the review) +- Agents are **stateless** — all state lives in the platform; the platform trusts and **always verifies** +- The agent's trace and submission confidence are captured in the contract for review + +Skill catalog + real agent runtime: planned + +--- + +# The Contract + +A 5-line YAML file. This is the entire consumer-facing interface to production. + +```yaml +# .acdl/contract.yaml — a static site +uses: acdl/pipelines/deploy.yaml@v1.6 +module: static-assets +environment: dev +inputs: + bucket_name: my-static-site-assets + region: us-east-1 +``` + +```yaml +# .acdl/contract.yaml — a microservice +uses: acdl/pipelines/deploy.yaml@v1.6 +module: microservice +environment: dev +inputs: + image: my-registry/my-microservice:latest + port: 8080 +``` + +An invalid contract **fails fast at validation** with a clear error — not an opaque failure three stages in. + +--- + +# No Platform Code, No Cloning + +Consumers `uses:` a **versioned** central workflow. The platform fetches itself at run time. The consumer **never touches platform internals.** + +![w:1000](assets/png/developer-experience-03-no-cloning.png) + +- The consumer's CI definition is a thin wrapper — one `uses:` line +- The runner checks out the consumer repo, then checks out the platform repo into the workspace +- The platform installs its own runtime dependencies — the consumer installs nothing +- When the platform ships a fix, every consumer on a floating tag gets it on their next run + +--- + +# Versioned, Predictable Releases + +Consumers control **when** they absorb platform improvements. + +- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer automatically receives patch updates within the line Available today +- **Semantic versioning with a clear contract:** interface → MAJOR, behavior → MINOR, lifecycle → PATCH +- **A consumer can pin to an exact version** for maximum stability, or float on MAJOR only (`@v1`) to absorb new features on their own cadence +- **Unversioned references (`@main`, bare) are discouraged** — the versioned tag is the only immutability lever +- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags Available today + +--- + +# Instant Feedback + +Developers see **what the platform is doing**, in real time, in their own run logs. Available today + +- **Streamed output by default** — the infrastructure plan, policy-check results, and each check record (severity, rule ID, pass/fail) flow to stdout +- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard +- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque debugging exercise.** +- **A `--quiet` mode** suppresses streaming for log-only contexts + +--- + +# Deploy Outputs That Just Work + +After a successful deploy, the developer gets their connection information **without hunting for it** — and without secrets leaking into logs. Available today + +- **Human-readable connection strings** posted as a structured GitHub PR comment / job summary +- **Runtime-injectable values** written to encrypted Parameter Store (`SecureString`, KMS-encrypted, namespaced `/acdl/{env}/{contractId}/{output_name}`) +- **No raw secrets in logs** — enforced by construction +- **Errors become GitHub issues, automatically** — a failed deploy reports through the platform Lambda, which opens (or comments on) an issue on the platform repo. The consumer's only grant is the onboarding-granted Lambda-invoke permission + +--- + +# Local Reproducibility + +The entire CI pipeline runs **from the shell**, not just in CI. Available today + +- `scripts/run_ci.sh` mirrors the CI pipeline locally — the same three stages (lint → test → check-only) in sequence +- `scripts/run_platform.sh --check-only` runs the platform **offline** — no AWS, no policy engine, no outbox required. Validates a contract end-to-end before pushing +- `--plan-only` runs through the infrastructure plan without applying +- The CI and deploy pipelines are defined by **declarative contracts** (YAML instances validated against JSON Schemas) — a single source of truth that both workflows implement. A test asserts conformance + +--- + +# Friendly Onboarding + +First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. Available today + +When no environment is bound, the platform emits a **user-friendly onboarding prompt** instead of failing opaquely: + +1. That no environment is bound to their repo yet +2. What the platform will provision on their behalf (account, network, state, role) +3. The expected turnaround for the platform team to grant the environment +4. How to request an environment + +The pipeline then **exits without attempting a deployment** — no partial state, no confusing errors. + +Both onboarding paths end in a **sandbox dev submission that must pass the confidence gate** before the consumer is promoted. + +Citizen developer onboarding path: planned + +--- + +# Safe Promotion Path + +The contract is environment-agnostic by design. Promotion is **a workflow choice, not a contract edit** — the platform raises the bar automatically. + +**Approach A — One contract, one job per environment.** A single contract is referenced by multiple jobs; the environment is passed by each job and interpolated at runtime. The contract never changes. + +```yaml +jobs: + dev: + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: { contract: .acdl/contract.yaml, environment: dev } + qa: + needs: dev + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: { contract: .acdl/contract.yaml, environment: qa } +``` + +**Approach B — One job per environment, environment-specific contracts.** When inputs genuinely differ per environment, each job points at its own contract file. + +```yaml +jobs: + dev: + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: { contract: .acdl/contract-dev.yaml } + qa: + needs: dev + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: { contract: .acdl/contract-qa.yaml } +``` + + + +--- + +# Safe Promotion Path — The Rising Bar + +Whichever approach a team picks, the platform applies the same rising bar: + +| Environment | What the platform adds | +|---|---| +| dev | Confidence ≥ 0.50, fully autonomous | +| qa | QA human attestation + confidence ≥ 0.75 | +| prod | SRE human attestation + confidence ≥ 0.90 | +| dr | SRE human attestation + confidence ≥ 0.95 + DR drill reference | + +- **No staging environment** — the design deliberately removes the "staging is basically prod but not really" anti-pattern +- **Separation of duties is enforced** — the QA approver cannot be the prod approver Design shipped Wiring: planned +- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit + +The DX win: the contract stays stable across environments. The safety win: the platform raises the threshold and attestation bar automatically based on the job's declared environment. + +--- + +# Safe Decommission + +Tearing down a stack is **as deliberate as deploying one** — and just as gated. Available today + +```yaml +uses: acdl/.github/workflows/deploy.yml@v1.8 +with: + contract: .acdl/contract.yaml + mode: decommission + changeRequestId: "CR-2026-001" +``` + +A 2-step pipeline with **two SRE human-attestation gates**: + +1. **Validate the change request** — the platform queries the CMDB; the CR must be `approved` and match the consumer repo +2. **Disable deletion protection** (plan + apply) → **SRE approves** +3. **Zero all counts + destroy** (plan + apply) → **a second SRE approves** +4. **Confirmation** — the stack is destroyed + +The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable. + +--- + +# Self-Service Module Catalog + +Developers pick from **pre-built, security-reviewed building blocks** — they don't author infrastructure from scratch. Available today + +- **Primitives** — single-purpose resources (S3, VPC, ECS, IAM, load balancer, container registry, CloudFront, WAF, RDS), each with documented inputs/outputs, usage, compliance extension points, and versioning +- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + load balancer + registry) +- **Validated examples per module** — `simple.yaml` + `complex.yaml` + variation files, validated against the contract schema in CI. Examples cannot drift from the schema silently +- **Auto-promotion of patterns** — a thin-composition layer is auto-promoted to the catalog after 3 observed usages Planned +- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, HIPAA, DORA controls will wire in Planned + +--- + + + + +# The Outcome for Leadership + + + +- **Velocity without sacrificing safety.** Speed is in the ergonomics (a 5-line contract, a one-line `uses:`); safety is in the gates the consumer cannot bypass. +- **Security, observability, and compliance as platform defaults** — not per-team effort, not post-hoc remediation. Encryption, deletion protection, uptime monitoring, policy checks, and evidence are on by construction. +- **Auditability as a byproduct, not a project.** Every production change is traceable to a human attestation and a tamper-evident evidence event. +- **Blast radius contained by design.** Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources. +- **The bottleneck moves off the platform team's ticket queue.** A merged change progresses through lower environments without a platform engineer joining a thread. +- **A path to the citizen developer.** The same safety envelope that serves a senior engineer is the one that will serve a non-technical consumer — expanding who can ship safely without lowering the bar. \ No newline at end of file diff --git a/docs/presentations/the-developer-experience.md b/docs/presentations/the-developer-experience.md index 9dc8c7d..605ed02 100644 --- a/docs/presentations/the-developer-experience.md +++ b/docs/presentations/the-developer-experience.md @@ -208,14 +208,54 @@ First impressions of a platform are made **when it fails for the first time.** T ## Slide 11 — Safe Promotion Path -Promoting to a higher environment is **changing one field** — and the platform raises the bar automatically. +The contract is environment-agnostic by design. Promotion is **a workflow choice, not a contract edit** — the same contract carries cleanly from dev to qa to prod. The platform raises the bar automatically as the target environment becomes more sensitive. + +**Approach A — One contract, one job per environment.** A single contract is referenced by multiple jobs in the CI workflow; the environment is passed by each job and interpolated at runtime. The contract itself never changes. ```yaml -# dev → qa: change one line -uses: acdl/pipelines/deploy.yaml@v1.6 -environment: qa # QA attestation + confidence >= 0.75 +# .github/workflows/deploy.yml — one job per environment, one shared contract +jobs: + dev: + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: + contract: .acdl/contract.yaml + environment: dev + qa: + needs: dev + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: + contract: .acdl/contract.yaml + environment: qa + prod: + needs: qa + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: + contract: .acdl/contract.yaml + environment: prod ``` +**Approach B — One job per environment, environment-specific contracts.** When inputs genuinely differ per environment (different capacity, different config), each job points at its own contract file. The pipeline, policy, and confidence model stay identical. + +```yaml +jobs: + dev: + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: + contract: .acdl/contract-dev.yaml + qa: + needs: dev + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: + contract: .acdl/contract-qa.yaml + prod: + needs: qa + uses: acdl/.github/workflows/deploy.yml@v1.6 + with: + contract: .acdl/contract-prod.yaml +``` + +Whichever approach a team picks, the platform applies the same rising bar: + | Environment | What the platform adds | |---|---| | dev | Confidence ≥ 0.50, fully autonomous | @@ -227,7 +267,7 @@ environment: qa # QA attestation + confidence >= 0.75 - **Separation of duties is enforced** — the QA approver cannot be the prod approver. *(Design shipped; wiring for qa/prod/dr is planned.)* - **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit. -> **Speaker notes:** The one-field promotion is the DX win; the automatic threshold + attestation raise is the safety win. They are the same feature. For leadership: this is how the platform makes "move fast" and "be safe" stop being a trade-off — the speed is in the ergonomics, the safety is in the gates the consumer can't bypass. +> **Speaker notes:** Promotion is a workflow choice, not a contract mutation — this matters because it means a promotion can be reviewed as a *diff in the workflow*, not as a rewritten contract. Approach A (one contract, environment passed by the job) keeps the single source of truth; Approach B (environment-specific contracts) lets teams whose inputs genuinely vary keep that variation explicit and reviewable. For leadership: the DX win is that the contract stays stable across environments; the safety win is that the platform raises the threshold and attestation bar automatically based on the target environment the job declares. The consumer can't bypass the gates — they pick *which* environment to target, and the platform applies the right bar. ---