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

marp, theme, paginate, size, header, footer, style

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

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>

---

Two consumer paths, one safety envelope

• Technical developer — owns app code + a contract + a thin CI definition
• Citizen developer — declares intent; an AI agent produces a contract that passes the same safety envelope
• Upstream is anything — IDE, agentic SDLC, or vibe coding. ACDL doesn't care how the contract was produced
• ACDL is infrastructure only — provisions and governs AWS resources. Application deployment is upstream

---

The platform at a glance

• You own the left edge — app code and a contract. That is the entire consumer surface
• The platform owns the middle — pipeline, catalog, adapter, environments, gates, evidence
• Two surfaces, one pipeline, one evidence stream — senior engineer and citizen dev converge on the same safety envelope
• The bar rises automatically — confidence signal + HITL gates scale with the target environment, not a ticket

---

Three things. The entire consumer 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

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 modules, clone the platform repo, hold cloud credentials, or maintain a state backend

---

See what the platform does, in real time

• Streamed output by default — the plan, policy results, and each check record flow to stdout
• PR comments after every successful pipeline stage — always know where you stand
• Clear, explainable halt reasons — a policy violation, an insufficient signal, or a missing attestation. Never opaque.
• Connection strings posted as PR comments — human-readable, no hunting. Runtime secrets go to encrypted Parameter Store, never to logs
• Errors become GitHub issues, automatically — a failed deploy opens an issue on the platform repo

---

Pick from pre-built, security-reviewed blocks

• Primitives — single-purpose resources (S3, VPC, ECS, IAM, ALB, ECR, CloudFront, WAF, RDS)
• Modules — composed patterns (static site with CDN + WAF; microservice with VPC + ECS + ALB + ECR)
• Validated examples per module — simple.yaml + complex.yaml, validated against the contract schema in CI
• Auto-promotion of patterns — after 3 observed usages Planned

---

The bar rises automatically with sensitivity

Environment	What the platform adds	Maturity
dev	Confidence ≥ 0.50, fully autonomous	—
qa	QA human attestation + confidence ≥ 0.75	Planned
prod	SRE human attestation + confidence ≥ 0.90	Planned
dr	SRE human attestation + confidence ≥ 0.95 + DR drill	Planned

• No staging environment — dev is the only autonomous environment
• Separation of duties — the QA approver cannot be the prod approver

---

Tearing down is as gated as deploying

<style> section { font-size: 22px; } pre { font-size: 13px; line-height: 1.2; } code { font-size: 13px; } </style>

uses: acdl/.github/workflows/deploy.yml@v1.12
with:
  contract: .acdl/contract.yml
  mode: decommission
  changeRequestId: "CHG0678912"

• Validate the change request — platform queries the CMDB; CR must be approved and match the consumer repo
• Two SRE human-attestation gates — disable protection → SRE approves → zero counts + destroy → second SRE approves
• Per-stack encryption key enters a grace window (default 30 days) so encrypted data remains recoverable

---

You control when you absorb improvements

• 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
• Pin to an exact version for 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 floating tags

---

Fails gracefully, not opaquely

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

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.

Citizen developer onboarding path: planned

---

The desired outcomes

• Velocity without sacrificing safety — speed in ergonomics, safety in unbypassable gates
• Security, observability, compliance as platform defaults — not per-team effort, not post-hoc remediation
• Auditability as a byproduct, not a project — every change traceable to a human attestation and a tamper-evident evidence event
• Blast radius contained by design — OIDC + ABAC, only your own tagged resources
• The bottleneck moves off the platform team's ticket queue — a merged change progresses without a platform engineer joining a thread
• Infrastructure as a utility, not a craft — consume, don't maintain
• A path to the citizen developer — same envelope, senior engineer or non-technical

---

Appendix

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

Skill catalog + real agent runtime: planned

---

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.

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

• 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

---

A4 — The Road to the North Star

Proposed phasing — not formally planned.

---

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

---

A6 — Operating Model & Cost

<style> section { font-size: 20px; } table { font-size: 18px; } </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)

• Local emulators are the primary tier — the full pipeline runs in-process, no AWS credentials
• Live-AWS verification is milestone-scoped, then torn down. 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): 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).

---

A7 — Verified by Construction

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

Two architectural pillars make "Verified" a structural property, not a claim:

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