Bluefly Canonical DDEV Distribution Architecture¶

Authority: DDEV core docs and the DDEV Add-on Registry. Reference install: Applications/ContextControl.ai/.ddev Not in scope: Oracle runtime, Gas Town/Beads work authority, production hosting.

Durable abstraction¶

Bluefly does not ship an “AI workspace.” It ships a DDEV distribution: a small, opinionated, version-pinned composition of upstream DDEV + registry add-ons + thin Bluefly adapters.

Analogy	Role
Drupal CMS	Reference CMS
ContextControl.ai	Reference AI product site (consumer of the distribution)
Bluefly Canonical DDEV	Opinionated local distribution

Capability: Developer Distribution Reference Provider: DDEV Deployment Provider: Bluefly DDEV Distribution (playlists + conventions + thin adapters only)

Do not let every project invent its own DDEV stack. Extend playlists; do not fork the distribution.

Ownership stack¶

Bluefly Distribution (playlists + conventions)
        → Official Add-ons
        → Thin Bluefly Add-ons
        → Project

Bluefly owns almost nothing: playlists, conventions, tiny adapters.

Plane separation¶

DDEV          → developer distribution (workstation)
Git           → history
IaC           → what exists (capability modules)
agent-docker  → how it runs (installer, not architect)
Oracle        → runtime
Gas Town      → execution / work
OpenClaw      → trust / capability federation
Drupal        → content SoR / product UI

Project types (not one “Drupal” playlist)¶

Type	Playlist family
`drupal-site`	`core-drupal-site` + optional overlays
`drupal-distribution`	site-like core
`drupal-contrib`	`core-drupal-contrib` only
`drupal-theme`	theme-appropriate members
`drupal-profile`	profile-appropriate members

Playlist Admission Rule: install only if project type ∈ supports and ∉ conflicts (bluefly.addon.yaml / documented matrix). Hard example: ddev/ddev-drupal-contrib conflicts with drupal-site.

Custom add-on rule (thin adapter)¶

Add-on	May own	Must not own	Verdict
`ddev-agent-blu`	OpenClaw/CoPaw env, `ddev blu`, optional governance	Redis/Solr/Adminer, SSH daemons, Beads, AI runtimes	KEEP_THIN
`ddev-claude-drupal`	Persona, skills, `claude-sync` into existing Claude home	Claude install/lifecycle	KEEP_THIN

Upstream assistant add-ons own install and lifecycle. Bluefly owns configuration, conventions, and project integration.

Capability justification template (required)¶

Field	Question
Capability	What single capability?
Upstream Owner	Who owns the durable part?
Bluefly Extension	What thin delta?
Maintenance Cost	Low / Medium / High
Can this disappear?	Yes/No — when do we delete the repo?

Composition home¶

Operator composition lives under Applications/__DRUPAL/DDev-Addons/ plus BluCity-Docs architecture/Ddev/. A future bluefly-ddev-distribution repo may hold only playlists/, templates/, examples/, docs/, tests/ — no runtime, no containers, no Claude/OpenCode install.

What we will not build¶

Custom Claude / Codex / Cursor / OpenCode runtimes
Meta AI-workspace orchestrators
Parallel Beads/Gas Town inside DDEV
agent-docker as architect of what exists

addon-playlists.md
standards/drupal/ddev/ddev-standard.md, standards/drupal/ddev/ddev-addon-policy.md, standards/drupal/ddev/ddev-playlist-standard.md
references/addon-reference-catalog.md