Skip to content

DDEV Standard (Bluefly)

Status: REQUIRED

1. Naming & Conventions

  • All DDEV environments must map cleanly to their upstream authoritative environments.
  • Project names should reflect their canonical repository names (e.g., contextcontrol).

2. The Rule of Upstream

  • Official documentation: docs.ddev.com is the sole tutorial authority. If a workflow or configuration step is documented upstream, do not rewrite it as a Bluefly tutorial — link to it.
  • Never fork DDEV functionality.
  • The local DDEV setup must remain thin. If a workflow seems complex, do not solve it by writing a custom DDEV CLI wrapper. Shift that execution authority to Gas City/Town or GitLab components.
  • Do not add .ddev-template configuration directly to the host machine's global configurations. Use project-scoped .ddev/ folders only.

3. Version Pinning

  • Strict Pinning: All installed DDEV add-ons must specify a version in the project configuration where supported.
  • Upgrades: Add-on upgrades should be deliberate actions backed by a configuration change in git, rather than implicit pulls of latest.

4. DDEV Add-on Policy

The DDEV Add-on Registry is the upstream catalog of record. Classification: references/addon-reference-catalog.md.

Classes

Class Meaning Install default?
CORE Required for core-drupal Yes (canonical profile)
RECOMMENDED High-value; install when needed Per site
OPTIONAL Evaluated; needs written justification Opt-in
SPECIALIZED Niche CMS/runtime Rare
REJECT Conflicts or duplicates Never (canonical)

Selection Rules

  1. Prefer official (ddev/*) over community when capabilities match.
  2. One implementation per capability (one DB UI, one search default, one Claude runtime).
  3. Reject meta-orchestrators (ddev-ai-workspace) and parallel work ledgers (local Beads).
  4. Reject experimental tags unless an explicit project exception is recorded.
  5. Bluefly custom add-ons only for product-boundary gaps the registry cannot express.
  6. Playlist Admission Rule: install only if project type ∈ supports and ∉ conflicts.

Custom Add-ons (Thin Adapters Only)

Every Bluefly add-on JUSTIFICATION.md must lead with the capability card (Capability, Upstream Owner, Bluefly Extension, Maintenance Cost, Deletion condition).

Approved (KEEP_THIN; each ships bluefly.addon.yaml): * ddev-agent-blu — OpenClaw/CoPaw env, ddev blu, optional governance * ddev-claude-drupal — Drupal overlays only; extends e0ipso/ddev-assistant-claude

Prohibited: Bluefly-owned Claude, Codex, Cursor, or OpenCode runtimes; Town/Beads orchestration inside DDEV; wrappers that reimplement official add-ons. Upstream assistant add-ons own install and lifecycle. Bluefly owns configuration, conventions, and project integration.

Installation / Upgrade

ddev add-on get <owner/repo> --version <tag>
Pin versions. Record reason in the project install manifest. Upgrade on ContextControl.ai first.

5. DDEV Playlist Standard

Playlists are curated, version-pinned compositions of DDEV add-ons. They are not feature packs and not runtimes.

Project Types

Every Drupal DDEV project declares exactly one type: | Type | Use | |------|-----| | drupal-site | Full application (e.g. ContextControl.ai) | | drupal-distribution | Product / CMS distribution | | drupal-contrib | Single contrib module repository | | drupal-theme | Theme repository | | drupal-profile | Install profile repository |

Playlist Admission Rule

Every add-on in a Bluefly playlist must declare in docs (and bluefly.addon.yaml for Bluefly add-ons): 

supports:
  - drupal-site
  # ...
conflicts:
  - drupal-site   # example: ddev-drupal-contrib
Refuse install when: 1. Project type ∉ supports, or 2. Project type ∈ conflicts.

Required Playlists

Playlist Default project type Notes
core-drupal-site drupal-site ContextControl reference
core-drupal-contrib drupal-contrib Mutually exclusive with site core
drupal-ai any supported Composed onto a core playlist

Opt-in: testing, search, performance, enterprise, and future named lists.

Activation

  • Reference full site installs only core-drupal-site + drupal-ai.
  • Installing all playlists at once violates the minimal standard.
  • Pin with ddev add-on get <repo> --version <tag>.