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

# The Developer Experience

> **Audience:** Senior Leadership, CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
> **Length:** ~15 minutes · 14 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:** "Available today" = shipped and verified. "Planned" = on the roadmap, not yet shipped.

---

## Slide 1 — Two Consumer Surfaces, One Platform

The platform serves **two kinds of consumer** through two coordinated interfaces — but both converge on the **same contract, the same policy envelope, and the same evidence stream.**

```mermaid
flowchart TD
    A["Technical developer"] --> C["Contract YAML"]
    B["Citizen developer<br/>(non-technical)"] --> D["Declares intent in<br/>natural language"]
    D --> E["Agent produces<br/>the contract"]
    C --> F["Same platform:<br/>resolve → check → plan → policy<br/>→ confidence → evidence → apply"]
    E --> F
    F --> G["Same safety guarantees,<br/>same audit trail"]
```

- **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 agent produces a contract that passes the **same** safety envelope as a senior engineer's.

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 leadership takeaway: we expand who can ship safely without lowering the bar.

---

## Slide 2 — What a Developer Actually Does

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

```mermaid
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"]
```

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.

> **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. For the Head of DevOps: this is the lever for throughput — the bottleneck moves off the platform team's ticket queue.

---

## Slide 3 — 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 — it is the mandatory release gate).
- Agents are **stateless** — all state lives in the platform. The platform does not run the skill blindly; it trusts and **always verifies** on the platform side.
- The agent's trace and submission confidence are captured in the contract (`profile: agentic`), so a reviewer can see *how* the contract was produced.
- **Initial skill catalog:** web API, worker, scheduled job, static asset, basic observability bootstrap. *(Catalog is planned; the agentic surface is on the roadmap.)*

> **Speaker notes:** Be honest about maturity: the *mechanism* (agent → contract → same pipeline) is designed and the stub was proven in the v1.0 demo; the full skill catalog and real agent runtime are planned. But the design point matters to leadership now: we are building for a world where more of the org can ship safely, not where more of the org has to become a platform engineer.

---

## Slide 4 — 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
  env:
    LOG_LEVEL: info
```

Four fields:

| Field | Meaning |
|---|---|
| `uses` | The central pipeline, pinned to a versioned tag |
| `module` | A name from the module catalog |
| `environment` | `dev`, `qa`, `prod`, or `dr` |
| `inputs` | The handful of values that vary per deployment |

An invalid contract (missing field, unknown module, wrong type) **fails fast at validation** with a clear error — not an opaque failure three stages in.

> **Speaker notes:** The contract is the API. It is deliberately tiny so that it can be reviewed, validated, and audited. For leadership: this is what makes "declare intent" concrete — it's a one-screen file, not a 300-line Terraform root module.

---

## Slide 5 — No Platform Code, No Cloning

Consumers `uses:` a **versioned** central workflow. The platform fetches itself at run time. The consumer **never touches platform internals.**

```mermaid
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"]
```

- The consumer's CI definition is a thin wrapper — one `uses:` line pointing at a versioned tag.
- 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.
- The consumer **never clones the platform repo, never invokes platform scripts locally** (optional `--check-only` validation is available but not required for the happy path).

> **Speaker notes:** The Head of Cloud cares about this: there is no "platform code in every consumer repo" problem. When the platform ships a fix, every consumer on a floating MAJOR.MINOR tag gets it on their next run — no per-repo upgrade project.

---

## Slide 6 — Versioned, Predictable Releases

Consumers control **when** they absorb platform improvements.

- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer on `@v1.6` automatically receives patch updates within the 1.6 line.
- **Semantic versioning with a clear contract:** interface changes → MAJOR, behavior changes → MINOR, lifecycle fixes → 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.
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags. *(Available today.)*

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

Developers see **what the platform is doing**, in real time, in their own run logs.

- **Streamed output by default** — the infrastructure plan, policy-check results, and each `PolicyCheckResult` record (severity, rule ID, pass/fail) flow to stdout. *(Available today.)*
- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard. *(Available today.)*
- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque, manual-debugging exercise.**
- **A `--quiet` mode** suppresses streaming for log-only contexts.

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

---

## Slide 8 — 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.

- **Human-readable connection strings** posted as a structured GitHub PR comment / job summary. *(Available today.)*
- **Runtime-injectable values** written to encrypted Parameter Store (`SecureString`, KMS-encrypted, namespaced `/acdl/{env}/{contractId}/{output_name}`). *(Available today.)*
- **No raw secrets in logs** — the platform enforces this 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 — no separate `issues: write` scope on the consumer side. *(Available today.)*

> **Speaker notes:** 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.

---

## Slide 9 — Local Reproducibility

The entire CI pipeline runs **from the shell**, not just in CI.

- `scripts/run_ci.sh` mirrors the CI pipeline locally — the same three stages (lint → test → check-only) in sequence. Exits 0 with "CI PIPELINE OK." *(Available today.)*
- `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. *(Available today.)*
- `--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 the GitHub and Gitea workflows implement. A test asserts conformance.

> **Speaker notes:** This is the "no 'works on my machine' for CI" slide. A developer can reproduce the exact CI behavior locally before pushing. For the Head of Engineering: this shrinks the PR-cycle time because failures are caught pre-push, and it makes the pipeline itself a reviewable artifact (the YAML contract), not tribal workflow code.

---

## Slide 10 — Friendly Onboarding

First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully.

- When a consumer pipeline runs for the first time and **no environment is bound**, the platform detects this and emits a **user-friendly onboarding prompt** instead of failing opaquely. *(Available today.)*
- The prompt tells the consumer:
  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. *(Developer path shipped; citizen developer path planned.)*

> **Speaker notes:** This looks like a small thing; it's actually a cultural one. The platform's posture is "help me get started," not "you should have known." For the Head of DevOps: this is what drives adoption. Platforms that fail opaquely on first run get routed around.

---

## Slide 11 — Safe Promotion Path

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
# .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 |
| qa | QA human attestation + confidence ≥ 0.75 |
| prod | SRE human attestation + confidence ≥ 0.90 |
| dr | SRE human attestation + confidence ≥ 0.95 + a disaster-recovery drill reference |

- **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. *(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:** 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.

---

## Slide 12 — Safe Decommission

Tearing down a stack is **as deliberate as deploying one** — and just as gated.

```yaml
# Consumer's deploy workflow call
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** *(available today)*:

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** (resolve with `deletion_protection: false`, plan + apply) → **SRE approves.**
3. **Zero all counts + destroy** (the platform zeroes every scalable count, plan + apply) → **a second SRE approves.**
4. **Confirmation** — the platform confirms the stack is destroyed.

**After decommission:**

- 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.
- Uptime monitoring is **not** automatically destroyed — it can be left running to watch the decommissioned endpoints go dark, or destroyed separately.

> **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 13 — Self-Service Module Catalog

Developers pick from **pre-built, security-reviewed building blocks** — they don't author infrastructure from scratch.

- **Primitives** — single-purpose resources (S3, VPC, ECS cluster, ECS service, IAM role, load balancer, container registry, CloudFront, WAF, RDS). Each has documented inputs, outputs, usage, compliance extension points, and versioning. *(Available today.)*
- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + load balancer + registry). *(Available today.)*
- **Validated examples per module** — every module ships `simple.yaml` + `complex.yaml` + variation files, validated against the contract schema in CI. Examples cannot drift from the schema silently. *(Available today.)*
- **Auto-promotion of patterns** — a thin-composition layer is auto-promoted to the catalog after 3 observed usages. *(Mechanism planned.)*
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, HIPAA, DORA controls will wire in. *(Compliance milestone is planned.)*

> **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 14 — The Outcome for Leadership

What this platform delivers to the organization:

- **Velocity without sacrificing safety.** The speed is in the ergonomics (a 5-line contract, a one-line `uses:`); the 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.
- **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.

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