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

The Developer Experience

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

---

Slide 1 — Title

The consumer surface is intentionally tiny. The platform's surface is large and opinionated.

Speaker notes: Brief introduction — this deck covers who uses the platform and how fast/safe they ship, not the internal mechanics (that's the companion deck). Set the frame: velocity without sacrificing safety, and security/observability/compliance as platform defaults rather than per-team effort.

---

Slide 2 — Where ACDL Sits in Your World

Story beat: Here's who uses the platform and where the boundary is.

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.

flowchart TD
    U1["Anything upstream<br/>(IDE / agentic SDLC / vibe coding)"] --> T["Technical developer<br/>writes app + contract"]
    U1 --> C["Citizen developer<br/>declares intent"]
    T --> K["Contract YAML"]
    C --> AI["An AI agent maps intent<br/>to a reviewed-skill contract"]
    AI --> K
    K --> ACDL["ACDL — infrastructure only<br/>resolve → check → plan → policy<br/>→ confidence → evidence → apply"]
    ACDL --> AWS["AWS resources provisioned + governed"]

• 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. Agentic
• 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 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.

---

Slide 3 — The Contract — The Entire Consumer Surface

Story beat: Now let's look at what a consumer actually writes — it's tiny.

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: module, environment, inputs
3. A one-line CI definition — a thin uses: wrapper pointing at a versioned platform workflow

uses: acdl/pipelines/deploy.yaml@v1.6
module: microservice
environment: dev
inputs:
  cpu: 256
  memory: 512
  desired_count: 2
  port: 8080

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

Story beat: Once you push, here's what you see — in real time, in your own logs.

Developers see what the platform is doing, in real time. Testing

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

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.

---

Slide 5 — Versioned, Predictable Releases

Story beat: You control when you absorb platform improvements — no surprise upgrades.

Consumers control when they absorb platform improvements. Testing

• Floating MAJOR + MINOR tags (e.g. @v1.6) — 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 a consumer has.
• 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

Story beat: First impressions matter — the platform fails gracefully, not opaquely.

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

When no environment is bound, the platform emits a user-friendly onboarding prompt instead of failing opaquely. 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.

Citizen developer onboarding 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 7 — Safe Promotion Path

Story beat: 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.

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.

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

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 }

Whichever approach a team picks, the platform applies the same rising bar:

Environment	What the platform adds	Maturity
dev	Confidence ≥ 0.50, fully autonomous	Testing
qa	QA human attestation + confidence ≥ 0.75	Planned
prod	SRE human attestation + confidence ≥ 0.90	Planned
dr	SRE human attestation + confidence ≥ 0.95 + a disaster-recovery drill reference	Planned

• 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

Story beat: Tearing down is as deliberate as deploying — and just as gated.

Tearing down a stack is as deliberate as deploying one. Testing

uses: acdl/.github/workflows/deploy.yml@v1.8
with:
  contract: .acdl/contract.yaml
  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

Story beat: You don't author infrastructure — you pick from pre-built, security-reviewed building blocks.

Developers pick from pre-built, security-reviewed building blocks. Testing

• 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. Planned Agentic
• Compliance extension points — each module lists where GDPR, SOX, SOC2, DORA controls will wire in. 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 10 — The Desired Outcomes

Story beat: 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. Agentic

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.

---

Appendix — Contents

For deep dives — these slides cover details omitted from the main 10.

1. A1 — The Citizen Developer Experience (full)
2. A2 — No Platform Code, No Cloning (detail)
3. A3 — Local Reproducibility (detail)
4. A4 — The Road to the North Star (phased roadmap)
5. A5 — Glossary

Speaker notes: These are backup slides for Q&A. Use them when the audience asks for the detail behind a main-slide claim. Don't walk through them in the main talk unless time permits.

---

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. Think of this as vibe coding on a laptop — the consumer describes what they want; an AI agent turns that into a contract that the platform treats identically to a senior engineer's.

• 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. Agentic
• 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.

Skill catalog + real agent runtime: planned Agentic

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. The "vibe coding on a laptop" framing is intentional — it meets the citizen developer where they already are, but every submission still passes the same safety envelope. 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.

---

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.

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).
• 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.

Speaker notes: The Head of Cloud cares about this: there is no "platform code in every consumer repo" problem. The version-pinned uses: line is the only coupling, and it's a coupling that updates itself within the line.

---

A3 — Local Reproducibility

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

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

Speaker notes: This is the "no surprises before you push" story. A consumer can validate their contract offline, run the plan offline, and only push when they're confident. The same declarative contract drives both the local tooling and CI — there's no "works on my machine, fails in CI" gap.

---

A4 — The Road to the North Star

Proposed phasing — not formally planned.

flowchart LR
    P1["Phase 1<br/>Core platform<br/>(contract, catalog, evidence)"] --> P2["Phase 2<br/>Safe promotion<br/>qa/prod/dr wiring"]
    P2 --> P3["Phase 3<br/>Agentic surface<br/>(skill catalog + agents)"]
    P3 --> P4["Phase 4<br/>North star<br/>citizen developer GA"]

Speaker notes: This is a proposed phasing, not a formally committed plan — call that out explicitly. Phase 1 is what's tested today. Phase 2 is the next milestone (qa/prod/dr wiring). Phase 3 introduces the agentic surface. Phase 4 is the north star: citizen developer GA on the same safety envelope. Use this only when an audience member asks "how do you get from here to there."

---

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

Speaker notes: Keep this slide in your back pocket for the audience member who asks "what does ABAC actually mean?" Don't read it aloud.