acdl/docs/presentations/the-developer-experience-marp.md

---
marp: true
theme: default
paginate: true
size: 16x9
header: "The Developer Experience"
footer: "Internal"
style: |
  section {
    font-family: "Akkurat Pro", "Helvetica Neue", "Arial", sans-serif;
    font-size: 22px;
    color: #1B1B1B;
  }
  h1 { color: #D6002A; font-size: 34px; margin-bottom: 0.3em; }
  h2 { color: #D6002A; font-size: 26px; margin-bottom: 0.2em; }
  section.title { background: #1B1B1B; color: #fff; border-top: 8px solid #D6002A; }
  section.title h1 { color: #fff; }
  table { font-size: 18px; width: 100%; }
  th { background: #F0F0F0; }
  blockquote { border-left: 4px solid #D6002A; color: #2E2E2E; font-size: 20px; }
  pre { font-size: 14px; line-height: 1.3; }
  code { font-size: 14px; }
  img { display: block; margin: 0 auto; max-height: 280px; }
  em.story { color: #6B7280; font-size: 16px; font-style: italic; }
  .badge {
    display: inline-block; padding: 2px 8px; border-radius: 4px;
    font-size: 14px; font-weight: 600;
  }
  .testing { background: #DBEAFE; color: #1E3A5F; }
  .planned { background: #fef3c7; color: #78350f; }
  .agentic { background: #EDE9FE; color: #4C1D95; }
---

<!-- _class: title -->
<!-- _paginate: false -->

# The Developer Experience

### Agentic Cloud Delivery Platform

<style>
section.title h1 { font-size: 44px; margin-bottom: 0.1em; }
section.title h3 { color: #F0F0F0; font-weight: 400; font-size: 22px; margin-top: 0; }
</style>

---

# Where Agentic Cloud Delivery (ACDL) Sits in Your World

<em class="story">Here's who uses the platform and where the boundary is.</em>

![w:1100](assets/png/developer-experience-01b-scope-boundary.png)

- **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** — your IDE, an agentic SDLC, or vibe coding on a laptop. ACDL doesn't care how the contract was produced
- **ACDL is infrastructure only** — it provisions and governs AWS resources. Application deployment is upstream

---

# The Contract — The Entire Consumer Surface

<em class="story">Now let's look at what a consumer actually writes — it's tiny.</em>

Three things. That is the entire consumer-side surface.

<img src="assets/png/developer-experience-02-what-dev-does.png" style="float: right; width: 38%; margin-left: 20px; margin-bottom: 10px;" />

- **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

```yaml
id: msvc
name: microservice
environment: dev
infrastructure:
  microservice:
    version: "1.0.0"
    inputs:
      cpu: 256
      memory: 512
      desired_count: 2
      port: 8080
```

- **3. A one-line CI definition** — a thin `uses:` wrapper pointing at a versioned platform workflow
- The developer does **not**: write infrastructure modules, clone the platform repo, hold cloud credentials, or maintain a state backend

---

# The Developer Feedback Loop

<em class="story">Once you push, here's what you see — in real time, in your own logs.</em>

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
- **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 in encrypted Parameter Store** — KMS-encrypted, namespaced, **no raw secrets in logs**
- **Errors become GitHub issues, automatically** — a failed deploy opens an issue on the platform repo

---

# Versioned, Predictable Releases

<em class="story">You control when you absorb platform improvements — no surprise upgrades.</em>

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
- **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

---

# Friendly Onboarding

<em class="story">First impressions matter — the platform fails gracefully, not opaquely.</em>

First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. <span class="badge testing">Testing</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.

<span class="badge planned">Citizen developer onboarding path: planned</span>

---

# Safe Promotion Path

<em class="story">Promotion is a workflow choice, not a contract edit — and the bar rises automatically.</em>

The contract is environment-agnostic. The platform raises the bar automatically.

![w:1000](assets/png/developer-experience-04-promotion-journey.png)

<table style="width: 100%; border: none;">
<tr>
<td style="width: 50%; vertical-align: top; border: none; padding-right: 12px;">

**Approach A — One contract, one job per environment.** Environment passed by each job.

```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 }
```

</td>
<td style="width: 50%; vertical-align: top; border: none; padding-left: 12px;">

**Approach B — Environment-specific contracts.** When inputs differ per environment.

```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 }
```

</td>
</tr>
</table>

<style>
section { font-size: 16px; }
pre { font-size: 10px; line-height: 1.2; }
code { font-size: 10px; }
td { font-size: 14px; }
</style>

---

# Safe Decommission

<em class="story">Tearing down is as deliberate as deploying — and just as gated.</em>

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; the CR must be `approved` and match the consumer repo
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.

---

# Self-Service Module Catalog

<em class="story">You don't author infrastructure — you pick from pre-built, security-reviewed building blocks.</em>

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 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** — 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>

---

<!-- _class: title -->
<!-- _paginate: false -->

# The Desired Outcomes

<em class="story">Here's what this delivers to the organization.</em>

- **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.
- **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 — 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>

---

<!-- _class: title -->
<!-- _paginate: false -->

# Appendix

<em class="story">For deep dives — these slides cover details omitted from the main 10.</em>

**Contents:**

1. The Citizen Developer Experience (full)
2. No Platform Code, No Cloning (detail)
3. Local Reproducibility (detail)
4. The Road to the North Star (phased roadmap)
5. Glossary
6. Operating Model & Cost
7. Verified by Construction

---

# A1 — 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 AI 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> <span class="badge agentic">Agentic</span>

---

# A2 — 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

---

# A3 — Local Reproducibility

The entire CI pipeline runs **from the shell**, not just in CI. <span class="badge testing">Testing</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

---

<!-- _class: title -->
<!-- _paginate: false -->

# A4 — The Road to the North Star

*Proposed phasing — not formally planned.*

![w:1100](assets/png/road-to-north-star.png)

---

# A5 — Glossary

| Term | Meaning |
|---|---|
| **OIDC** | OpenID Connect — federation protocol for short-lived tokens, no long-lived credentials |
| **ABAC** | Attribute-Based Access Control — access scoped by resource tags + repo identity, not roles |
| **CMK** | Customer-Managed Key — per-stack encryption key, 90-day rotation, no shared keys |
| **CMDB** | Configuration Management Database — validates change requests for decommission |
| **RPO** | Recovery Point Objective — RPO = 0 means evidence is written synchronously, no data loss |
| **HITL** | Human-in-the-Loop — deliberate human attestation required for qa/prod/dr environments |
| **VCS** | Version Control System — the git hosting platform (GitHub, Gitea, GitLab) |
| **NFR** | Non-Functional Requirement — encryption, tagging, observability standards |
| **IR** | Intermediate Representation — the engine-agnostic stack definition between contract and Terraform |

---

# A6 — Operating Model & Cost

<style>
section { font-size: 18px; }
table { font-size: 16px; }
</style>

ACDL runs at **zero cloud cost** for day-to-day development. AWS spend was measured via Cost Explorer (`COST.md`, 2026-07-28):

| Metric | Value |
|--------|-------|
| Total spend (8 days) | **$0.001883** |
| Daily average | $0.000235 |
| Projected monthly | ~$0.007 |
| Peak day | 2026-07-27 ($0.000867) |

- **S3 dominates** (98.8%, terraform state bucket) — no compute (ECS/Lambda) ran because v1.0→v1.10 was plan-only for IAM-gated capabilities
- **Local emulators are the primary tier** — the full pipeline runs in-process, no AWS credentials, no Checkov, no DynamoDB. <span class="badge testing">Testing</span>
- **Live-AWS verification is milestone-scoped, then torn down.** The v1.11 lifecycle pipeline ran apply→modify→destroy for every module, then tore down to zero-cost (D-096). The pipeline now **defaults to plan-only** on every PR; `ACDL_LIFECYCLE_MODE=full` overrides to apply→destroy for milestone verification (REQ-134, v1.12).
- **Cost drivers** are spike-scoped: Terraform plan reads (free), S3 state storage (cents), DynamoDB outbox (cents). No running infrastructure between milestones.

**Pre-mortem (`PRE_MORTEM.md`):** failure modes were pre-mortemed before the leadership pitch. The v1.10 decay incident (diff-scoped VERIFY missed 7 adapter defects) is the root pattern: *a claim outruns the verification that backs it.* Four forward failure modes + structural mitigations (regression-tested IAM baseline, mandatory teardown, verified-only deck claims, honest scope).

---

<!-- _class: title -->
<!-- _paginate: false -->

# A7 — Verified by Construction

<em class="story">The v1.11 architecture makes "Verified" a structural property, not a claim.</em>

<style>
section { font-size: 18px; }
</style>

Two architectural pillars:

- **The stateless adapter (918 → ~80 lines).** The Terraform adapter was a 918-line monolith with 3 constant tables and 39 type-specific branches. It is now a ~80-line **stateless assembler**: it owns no module content — no resource shape, no nested HCL blocks, no defaults. Each L1 module ships a real `terraform/` module dir owning its shape, nested blocks, and defaults. The adapter reads the registry and emits `module "x" { source = ... }` blocks. A new module is a new terraform dir, not a code change. *(The v1.12 P67 fix closed a dedup defect for multi-resource L1s — ecs-service, alb; CAP-013 now Verified.)*
- **Pipeline-driven lifecycle testing.** A `modules-lifecycle` pipeline matrix-runs each L1 and L2 module's contracts through apply→modify→destroy against live AWS. **The "test" = the pipeline cell going green.** Defaults to **plan-only** on every PR (fast, no AWS mutation, no cost); `ACDL_LIFECYCLE_MODE=full` overrides to the real apply→destroy for milestone verification (REQ-134, v1.12). The regression gate (D-091) re-runs all 22 capabilities at milestone completion — **22/22 Verified** as of v1.12.

The v1.10 lesson is the negative space: a 918-line adapter with type-specific branches decayed silently. The ~80-line stateless adapter + the milestone regression gate are the structural fix.