Jon Chery
eb7634da28
v1.15-Nova rebrand doc verification (phase/05-final-review-ship) found stale ACDL references where the code/terraform already uses Nova names. Critical drift fixed (doc said old name; code uses new): - README.md: `.acdl/contract.yml` -> `.nova/contract.yml`; `acdl-spike-runner` -> `nova-spike-runner`; ABAC tag keys `acdl:owner|contract` -> `nova:owner|contract`. - docs/environments/index.md: `acdl-contract-ingestor` -> `nova-contract-ingestor`; `aws:PrincipalTag/acdl:owner` -> `nova:owner`; `acdl-contracts` -> `nova-contracts`. - docs/consumer-guide.md: `acdl-change-requests` -> `nova-change-requests`; state bucket example `acdl-qa-state` -> `nova-qa-state`. - docs/presentations/* (4 decks + 2 HTML + talking-points): `acdl:owner|contract| environment|cost-center` -> `nova:*`; `ACDL_LIFECYCLE_MODE` -> `NOVA_LIFECYCLE_MODE`. - pipelines/modules-lifecycle.yml comments: `ACDL_LIFECYCLE_MODE` -> `NOVA_LIFECYCLE_MODE` (workflows already use NOVA_; the contract comments were stale). - docs/NOVA_MIGRATION.md: status banner -> COMPLETE (P5 cutoff passed). - .ciagent/ARCHITECTURE.md: header `ACDL` -> `Nova`; NOVA_LIFECYCLE_MODE rename noted in the live lifecycle-mode section (v1.15 addendum already correct). - .ciagent/ROADMAP.md: v1.15 phase statuses P1-P4 pending -> complete (v1.15.1..v1.15.4); P5 -> in progress (phase/05-final-review-ship). Verification: - grep for `acdl:*` tag keys / `.acdl/contract` / `acdl-contract-ingestor` / `acdl-contracts` / `ACDL_LIFECYCLE_MODE` in README/docs/pipelines -> 0 hits (excluding explicitly-unchanged repo path `acdl/.github/...`, `continuous-intelligence/acdl`, and historical narrative). - core/output_publisher.py uses `/nova`; schemas/tagging-standard.json uses `nova:*`; terraform uses `nova-*` (0 `acdl-` in *.tf) — docs now match. - git tag v1.15.0..v1.15.4 exist. - pytest tests/test_lifecycle_mode_flag.py tests/test_pipeline_contract.py -> 111 passed. ---ci--- project: acdl
253 lines
16 KiB
Markdown
253 lines
16 KiB
Markdown
# The Developer Experience — Talking Points
|
|
|
|
> **Companion to:** `the-developer-experience-marp.md` (11 main + Appendix TOC + 7 appendix = 19 slides)
|
|
> **Content source:** `the-developer-experience.md` (full source of truth with speaker notes)
|
|
> **Purpose:** Presenter-ready cues — 3-6 talking points per slide + the one key takeaway the audience should remember.
|
|
> **Audience:** Senior Leadership — CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
|
|
|
|
---
|
|
|
|
## Slide 1 — Title
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- v1.12 re-verification: every "Testing" claim in this deck is now Verified — 22/22 capabilities via the v1.11 lifecycle pipeline (see A7)
|
|
|
|
**Key takeaway:** The consumer surface is intentionally tiny. The platform's surface is large and opinionated.
|
|
|
|
---
|
|
|
|
## Slide 2 — Two consumer paths, one safety envelope
|
|
|
|
**Talking points:**
|
|
- This is the scope-boundary slide — here's who uses the platform, and here's where Nova's responsibility starts and stops
|
|
- Two consumer paths converge on the same contract: **technical** developer writes the contract directly; **citizen** developer declares intent and an AI agent produces a contract that passes the same safety envelope
|
|
- Upstream is anything — your IDE, an agentic SDLC, or vibe coding on a laptop. Nova doesn't care how the contract was produced
|
|
- Nova is infrastructure only — it provisions and governs AWS resources. Application deployment is upstream of the contract
|
|
- The two surfaces are *parallel*, not a progression. A citizen developer doesn't "graduate" to the developer surface. There is no "citizen developer mode" with weaker checks
|
|
|
|
**Key takeaway:** Two consumer paths, one safety envelope. Nova is infra only — anything upstream is fair game.
|
|
|
|
---
|
|
|
|
## Slide 3 — The platform at a glance
|
|
|
|
**Talking points:**
|
|
- One-slide map — frame it from the left edge: "this is what you touch, this is what the platform owns for you"
|
|
- The leadership beat: the convergence — two surfaces, one pipeline, one evidence stream — is the design point that lets us expand who can ship safely without lowering the bar
|
|
- Don't walk every node — point to the contract boundary and say "the rest of this deck zooms into the developer-facing pieces"
|
|
- The bar rises automatically — the confidence signal and HITL gates scale with the target environment, not with a ticket
|
|
|
|
**Key takeaway:** You own the left edge (app + contract). The platform owns everything else, end to end.
|
|
|
|
---
|
|
|
|
## Slide 4 — Three things. The entire consumer surface.
|
|
|
|
**Talking points:**
|
|
- Hold this slide — the audience should sit with how small the consumer surface is. Three things: app code, a contract, a one-line CI definition
|
|
- The contract is a single YAML file: module, environment, inputs. That's the entire consumer-facing interface to production
|
|
- The contract example shows **infrastructure inputs** (cpu, memory, desired_count, port) — not an `image:` field. The consumer declares capacity and shape; the platform resolves the rest
|
|
- Walk the "does not" list quickly — no infrastructure modules, no platform repo cloning, no cloud credentials, no state backends. Every item 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
|
|
|
|
**Key takeaway:** Three things. That's the entire consumer-side surface. Everything else is the platform's job.
|
|
|
|
---
|
|
|
|
## Slide 5 — See what the platform does, in real time
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- Streamed output by default — the plan, policy 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
|
|
- Connection strings posted as PR comments — human-readable, no hunting. Runtime secrets go to encrypted Parameter Store (KMS-encrypted, namespaced), never to logs
|
|
- The "errors become GitHub 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
|
|
- Clear, explainable halt reasons — a policy violation, an insufficient confidence signal, or a missing attestation. Never an opaque debugging exercise
|
|
|
|
**Key takeaway:** The platform closes the feedback loop — streamed output, PR comments, clear halt reasons, no secrets in logs.
|
|
|
|
---
|
|
|
|
## Slide 6 — Pick from pre-built, security-reviewed blocks
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- Primitives are single-purpose resources (S3, VPC, ECS, IAM, ALB, ECR, CloudFront, WAF, RDS) — each with documented inputs/outputs and versioning
|
|
- Modules are composed patterns — a static site with CDN + WAF; a microservice with VPC + ECS + ALB + ECR
|
|
- Validated examples per module (`simple.yaml` + `complex.yaml`) are validated against the contract schema in CI — examples cannot drift from the schema silently
|
|
- Auto-promotion of patterns (after 3 observed usages) and compliance extension points (GDPR, SOX, SOC2, DORA) are on the roadmap
|
|
|
|
**Key takeaway:** You don't author infrastructure — you pick from pre-built, security-reviewed building blocks. The catalog is the compounding asset.
|
|
|
|
---
|
|
|
|
## Slide 7 — The bar rises automatically with sensitivity
|
|
|
|
**Talking points:**
|
|
- Promotion is a workflow choice, not a contract edit — a promotion can be reviewed as a *diff in the workflow*, not as a rewritten contract
|
|
- The DX win: the contract stays stable across environments; the safety win: the platform raises the threshold and attestation bar automatically based on the target environment
|
|
- The consumer can't bypass the gates — they pick *which* environment to target, and the platform applies the right bar
|
|
- 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
|
|
- Be honest about maturity: dev is tested and pilot-ready; qa/prod/dr wiring is planned
|
|
|
|
**Key takeaway:** The bar rises automatically with sensitivity. The consumer picks the environment; the platform applies the right gate.
|
|
|
|
---
|
|
|
|
## Slide 8 — Tearing down is as gated as deploying
|
|
|
|
**Talking points:**
|
|
- 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`
|
|
- The CMDB validation means decommission is auditable, not just possible — the platform queries the CMDB and asserts the CR is `approved` and matches the consumer repo
|
|
- Two SRE human-attestation gates: disable 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 during decommission
|
|
- For the Head of Infrastructure: this is what makes deletion protection safe to ship by default — cleanup is a deliberate, gated path, not an impossible one
|
|
|
|
**Key takeaway:** Tearing down is as deliberate as deploying — two SRE attestation gates + CMDB-validated change request.
|
|
|
|
---
|
|
|
|
## Slide 9 — You control when you absorb improvements
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- 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 a consumer has
|
|
- The automated release job computes the next semver on merge to main, creates the tag, and updates the floating tags
|
|
|
|
**Key takeaway:** You control when you absorb platform improvements — no surprise upgrades, no forced forks.
|
|
|
|
---
|
|
|
|
## Slide 10 — Fails gracefully, not opaquely
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- When no environment is bound, the platform emits a user-friendly onboarding prompt — not an opaque failure
|
|
- The prompt tells the consumer: no environment bound, what the platform will provision, expected turnaround, how to request an environment
|
|
- The pipeline then exits without attempting a deployment — no partial state, no confusing errors
|
|
- The citizen developer onboarding path is planned
|
|
|
|
**Key takeaway:** The platform fails gracefully, not opaquely — first impressions are made when it fails for the first time.
|
|
|
|
---
|
|
|
|
## Slide 11 — The desired outcomes
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- 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
|
|
- 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 serves a senior engineer and a non-technical consumer
|
|
- Invite questions; the companion deck ("How the Platform Works") covers the internal mechanics in more depth
|
|
|
|
**Key takeaway:** Ship safely at the pace the business demands, with the security and audit posture the regulators require.
|
|
|
|
---
|
|
|
|
## Appendix TOC — Appendix
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- The appendix is indexed to match the Marp deck's A1-A7 structure
|
|
|
|
**Key takeaway:** Backup slides for Q&A — pull the relevant appendix slide when asked.
|
|
|
|
---
|
|
|
|
## A1 — The Citizen Developer Experience
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- Guardrails: skills are versioned, signed, reviewed for sensitive data; agents are stateless; the platform trusts and always verifies
|
|
- The agent's trace and submission confidence are captured in the contract (`profile: agentic`) for review
|
|
|
|
**Key takeaway:** A non-technical consumer ships by declaring intent — same pipeline, same safety envelope, no weaker checks.
|
|
|
|
---
|
|
|
|
## A2 — No Platform Code, No Cloning
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- The runner checks out the consumer repo, then checks out the platform repo into the workspace — the consumer never clones the platform repo
|
|
- 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 — no per-repo upgrade project
|
|
|
|
**Key takeaway:** The consumer never touches platform internals. The versioned `uses:` line is the only coupling.
|
|
|
|
---
|
|
|
|
## A3 — Local Reproducibility
|
|
|
|
**Talking points:**
|
|
- 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
|
|
- `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
|
|
- The same declarative contract drives both the local tooling and CI — there's no "works on my machine, fails in CI" gap
|
|
|
|
**Key takeaway:** The entire CI pipeline runs from the shell — no surprises before you push.
|
|
|
|
---
|
|
|
|
## A4 — The Road to the North Star
|
|
|
|
**Talking points:**
|
|
- This is a proposed phasing, not a formally committed plan — call that out explicitly
|
|
- Phase 1 is what's tested and Verified today (22/22 capabilities, torn down to zero-cost)
|
|
- Phase 2 is the next milestone (qa/prod/dr wiring)
|
|
- Phase 3 introduces the agentic surface (skill catalog + agents)
|
|
- 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"
|
|
|
|
**Key takeaway:** Proposed phasing — Phase 1 Verified, Phase 4 is the North Star (citizen developer GA).
|
|
|
|
---
|
|
|
|
## A5 — Glossary
|
|
|
|
**Talking points:**
|
|
- Keep this slide in your back pocket for the audience member who asks "what does ABAC actually mean?"
|
|
- Don't read it aloud
|
|
- All acronyms used in the deck are defined here
|
|
|
|
**Key takeaway:** Reference slide — don't read aloud.
|
|
|
|
---
|
|
|
|
## A6 — Operating Model & Cost
|
|
|
|
**Talking points:**
|
|
- The headline for the Head of Cloud / Finance: less than one cent over 8 days of active development; zero BAU cloud spend
|
|
- The lifecycle pipeline defaults to plan-only so the PR-time cost is zero; `NOVA_LIFECYCLE_MODE=full` overrides for milestone verification
|
|
- The pre-mortem is the credibility slide — we already asked "how does this fail?" and the mitigations are structural
|
|
- The v1.10 decay incident is disclosed honestly, not hidden — that disclosure IS the mitigation
|
|
- Cost drivers are spike-scoped: Terraform plan reads (free), S3 state storage (cents), DynamoDB outbox (cents). No running infrastructure between milestones
|
|
|
|
**Key takeaway:** Zero BAU cloud cost. Pre-mortemed failure modes with structural mitigations.
|
|
|
|
---
|
|
|
|
## A7 — Verified by Construction
|
|
|
|
**Talking points:**
|
|
- This is the deep-dive slide for the Head of Engineering / Architecture — the two pillars answer "how do you keep the decks honest?"
|
|
- The adapter is simple enough to reason about (a stateless assembler); the lifecycle pipeline is the automated verification that backs every "Testing" claim
|
|
- The v1.10 lesson is the negative space: a 918-line adapter with type-specific branches decayed silently because the VERIFY gate was diff-scoped
|
|
- The ~80-line stateless adapter + the milestone regression gate are the structural fix
|
|
- The plan-only default (v1.12) means verification runs on every PR at zero cost, with the full apply→destroy gated behind a CI variable override
|
|
|
|
**Key takeaway:** "Verified" is a structural property, not a claim — the stateless adapter + lifecycle pipeline make it so. |