docs(P44): leadership presentation decks + Marp synthesis + README
Add two leadership-facing presentation decks for senior leadership (CTO, Head of Cloud, Head of Infrastructure, Head of DevOps): 1. How the Platform Works — 14 slides covering the contract-driven model, zero-trust, computed safety, policy enforcement, secure-by-default, immutable audit, HITL, observability, platform-managed environments, portability, and an honest shipped-vs-planned roadmap. 2. The Developer Experience — 14 slides covering two consumer surfaces, the 5-line contract, no platform code, versioned releases, instant feedback, deploy outputs, local reproducibility, friendly onboarding, safe promotion (one contract + per-env CI jobs), safe decommission, self-service module catalog, and the leadership outcome. Each deck has two forms: - Full markdown (source of truth) with speaker notes + mermaid code blocks - Marp deck (lean, no speaker notes, embedded PNG diagrams) for presentation Includes a README documenting the 3-step slide creation process: (full markdown → Marp synthesis → PPTX export) with conventions, build commands, and maturity framing rules. ---ci--- phase: 44 milestone: v1.9 status: complete requirements: covered: [] partial: [] ---/ci---
This commit is contained in:
Jon Chery
@@ -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:** `<deck-name>.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:** `<deck-name>-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 ``.
|
||||
- **`<!-- _class: title -->` + `<!-- _paginate: false -->`** on title and
|
||||
closing slides for the dark-background title style.
|
||||
- **Maturity badges** using inline spans:
|
||||
`<span class="badge today">Available today</span>`
|
||||
`<span class="badge planned">Planned</span>`
|
||||
- **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/<deck-name>-marp.md \
|
||||
-o <output-path>.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/<deck>-<slide>-<name>.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 `` (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/<deck-name>-marp.md \
|
||||
-o <output-path>.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/<deck-name>-marp.md \
|
||||
-o <output-path>.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 `<deck-name>.md` following the
|
||||
`## Slide N — Title` + `> **Speaker notes:**` structure. This is the
|
||||
source of truth.
|
||||
2. **Extract any mermaid diagrams** into `assets/mmd/<deck-name>-<slide>-<name>.mmd`
|
||||
and render them to `assets/png/` (command above).
|
||||
3. **Synthesize the Marp deck** as `<deck-name>-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('<output>.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 |
|
||||
@@ -0,0 +1,7 @@
|
||||
flowchart LR
|
||||
A["Technical developer"] --> C["Contract YAML"]
|
||||
B["Citizen developer<br/>(non-technical)"] --> D["Declares intent<br/>in natural language"]
|
||||
D --> E["Agent produces<br/>the contract"]
|
||||
C --> F["Same platform:<br/>resolve → check → plan →<br/>policy → confidence → apply"]
|
||||
E --> F
|
||||
F --> G["Same safety guarantees,<br/>same audit trail"]
|
||||
@@ -0,0 +1,5 @@
|
||||
flowchart LR
|
||||
A["1. App code<br/>(top level of the repo)"] --> D["Push to main"]
|
||||
B["2. Contract<br/>(.acdl/contract.yaml)"] --> D
|
||||
C["3. CI definition<br/>(.github/workflows/deploy.yml<br/>— one 'uses:' line)"] --> D
|
||||
D --> E["Platform does the rest"]
|
||||
@@ -0,0 +1,6 @@
|
||||
flowchart LR
|
||||
A["Consumer repo<br/>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<br/>into the workspace| C["Platform code<br/>(modules, adapters, schemas)"]
|
||||
C --> B
|
||||
B -->|runs the pipeline against<br/>the consumer's contract| D["Consumer's resources in AWS"]
|
||||
@@ -0,0 +1,3 @@
|
||||
flowchart LR
|
||||
A["Consumer<br/>writes a contract"] --> B["Platform resolves,<br/>compiles, checks,<br/>deploys, records"]
|
||||
B --> C["Resources running in AWS<br/>+ tamper-evident evidence"]
|
||||
@@ -0,0 +1,10 @@
|
||||
flowchart TD
|
||||
subgraph R1 [" "]
|
||||
direction LR
|
||||
A["Consumer<br/>contract"] --> B["Validate<br/>contract"] --> C["Resolve to<br/>target stack"] --> D["Security<br/>checks"] --> E["Infrastructure<br/>plan"]
|
||||
end
|
||||
subgraph R2 [" "]
|
||||
direction LR
|
||||
F["Policy<br/>checks"] --> G["Confidence<br/>signal"] --> H["Evidence<br/>event"] --> I["Infrastructure<br/>apply"]
|
||||
end
|
||||
E --> F
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
@@ -0,0 +1 @@
|
||||
{ "args": ["--no-sandbox", "--disable-setuid-sandbox"] }
|
||||
@@ -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; }
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# How the Platform Works
|
||||
|
||||
**ACDL — Agentic Cloud Delivery Platform**
|
||||
|
||||
Senior Leadership Briefing
|
||||
|
||||
<style>
|
||||
section.title h1 { font-size: 42px; }
|
||||
</style>
|
||||
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
- **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. <span class="badge today">Available today (GitHub Actions)</span> <span class="badge planned">Planned: all runners</span>
|
||||
- **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`) <span class="badge today">Available today</span>
|
||||
- **Cloud security posture** (Wiz adapter) — translates cloud security findings into the same normalized record <span class="badge today">Adapter ready</span>
|
||||
- **Kubernetes-native policy** (Kyverno adapter) — ready for the GitOps reconciler <span class="badge today">Adapter ready</span>
|
||||
|
||||
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.** <span class="badge today">Available today</span>
|
||||
|
||||
- **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 <span class="badge today">Available today</span>
|
||||
- **Tiered storage:** cold, tamper-proof source of truth (S3 Object Lock, 7-year retention) + a hot query index <span class="badge today">Outbox shipped</span> <span class="badge planned">Full ledger: planned</span>
|
||||
- **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.** <span class="badge today">Design shipped</span> <span class="badge planned">Wiring: planned</span>
|
||||
- **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.** <span class="badge today">Available today</span>
|
||||
|
||||
- **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). <span class="badge today">Available today</span> <span class="badge planned">Self-service: planned</span>
|
||||
|
||||
---
|
||||
|
||||
# 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.* <span class="badge today">1 adapter: Terraform</span> <span class="badge planned">OpenTofu / Pulumi / K8s</span>
|
||||
- **Forge-agnostic contract ingestion.** The platform Lambda reads a configurable API base for GitHub or Gitea. <span class="badge today">Available today</span>
|
||||
- **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. <span class="badge planned">Future capability</span>
|
||||
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# Roadmap: Shipped vs. Planned
|
||||
|
||||
<style>
|
||||
section { font-size: 20px; }
|
||||
</style>
|
||||
|
||||
**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)
|
||||
@@ -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; }
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# The Developer Experience
|
||||
|
||||
**ACDL — Agentic Cloud Delivery Platform**
|
||||
|
||||
Senior Leadership Briefing
|
||||
|
||||
<style>
|
||||
section.title h1 { font-size: 42px; }
|
||||
</style>
|
||||
|
||||
---
|
||||
|
||||
# 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.**
|
||||
|
||||
|
||||
|
||||
- **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.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
<span class="badge planned">Skill catalog + real agent runtime: planned</span>
|
||||
|
||||
---
|
||||
|
||||
# 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.**
|
||||
|
||||
|
||||
|
||||
- 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 <span class="badge today">Available today</span>
|
||||
- **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 <span class="badge today">Available today</span>
|
||||
|
||||
---
|
||||
|
||||
# Instant Feedback
|
||||
|
||||
Developers see **what the platform is doing**, in real time, in their own run logs. <span class="badge today">Available today</span>
|
||||
|
||||
- **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. <span class="badge today">Available today</span>
|
||||
|
||||
- **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. <span class="badge today">Available today</span>
|
||||
|
||||
- `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. <span class="badge today">Available today</span>
|
||||
|
||||
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.
|
||||
|
||||
<span class="badge planned">Citizen developer onboarding path: planned</span>
|
||||
|
||||
---
|
||||
|
||||
# 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 }
|
||||
```
|
||||
|
||||
<style>
|
||||
section { font-size: 19px; }
|
||||
pre { font-size: 13px; }
|
||||
code { font-size: 13px; }
|
||||
</style>
|
||||
|
||||
---
|
||||
|
||||
# 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 <span class="badge today">Design shipped</span> <span class="badge planned">Wiring: planned</span>
|
||||
- **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. <span class="badge today">Available today</span>
|
||||
|
||||
```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. <span class="badge today">Available today</span>
|
||||
|
||||
- **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 <span class="badge planned">Planned</span>
|
||||
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, HIPAA, DORA controls will wire in <span class="badge planned">Planned</span>
|
||||
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
<!-- _paginate: false -->
|
||||
|
||||
# The Outcome for Leadership
|
||||
|
||||
<style>
|
||||
section { font-size: 22px; }
|
||||
</style>
|
||||
|
||||
- **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.
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user