continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity

docs(P71): polish leadership decks — action headlines, trim, 6 new diagrams (v1.13)

Browse Source 
Polish both leadership decks (how-the-platform-works + the-developer-experience)
across all 4 pipeline layers (source md, marp, html, talking points).

Story-arc restructure (per storytelling best practices):
- Intro ~10% / Body ~80% / Conclusion ~10%; 3-5 body points per deck
- One idea per slide; action headlines replace category names
- Before/after 2-slide sequence (problem -> north star) on platform deck
- Main 10 slides kept; detail pushed to expanded appendix (8 + 7)

Word reduction + natural flow:
- Remove all <em class="story"> transition lines (flow carried by headlines)
- Bullets <= 12 words, 3-4 per main slide (was 5-6)
- Cut parentheticals, sub-clauses, redundant restatements

Design + visuals:
- Larger fonts: body 22 -> 26px, h1 34 -> 40px, h2 26 -> 32px, blockquote 20 -> 24px
- 6 new mermaid diagrams -> PNGs:
  - platform-works-02-frictions (2x2 quadrant)
  - platform-works-03-north-star (before/after)
  - platform-works-07-zero-trust (OIDC + ABAC flow)
  - developer-experience-05-catalog (primitives -> modules)
  - developer-experience-07-decommission (6-node gate flow)
  - developer-experience-08-semver (floating/pinned/major timeline)
- At most 1 diagram per main slide; no diagrams on title/conclusion
- High contrast preserved, no animations, maturity badges intact

Verify:
- Marp renders both decks clean (HTML re-rendered, committed)
- Talking-points sections == Marp slide count per deck
- No stale "deploy-unverified" claims (only closed-status disclosure)
- 522 tests pass (no code touched; only docs/presentations/ files changed)
- 22/22 Verified framing preserved verbatim from v1.12

---ci---
project: acdl
phase: 71
milestone: v1.13
status: complete
---/ci---
This commit is contained in:
Jon Chery
2026-07-29 14:43:29 +00:00
parent 9aa9ece1df
commit 4b8577df2e
20 changed files with 1721 additions and 1791 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/presentations/the-developer-experience.md
+149 -147
View File
@@ -2,7 +2,7 @@
> **Subtitle:** Agentic Cloud Delivery Platform
> **Audience:** Senior Leadership, CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
> **Length:** ~15 minutes · 10 main + 6 appendix = 16 slides
> **Length:** ~15 minutes · 10 main + 7 appendix = 17 slides
> **Purpose:** Sell the developer experience and the citizen developer experience to tech leadership — velocity without sacrificing safety, and security/observability/compliance as platform defaults rather than per-team effort.
> **Maturity framing:** "Testing" = works internally, dev pilot-ready. "Planned" = on the roadmap. "Agentic" = involves AI agents or autonomous decision-making.
> **Re-verification (2026-07-29):** Every "Testing" claim in this deck was re-verified in v1.10 Phase 54 (D-093) and again in v1.11 via the pipeline-driven lifecycle tests (P59–P62). The headline E2E (contract → resolver → adapter → terraform init/validate/plan) passes against the live AWS account; the local emulating tier (Phase 53) runs the full E2E with no cloud credentials. **22/22 auto-verifiable capabilities Verified** (CAP-013 fixed in v1.12 P67 — the adapter's multi-resource L1 dedup defect is closed). The v1.11 lifecycle pipeline ran apply→modify→destroy against live AWS and was then torn down to zero-cost (D-096). See `.ciagent/CAPABILITY_INVENTORY.md` and `.ciagent/PRE_MORTEM.md`.
@@ -17,14 +17,10 @@ The consumer surface is intentionally tiny. The platform's surface is large and
---
## Slide 2 — Where Agentic Cloud Delivery (ACDL) Sits in Your World
Here's who uses the platform and where the boundary is.
## Slide 2 — Two consumer paths, one safety envelope
The platform serves **two kinds of consumer** through two coordinated paths — but both converge on the **same contract, the same policy envelope, and the same evidence stream.**
**Agentic Cloud Delivery (ACDL)** sits between upstream (anything that produces a contract) and downstream (AWS resources running + the consumer's image pipeline).
```mermaid
flowchart LR
subgraph UP ["Upstream — anything"]
@@ -49,27 +45,19 @@ flowchart LR
F --> G
```
- **Technical developer** — owns app code + a contract + a thin CI definition. Uses the full module catalog and inputs.
- **Citizen developer** — declares intent in plain language; an AI agent produces a contract that passes the **same** safety envelope as a senior engineer's. <span class="badge agentic">Agentic</span>
- **Upstream is anything** — your IDE, an agentic SDLC, or vibe coding on a laptop. ACDL doesn't care how the contract was produced.
- **Technical developer** — owns app code + a contract + a thin CI definition.
- **Citizen developer** — declares intent in plain language; an AI agent produces a contract that passes the **same** safety envelope. <span class="badge agentic">Agentic</span>
- **Upstream is anything** — IDE, agentic SDLC, or vibe coding. ACDL doesn't care how the contract was produced.
- **ACDL is infrastructure only** — it provisions and governs AWS resources. Application deployment is upstream.
The platform is **opinionated in what it accepts, regardless of who is declaring.** There is no "citizen developer mode" with weaker checks.
> **Speaker notes:** This is the thesis of the deck. The two surfaces are *parallel*, not a progression — a citizen developer doesn't "graduate" to the developer surface. Both produce a contract; both get the same treatment. The scope boundary matters: anything upstream of the contract is out of ACDL's concern — ACDL is the infrastructure layer that takes a contract and governs the AWS resources. The leadership takeaway: we expand who can ship safely without lowering the bar.
> **Speaker notes:** This is the thesis of the deck. The two surfaces are *parallel*, not a progression — a citizen developer doesn't "graduate" to the developer surface. Both produce a contract; both get the same treatment. The scope boundary matters: anything upstream of the contract is out of ACDL's concern. The leadership takeaway: we expand who can ship safely without lowering the bar.
---
## Slide 3 — The Contract — The Entire Consumer Surface
Now let's look at what a consumer actually writes — it's tiny.
## Slide 3 — Three things. The entire consumer surface.
Three things. That is the entire consumer-side surface.
1. **App code** — the consumer's service, at the top level of the repo
2. **A contract** — a single YAML file: id, name, environment, infrastructure
3. **A one-line CI definition** — a thin `uses:` wrapper pointing at a versioned platform workflow
```yaml
id: msvc
name: microservice
@@ -84,53 +72,166 @@ infrastructure:
port: 8080
```
The developer does **not**:
1. **App code** — the consumer's service, at the top level of the repo
2. **A contract** — a single YAML file: id, name, environment, infrastructure
3. **A one-line CI definition** — a thin `uses:` wrapper pointing at a versioned platform workflow
- 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 developer does **not**: write infrastructure modules, clone the platform repo, hold cloud credentials, or maintain a state backend.
> **Speaker notes:** Hold this slide. The audience should sit with how small the consumer surface is. Every item in the "does not" list is a category of toil the platform removes. The contract is the API — deliberately tiny so that it can be reviewed, validated, and audited. For the Head of DevOps: this is the lever for throughput — the bottleneck moves off the platform team's ticket queue.
---
## Slide 4 — The Developer Feedback Loop
Once you push, here's what you see — in real time, in your own logs.
## Slide 4 — See what the platform does, in real time
Developers see **what the platform is doing**, in real time. <span class="badge testing">Testing</span>
- **Streamed output by default** — the infrastructure plan, policy-check results, and each check record flow to stdout.
- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard.
- **Streamed output by default** — the plan, policy-check results, and each check record flow to stdout.
- **PR comments after every successful pipeline stage** — a developer always knows where they stand.
- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque debugging exercise.**
- **Connection strings posted as PR comments** — human-readable, no hunting. Runtime secrets go to encrypted Parameter Store (KMS-encrypted, namespaced), never to logs.
- **Errors become GitHub issues, automatically** — a failed deploy opens an issue on the platform repo. The consumer's only grant is the onboarding-granted Lambda-invoke permission — no separate `issues: write` scope on the consumer side.
- **Errors become GitHub issues, automatically** — a failed deploy opens an issue on the platform repo.
> **Speaker notes:** This directly answers "but developers hate platforms that hide what they're doing." The platform is opinionated about *what* runs, not *opaque* about *that* it runs. The PR-comment-after-each-stage pattern is a small thing that compounds into trust. The "errors become issues" point is a DX win that also helps the platform team — every consumer failure is a tracked, queryable artifact, not a lost log line. The Head of DevOps should hear: the platform closes the feedback loop, it doesn't just push a green/red status.
> **Speaker notes:** This directly answers "but developers hate platforms that hide what they're doing." The platform is opinionated about *what* runs, not *opaque* about *that* it runs. The PR-comment-after-each-stage pattern is a small thing that compounds into trust. The "errors become issues" point is a DX win that also helps the platform team — every consumer failure is a tracked, queryable artifact, not a lost log line.
---
## Slide 5 — Versioned, Predictable Releases
## Slide 5 — Pick from pre-built, security-reviewed blocks
You control when you absorb platform improvements — no surprise upgrades.
Developers pick from **pre-built, security-reviewed building blocks.** <span class="badge testing">Testing</span>
```mermaid
flowchart LR
subgraph PRIM ["Primitives"]
direction TB
P1["S3"]
P2["VPC"]
P3["ECS"]
P4["IAM"]
P5["ALB"]
P6["ECR"]
P7["CloudFront"]
P8["WAF"]
P9["RDS"]
end
subgraph MOD ["Modules — composed patterns"]
direction TB
M1["Static site\nCDN + WAF + S3"]
M2["Microservice\nVPC + ECS + ALB + ECR"]
end
PRIM --> MOD
```
- **Primitives** — single-purpose resources (S3, VPC, ECS, IAM, ALB, ECR, CloudFront, WAF, RDS), each with documented inputs/outputs and versioning.
- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + ALB + ECR).
- **Validated examples per module** — `simple.yaml` + `complex.yaml`, validated against the contract schema in CI. Examples cannot drift from the schema silently.
- **Auto-promotion of patterns** — auto-promoted to the catalog after 3 observed usages. <span class="badge planned">Planned</span> <span class="badge agentic">Agentic</span>
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, DORA controls will wire in. <span class="badge planned">Planned</span>
> **Speaker notes:** The catalog is what makes "declare intent" practical — you can only declare a module that exists. For leadership: the catalog is the leverage. One well-reviewed module serves every consumer; a fix to the module serves every consumer on the next run. This is the compounding asset.
---
## Slide 6 — The bar rises automatically with sensitivity
The contract is environment-agnostic. The platform raises the bar automatically.
```mermaid
flowchart LR
DEV["dev<br/>autonomous"] -->|raise the bar| QA["qa<br/>QA attests"]
QA -->|raise the bar| PROD["prod<br/>SRE attests"]
PROD -->|raise the bar| DR["dr<br/>SRE attests + DR drill"]
```
| Environment | What the platform adds | Maturity |
|---|---|---|
| dev | Confidence ≥ 0.50, fully autonomous | <span class="badge testing">Testing</span> |
| qa | QA human attestation + confidence ≥ 0.75 | <span class="badge planned">Planned</span> |
| prod | SRE human attestation + confidence ≥ 0.90 | <span class="badge planned">Planned</span> |
| dr | SRE human attestation + confidence ≥ 0.95 + DR drill reference | <span class="badge planned">Planned</span> |
- **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.
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit.
> **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. The DX win: the contract stays stable across environments; the safety win: the platform raises the threshold and attestation bar automatically based on the target environment. The consumer can't bypass the gates — they pick *which* environment to target, and the platform applies the right bar. Be honest about maturity: dev is tested and pilot-ready; qa/prod/dr wiring is planned.
---
## Slide 7 — Tearing down is as gated as deploying
Tearing down a stack is **as deliberate as deploying one.** <span class="badge testing">Testing</span>
```mermaid
flowchart LR
A["Validate CR\n(CMDB)"]
B["Disable\nprevent_destroy"]
C["SRE\napprove"]
D["Zero counts\n+ destroy"]
E["SRE\napprove"]
F["Key enters\ngrace window"]
A --> B --> C --> D --> E --> F
```
```yaml
uses: acdl/.github/workflows/deploy.yml@v1.12
with:
contract: .acdl/contract.yml
mode: decommission
changeRequestId: "CHG0678912"
```
A 2-step pipeline with **two SRE human-attestation gates**:
1. **Validate the change request** — the platform queries the CMDB and asserts the CR is `approved` and matches the consumer repo. No CR, no decommission.
2. **Disable deletion protection** → **SRE approves** → **Zero all counts + destroy** → **a second SRE approves.**
The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable.
> **Speaker notes:** The counter-argument to "deletion protection makes cleanup impossible" is this slide. Decommission is a first-class, gated, two-approval flow — not a lock with no key, and not an ungated `terraform destroy`. For the Head of Infrastructure: the CMDB validation means decommission is auditable, not just possible.
---
## Slide 8 — You control when you absorb improvements
Consumers control **when** they absorb platform improvements. <span class="badge testing">Testing</span>
- **Floating MAJOR + MINOR tags** (e.g. `@v1.12`) — a consumer automatically receives patch updates within the line.
```mermaid
flowchart LR
subgraph FLOAT ["@v1.12 — floating MAJOR+MINOR"]
direction LR
F1["v1.12.0"]
F2["v1.12.1"]
F3["v1.12.2"]
F1 --> F2 --> F3
end
subgraph PIN ["@v1.12.2 — pinned exact"]
direction LR
P1["v1.12.2"]
P2["v1.12.2"]
P3["v1.12.2"]
P1 --> P2 --> P3
end
subgraph MAJ ["@v1 — float MAJOR only"]
direction LR
M1["v1.12.0"]
M2["v1.13.0"]
M3["v1.14.0"]
M1 --> M2 --> M3
end
```
- **Floating MAJOR + MINOR tags** (e.g. `@v1.12`) — automatically receive patch updates within the line.
- **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 a consumer has.
- **Pin to an exact version** for maximum stability, or float on MAJOR only (`@v1`) to absorb new features on your 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.
> **Speaker notes:** This is the "no surprise upgrades" story. Leadership hears two things: (1) consumers aren't forced to chase the platform, (2) the platform isn't forced to support N forks of every workflow. The versioning discipline is what makes both true.
---
## Slide 6 — Friendly Onboarding
First impressions matter — the platform fails gracefully, not opaquely.
## Slide 9 — Fails gracefully, not opaquely
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. <span class="badge testing">Testing</span>
@@ -149,114 +250,15 @@ The pipeline then **exits without attempting a deployment** — no partial state
---
## Slide 7 — Safe Promotion Path
## Slide 10 — The desired outcomes
Promotion is a workflow choice, not a contract edit — and the bar rises automatically.
The contract is environment-agnostic. The platform raises the bar automatically.
```mermaid
flowchart LR
DEV["dev<br/>autonomous"] -->|raise the bar| QA["qa<br/>QA attests"]
QA -->|raise the bar| PROD["prod<br/>SRE attests"]
PROD -->|raise the bar| DR["dr<br/>SRE attests + DR drill"]
```
**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 itself never changes.
```yaml
jobs:
dev:
uses: acdl/.github/workflows/deploy.yml@v1.12
with: { contract: .acdl/contract.yml, environment: dev }
qa:
needs: dev
uses: acdl/.github/workflows/deploy.yml@v1.12
with: { contract: .acdl/contract.yml, environment: qa }
```
**Approach B — Environment-specific contracts.** When inputs genuinely differ per environment, 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.12
with: { contract: .acdl/contract-dev.yaml }
qa:
needs: dev
uses: acdl/.github/workflows/deploy.yml@v1.12
with: { contract: .acdl/contract-qa.yaml }
```
Whichever approach a team picks, the platform applies the same rising bar:
| Environment | What the platform adds | Maturity |
|---|---|---|
| dev | Confidence ≥ 0.50, fully autonomous | <span class="badge testing">Testing</span> |
| qa | QA human attestation + confidence ≥ 0.75 | <span class="badge planned">Planned</span> |
| prod | SRE human attestation + confidence ≥ 0.90 | <span class="badge planned">Planned</span> |
| dr | SRE human attestation + confidence ≥ 0.95 + a disaster-recovery drill reference | <span class="badge planned">Planned</span> |
- **No staging environment** — the design deliberately removes the "staging is basically prod but not really" anti-pattern. Dev is the only autonomous environment.
- **Separation of duties is enforced** — the QA approver cannot be the prod approver.
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit.
> **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 keeps the single source of truth; Approach B 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. Be honest about maturity: dev is tested and pilot-ready; qa/prod/dr wiring is planned.
---
## Slide 8 — Safe Decommission
Tearing down is as deliberate as deploying — and just as gated.
Tearing down a stack is **as deliberate as deploying one.** <span class="badge testing">Testing</span>
```yaml
uses: acdl/.github/workflows/deploy.yml@v1.12
with:
contract: .acdl/contract.yml
mode: decommission
changeRequestId: "CHG0678912"
```
A 2-step pipeline with **two SRE human-attestation gates**:
1. **Validate the change request** — the platform queries the CMDB and asserts the CR is `approved` and matches the consumer repo. No CR, no decommission.
2. **Disable deletion protection** → **SRE approves** → **Zero all counts + destroy** → **a second SRE approves.**
The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable. The key is permanently deleted only after the window expires.
> **Speaker notes:** The counter-argument to "deletion protection makes cleanup impossible" is this slide. Decommission is a first-class, gated, two-approval flow — not a lock with no key, and not an ungated `terraform destroy`. For the Head of Infrastructure: the CMDB validation means decommission is auditable, not just possible.
---
## Slide 9 — Self-Service Module Catalog
You don't author infrastructure — you pick from pre-built, security-reviewed building blocks.
Developers pick from **pre-built, security-reviewed building blocks.** <span class="badge testing">Testing</span>
- **Primitives** — single-purpose resources (S3, VPC, ECS, IAM, load balancer, container registry, CloudFront, WAF, RDS). Each has 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** — auto-promoted to the catalog after 3 observed usages. <span class="badge planned">Planned</span> <span class="badge agentic">Agentic</span>
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, DORA controls will wire in. <span class="badge planned">Planned</span>
> **Speaker notes:** The catalog is what makes "declare intent" practical — you can only declare a module that exists. For leadership: the catalog is the leverage. One well-reviewed module serves every consumer; a fix to the module serves every consumer on the next run. This is the compounding asset.
---
## Slide 10 — The Desired Outcomes
Here's what this delivers to the organization.
- **Velocity without sacrificing safety.** Speed is in the ergonomics (a simple 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 — captured during the deploy, not reconstructed for the audit.
- **Blast radius contained by design.** Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources. One consumer can never affect another.
- **The bottleneck moves off the platform team's ticket queue.** A merged change progresses through lower environments without a platform engineer joining a thread. The platform team invests in the platform, not in per-deployment hand-holding.
- **Infrastructure as a utility, not a craft.** Teams consume infrastructure, they don't maintain it — and the platform compounds value over time by learning from recurring patterns.
- **A path to the citizen developer.** The same safety envelope that serves a senior engineer will serve a non-technical consumer. <span class="badge agentic">Agentic</span>
- **Velocity without sacrificing safety.** Speed is in the ergonomics; safety is in the gates the consumer cannot bypass.
- **Security, observability, and compliance as platform defaults** — not per-team effort, not post-hoc remediation.
- **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.
- **Infrastructure as a utility, not a craft.** Teams consume infrastructure, they don't maintain it.
- **A path to the citizen developer.** The same safety envelope serves a senior engineer and a non-technical consumer. <span class="badge agentic">Agentic</span>
> **Speaker notes:** Close on the strategic frame. The platform is not "a CI/CD tool" — it is the organizational lever for shipping safely at the pace the business demands, with the security and audit posture the regulators require. Invite questions; the companion deck ("How the Platform Works") covers the internal mechanics in more depth.