---
marp: true
theme: default
paginate: true
size: 16x9
header: "ACDL — The Developer Experience"
footer: "Confidential · For Senior Leadership"
style: |
section {
font-family: "Inter", "Segoe UI", "Helvetica Neue", sans-serif;
font-size: 22px;
}
h1 { color: #1a365d; font-size: 34px; margin-bottom: 0.3em; }
h2 { color: #1a365d; font-size: 26px; margin-bottom: 0.2em; }
section.title { background: #1a365d; color: #fff; }
section.title h1 { color: #fff; }
table { font-size: 18px; width: 100%; }
th { background: #edf2f7; }
blockquote { border-left: 4px solid #3182ce; color: #2d3748; font-size: 20px; }
pre { font-size: 16px; line-height: 1.3; }
code { font-size: 16px; }
img { display: block; margin: 0 auto; max-height: 300px; }
.badge {
display: inline-block; padding: 2px 8px; border-radius: 4px;
font-size: 14px; font-weight: 600;
}
.today { background: #c6f6d5; color: #22543d; }
.planned { background: #fef3c7; color: #78350f; }
---
# The Developer Experience
**ACDL — Agentic Cloud Delivery Platform**
Senior Leadership Briefing
---
# Two Consumer Surfaces, One Platform
The platform serves **two kinds of consumer** through two coordinated interfaces — both converge on the **same contract, the same policy envelope, and the same evidence stream.**
- **Technical developer** — owns app code + a contract + a thin CI definition
- **Citizen developer** — declares intent in plain language; an agent produces a contract that passes the **same** safety envelope
The platform is **opinionated in what it accepts, regardless of who is declaring.** There is no "citizen developer mode" with weaker checks.
---
# What a Developer Actually Does
Three things. That is the entire consumer-side surface.
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
---
# 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)
- 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
---
# 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
```
An invalid contract **fails fast at validation** with a clear error — not an opaque failure three stages in.
---
# 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
---
# Versioned, Predictable Releases
Consumers control **when** they absorb platform improvements.
- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer automatically receives patch updates within the line Available today
- **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 Available today
---
# Instant Feedback
Developers see **what the platform is doing**, in real time, in their own run logs. Available today
- **Streamed output by default** — the infrastructure plan, policy-check results, and each check record (severity, rule ID, pass/fail) 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.**
- **A `--quiet` mode** suppresses streaming for log-only contexts
---
# 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. Available today
- **Human-readable connection strings** posted as a structured GitHub PR comment / job summary
- **Runtime-injectable values** written to encrypted Parameter Store (`SecureString`, KMS-encrypted, namespaced `/acdl/{env}/{contractId}/{output_name}`)
- **No raw secrets in logs** — enforced 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
---
# Local Reproducibility
The entire CI pipeline runs **from the shell**, not just in CI. Available today
- `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. A test asserts conformance
---
# Friendly Onboarding
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. Available today
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.
Both onboarding paths end in a **sandbox dev submission that must pass the confidence gate** before the consumer is promoted.
Citizen developer onboarding path: planned
---
# Safe Promotion Path
The contract is environment-agnostic by design. Promotion is **a workflow choice, not a contract edit** — the platform raises the bar automatically.
**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 never changes.
```yaml
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 — One job per environment, environment-specific contracts.** When inputs genuinely differ per environment, each job points at its own contract file.
```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 }
```
---
# Safe Promotion Path — The Rising Bar
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 + DR drill reference |
- **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 Design shipped Wiring: planned
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit
The DX win: the contract stays stable across environments. The safety win: the platform raises the threshold and attestation bar automatically based on the job's declared environment.
---
# Safe Decommission
Tearing down a stack is **as deliberate as deploying one** — and just as gated. Available today
```yaml
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**:
1. **Validate the change request** — the platform queries the CMDB; the CR must be `approved` and match the consumer repo
2. **Disable deletion protection** (plan + apply) → **SRE approves**
3. **Zero all counts + destroy** (plan + apply) → **a second SRE approves**
4. **Confirmation** — the stack is destroyed
The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable.
---
# Self-Service Module Catalog
Developers pick from **pre-built, security-reviewed building blocks** — they don't author infrastructure from scratch. Available today
- **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** — a thin-composition layer is auto-promoted to the catalog after 3 observed usages Planned
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, HIPAA, DORA controls will wire in Planned
---
# The Outcome for Leadership
- **Velocity without sacrificing safety.** Speed is in the ergonomics (a 5-line 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.
- **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.
- **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.