Skip to content

Bluefly Platform Priorities Doctrine

Canonical Operating Priorities for the Bluefly.io Ecosystem

Scope: This doctrine sits above the technical standards catalog. It does not describe architecture, code standards, or CI mechanics — it tells BLU, MAYOR-ORACLE, and every agent what to work on next, and in what order. When this doctrine and a technical standard disagree on priority (not on technical fact), this doctrine wins. Provenance: delivered verbatim by Thomas via BLU, 2026-09-06. Landed as canonical doctrine, not a chat artifact.

Execution Coordinator: BLU Runtime Authority: MAYOR-ORACLE Source Authority: GitLab Work Authority: Gas City / Beads Documentation Authority: BluCity-Docs Secret System of Record: 1Password Primary Product Platform: Drupal CMS

1. The Goal

Bluefly is not trying to maximize: repositories, agents, prompts, custom services, architecture documents, open MRs, lines of code.

Bluefly is trying to build a small number of working, monetizable products on top of a functioning autonomous engineering factory.

Operating sequence: FACTORY WORKS → FACTORY BUILDS REAL PRODUCTS → PRODUCTS PROVE REPEATABLE DELIVERY → REPEATED METHODS BECOME FORMULAS/PACKS/SHARED COMPONENTS → SCALE.

Priority order: P0 Gas City/Bluefly Factory, P1 bluefly.io, P2 ContextControl.ai, P3 AMCS, P4 Estate Convergence. Everything else is subordinate unless it directly enables one of these.

2. P0 — Gas City Working on Oracle

CITY=blucity, RUNTIME=Oracle, CITY_PATH=/opt/bluefly/blucity, BEADS_AUTHORITY=Oracle, DOLT_AUTHORITY=Oracle.

Gas City defines work as living outside sessions in Beads, Formulas as reusable methods that materialize work graphs, Rigs as external projects, Packs as configuration, roles as Pack-defined not hardcoded.

Required P0 outcome: ORACLE_CITY=HEALTHY, BEADS=HEALTHY, DOLT=HEALTHY, AGENT_EXECUTION=HEALTHY, FORMULAS_EXECUTE=YES, ORDERS_EXECUTE=YES, RIGS_RESOLVE=YES, MACHINE_IDENTITIES=WORKING, 1PASSWORD_DELIVERY=WORKING, MODEL_GATEWAY=WORKING, REMOTE_CLIENT_ACCESS=WORKING, LOCAL_MAC_CITY_AUTHORITY=NO.

3. BluCity and BluCity-Packs

blueflyio/blu/blucity = Bluefly's deployed City definition. blueflyio/blu/blucity-packs = reusable Bluefly factory behavior.

blucity stays thin — owns pack.toml, city.toml, deployment-specific composition, truly City-local config.

blucity-packs owns reusable agents, formulas, orders, skills, commands, doctor checks, policies, provider configuration.

Official Gas City distinguishes portable pack.toml, City-local city.toml, machine-local .gc/site.toml.

4. One City Authority

ORACLE_CITY_AUTHORITY=YES, MAC_CITY_AUTHORITY=NO. The Mac is: remote operator client, editor, browser, DDEV host, worktree execution surface. The Mac must not own: production supervisor, canonical Beads, canonical Dolt, long-lived factory state, unique durable work.

5. Rigs

A Rig is not every GitLab project. Gas City defines a Rig as an external project (usually a Git repo) registered with the City, receiving its own Bead namespace and agent scope. Config: city.toml (portable Rig declaration), .gc/site.toml (local filesystem binding).

Use a Rig when a project needs independent durable engineering work, its own Bead scope, agents working directly in it, independent execution lifecycle. Do not create 100+ Rigs because 100+ repositories exist.

6. P1 — Bluefly.io Rebuild

Repository: blueflyio/assets/bluefly.io. Existing/live site source (input/reference, not future architecture): blueflyio/assets/bluefly.

Rebuild uses canonical Bluefly Drupal doctrine: CORE → CONTRIB → CONFIGURATION → RECIPE → CANVAS/SDC → ECA/FLOWDROP → DRUPAL AI → TOOL API/MCP → EXISTING BLUEFLY EXTENSION → CUSTOM ONLY AFTER PROVEN GAP.

Target: Drupal CMS, current, clean, rebuildable, fast, accessible, structured, AI-ready, minimal custom code. No accumulation of old Bluefly implementation merely because it existed previously.

7. Bluefly.io Acceptance

Complete only when: CLEAN_COMPOSER_BUILD=YES, DRUPAL_BOOT=YES, CONFIG_VALID=YES, RECIPES_VALID=YES, CANVAS=YES, SDC=YES, STRUCTURED_CONTENT=YES, EDITORIAL_WORKFLOW=YES, ACCESSIBILITY=PASS, SECURITY=PASS, AI_CONFIGURATION=VALID, NO_UNAUTHORIZED_PROVIDER_DEPENDENCIES=YES, NO_WORKSTATION_PATHS=YES, NO_PLAINTEXT_SECRETS=YES, CI=PASS, DEPLOYED=YES, PUBLIC_RUNTIME_VERIFIED=YES. Green CI alone is not acceptance.

8. P2 — ContextControl.ai

Canonical source: blueflyio/contextcontrol.ai/contextcontrol-ai. Core value prop: REGISTER, GOVERN, REMEMBER. Do not allow it to become another general-purpose orchestrator, scheduler, task database, secret store, Git replacement, or agent runtime. Gas City owns engineering orchestration. Beads owns engineering work. ContextControl owns governed context/memory capability.

9. P3 — AMCS

Canonical product sources: blueflyio/amcs/site_template_amcs, blueflyio/agent-platform/drupal/recipes/recipe_amcs. Consumer/demo: blueflyio/amcs/amcs-demo. Rule: DO_NOT_MANUALLY_BUILD_AMCS_IN_AMCS_DEMO — the demo must consume the canonical product.

Product = site template + foundation recipe + recipe_amcs + theme/SDC + packaged UI capabilities. AMCS is a Drupal 11 product assembled declaratively through Recipes and Site Templates, not heavy custom PHP.

10. AMCS Product Definition

SITE_TEMPLATE_AMCS = installable product entry point. RECIPE_AMCS = AMCS capability composition. FOUNDATION_RECIPE = generic Drupal platform baseline. AGENTIC_CANVAS_THEME = theme/SDC owner. STUDIO_UI = framework-agnostic UI source/artifact. AMCS_DEMO = consumer/acceptance environment.

Required AMCS capabilities: Canvas, SDC, Drupal AI, AI Agents, AI Agents OSSA, AI Context, ECA, Modeler, FlowDrop, Tool API, Tool Belt, MCP, Search/RAG, roles, permissions, content model, workflow.

11. Platform-Wide Shared CI

Every active Bluefly project should converge on blueflyio/gitlab_components as the reusable CI authority. Project-specific CI only for genuinely project-specific behavior; reusable CI belongs in gitlab_components. Shared: build, test, Composer auth, package publication, security, release, promotion, deployment, quality gates, runner behavior. If ten projects fail with one signature: fix one component, retry ten projects. Do not patch ten repositories independently.

12. GitLab Workflow

Correction from older draft wording — do NOT use "feature → main MR" while also maintaining "feature → release" as the engineering path. Use one clean promotion model:

FEATURE/FIX → MR → release/v0.1.x → all required pipelines pass → release accepted → release → main promotion MR → Thomas approves when human gate is required.

So: FEATURE_TO_MAIN=NO, FEATURE_TO_RELEASE=YES, RELEASE_TO_MAIN=YES. Thomas approves the promotion, not every individual implementation branch.

13. Green Does Not Mean Merge

PIPELINE_GREEN != AUTO_MERGE_PERMISSION. Merge requires: correct target, correct review, required approvals, no unresolved governance blockers, no known regression. For releases: SOURCE_CORRECT + PIPELINE_PASS + REVIEW_PASS + PROMOTION_AUTHORIZED, then merge.

14. No Broken MR Estate

Target is not literally zero failing MRs at every instant — there will always be legitimate WIP. Correct target: NO_UNOWNED_BROKEN_MRS=YES, NO_UNKNOWN_FAILURE_SIGNATURES=YES, NO_STALE_ABANDONED_MRS=YES. Every broken MR must be owned, classified, routed, or intentionally closed. BLU/REFINERY converge failures by signature rather than rediscovering them individually.

15. Agents Use One Durable Work Graph

WORK_AUTHORITY=ORACLE_BEADS. Agents use blu → Gas City API/context → Oracle → Beads. No separate local Beads universe, no local agent task tracker, no private agent TODO database, no chat-only assignment. Gas City makes Beads durable ground truth; sessions are disposable.

16. blu CLI

blu stays a thin Bluefly governance/operator layer, not another orchestrator. Desired: authenticate/identify, select City/Rig/context, call supported Gas City/Bluefly APIs, expose governed UX. Not: duplicate Formula engine, duplicate scheduler, duplicate Beads, duplicate Gas City API. blu-cli is the operator surface wrapping Gas City, not replacing it.

17. Self-Hosted Models

Default: use a self-hosted model when quality sufficient, latency acceptable, security appropriate, required tools work. Do not self-host ideologically. Routing optimizes quality, cost, latency, privacy, capability. A cheap model causing repeated failures is not cheaper. Policy: self-hosted default → escalate to a frontier model only when task complexity/quality requires it.

18. Agent Provider Readiness

Every role needs a capability contract, e.g. FOUNDRY requires: shell, git, worktrees, source editing, GitLab push, MR creation, CI inspection. A session lacking those isn't healthy for that role. Contract shape: ROLE → REQUIRED CAPABILITIES → PROVIDER → MACHINE IDENTITY → READINESS PROBE → READY. Do not let incapable sessions sit idle for days asking Thomas to reconnect them.

19. Custom Service Standard

No custom service without a contract: SERVICE, INTERFACE, CONFIGURATION, HANDLERS, OWNER, CONSUMERS, AUTH_MODEL, OBSERVABILITY, TESTS, FAILURE_SEMANTICS, DELETION_TRIGGER. Rule: NO_INTERFACE = NO_SERVICE. Before creating: does upstream already provide this? Does Drupal already provide this? Does Gas City already provide this? Does GitLab already provide this? Can configuration solve it? Can an existing service be extended? Only create after a proven gap.

20. API-First Execution

Use existing APIs/services/shared components before creating new scripts, services, databases, or side paths. API_FIRST=YES, FILESYSTEM_COUPLING=AVOID, DIRECT_DATABASE_COUPLING=AVOID, CUSTOM_SCRIPT_AS_API_REPLACEMENT=NO. For every service: interface first, implementation second.

21. Studio-UI Is the Shared Interface System

Studio-UI is a shared UI product, not copied into individual applications. Architecture: Studio-UI = reusable framework-agnostic component library; Drupal → SDC/integration adapter; Next.js → native adapter; React dashboard → native adapter; other client → appropriate adapter. Do not fork components per product, copy UI source into apps, create a Drupal-only Studio UI fork, or create a dashboard-only duplicate. Each framework gets an adapter; the component contract stays shared.

22. Studio-UI Interface Rule

Check Studio-UI first for new human-facing interfaces. If it contains the component, use it. If close, extend Studio-UI. Only create product-local UI when the capability genuinely belongs only to that product. Shared: buttons, forms, cards, navigation, tables, dialogs, agent UI, status components, dashboard primitives, layout primitives — converge toward Studio-UI.

23. Documentation Is a Product Surface

Documentation is currently an operational risk because contradictory doctrine changes agent behavior. Older master documents contain valuable research but also stale material (old Gas City runtime assumptions, historical Oracle topologies) — the July research still contains multiple conflicting descriptions of Gas City/Gas City and old runtime models. Therefore: DOCUMENTATION_CONVERGENCE=P0_GOVERNANCE.

24. One Documentation Authority

Canonical Bluefly engineering doctrine lives in BluCity-Docs. Project docs may contain project-specific contracts, README, setup, API usage, project architecture — but must point back to canonical Bluefly doctrine instead of copying it. Google Docs become working research, strategy, drafting, historical input — not a competing engineering authority.

25. Google Docs Consolidation

Listed docs: Bluefly_Gas_City_Drupal_Product_Factory_Research_2026-07-22, MASTER-BLUEFLY-AGENT-FACTORY, GasCity/BluTown material, Building_in_Drupal_The_2026_Way. These should NOT all remain active canonical instructions. Classify each as: research source, historical, superseded, active strategy, or canonical doctrine. The two attached Google docs contain substantial duplicated/contradictory material — one section says Gas City roles are configuration while other sections still describe Gas City as the active runtime. Consolidation must extract surviving intent, not simply merge documents together.

Classification (landed here; Google Docs' own headers are a separate follow-up, not a blocker — see Note below):

Document Classification
MASTER-BLUEFLY-AGENT-FACTORY RESEARCH / INPUT — not canonical
Bluefly_Gas_City_Drupal_Product_Factory_Research_2026-07-22 RESEARCH / HISTORICAL — contains known contradictions on Gas City vs Gas City runtime; superseded by Gas City architecture and this doctrine
GasCity/BluTown material HISTORICAL / SUPERSEDED — Gas City terminology superseded by Gas City; BluTown persona superseded by BluCity (see gc-cities.md)
Building_in_Drupal_The_2026_Way RESEARCH / INPUT — not canonical; canonical Drupal doctrine is drupal-standard.md

Note (follow-up, not a blocker): Bluefly does not have write access to edit these Google Docs directly from BluCity-Docs tooling. This table is the authoritative classification. Flagging to Thomas separately: the Google Docs' own headers should eventually be updated to point here and self-identify as non-canonical, so a reader opening the doc directly (not via BluCity-Docs) doesn't mistake it for current doctrine.

26. Documentation Precedence

Intent: Thomas's current intent → current Bluefly doctrine → historical strategy.

Technical fact: current upstream authority → current GitLab source → authoritative runtime evidence → current Bluefly doctrine → historical docs → agent memory.

This prevents old Google Docs from overriding current Gas City behavior.

27. Documentation Consolidation Workflow

For every subject: search current docs, identify active owner, identify duplicates, verify upstream facts, verify current Bluefly source, verify runtime if relevant, preserve unique intent, update one owner, archive/retire duplicates, update indexes, MR, verify a second agent resolves the correct answer. Do not create a new standard until existing owners have been searched.

28. Documentation Subjects to Converge

14 subjects, not 40 overlapping manifestos. This doctrine (#1) is landed; the remaining 13 are the target list for future convergence passes — not built now, so nobody reinvents this list:

  1. Bluefly Platform Priorities (this doc)
  2. Gas City Operating Standard
  3. City/Rig/Pack Model
  4. Authentication & Secrets Constitution
  5. Drupal CMS Product Doctrine
  6. AMCS Product Composition Doctrine
  7. Source/Runtime Convergence
  8. GitLab Delivery/Release Standard
  9. Machine Identity Standard
  10. Backup/Restore Contract
  11. Shared CI Standard
  12. Studio-UI Interface Standard
  13. Documentation Governance
  14. Failure Signature Catalog

29. WITNESS and REFINERY Own Documentation Convergence

WITNESS = detect contradictions, verify technical facts, identify stale doctrine, read-only. BLU = resolve architecture/policy ownership. REFINERY = consolidate docs, update owner, retire duplicates, repair references, push MR. No agent independently creates "the new canonical architecture" because it found an old document.

30. Project Documentation Rule

Every project needs only what it requires: README.md, AGENTS.md, API/interface docs, project-specific architecture, testing/build docs. AGENTS.md navigates agents to canonical doctrine — it does not duplicate entire Bluefly standards. E.g.: for Bluefly engineering policy → BluCity-Docs; for Drupal → Building in Drupal doctrine; for auth → Authentication & Secrets Constitution; for Gas City → Gas City Operating Standard.

31. Google Drive Rule

Google Drive is for research, strategy, business docs, drafting, meeting notes, long-form analysis — not the source of runtime engineering truth. Final technical doctrine converges into GitLab/BluCity-Docs. Google documents may link to final doctrine or be labeled research/superseded/archive.

32. Source/Runtime Law

Recurring failure: source says one thing, Oracle runs another. Lock: SOURCE_CORRECT != DONE. Terminal acceptance: SOURCE_CORRECT=YES, CI=PASS, MERGED=YES, DEPLOYED=YES, AUTHORITATIVE_RUNTIME_VERIFIED=YES. Only then close runtime-impacting work.

33. Infrastructure Law

No manual infrastructure architecture: GitLab → IaC → Oracle. Manual SSH only for read-only diagnosis or emergency evidence collection, not to establish final desired state. If the only way to fix production is SSH → edit file, that's SOURCE_RUNTIME_CONVERGENCE_FAILURE=YES — fix source/IaC instead.

34. Net-Negative Ownership

Every technical decision asks: what can we delete? What can upstream own? What can configuration own? What can a shared component own? What can a Recipe own? What can a Pack own? Composition over implementation, Drupal as crystallized knowledge — one of the strongest Bluefly principles.

35. Current Priority Board

BLUEFLY PLATFORM PRIORITY BOARD

P0 — FACTORY: GASCITY_ORACLE, BLUCITY, BLUCITY_PACKS, BEADS_DOLT, AGENT_EXECUTION, REMOTE_CLIENT, MACHINE_IDENTITIES, SELF_HOSTED_MODELS, BACKUP_RESTORE

P1 — BLUEFLY.IO: SOURCE, OLD_SITE_REFERENCE, DRUPAL_BUILD, COMPOSER, CONTENT_MODEL, CANVAS_SDC, STUDIO_UI, AI, CI, DEPLOY, PUBLIC_ACCEPTANCE

P2 — CONTEXTCONTROL.AI: SOURCE, MVP, BUILD, INTERFACES, STUDIO_UI, CI, DEPLOY, PRODUCT_ACCEPTANCE

P3 — AMCS: SITE_TEMPLATE, RECIPE_AMCS, FOUNDATION_RECIPE, THEME, STUDIO_UI, COMPOSER, CANVAS_SDC, AI, ECA_FLOWDROP, TOOL_API, MCP, FRESH_CREATE_PROJECT, DEMO_CONSUMER_PROOF

P4 — ESTATE: SHARED_CI_ADOPTION, OPEN_MRS, UNKNOWN_FAILURES, BROKEN_PIPELINES, DOC_CONTRADICTIONS, AGENT_IDENTITY_GAPS, LOCAL_AUTHORITY_COPIES

36. Work Selection Rule

BLU chooses work in this order: 1. Does it unblock P0? 2. Does it directly move P1? 3. Does it directly move P2? 4. Does it directly move P3? 5. Does it eliminate an estate-wide blocker affecting these? 6. Otherwise: defer.

Prevents spending two days on an unrelated dashboard while bluefly.io doesn't build.

37. Agents Do Not Invent Busywork

Keep ready work moving, not keep every agent busy. Idle workers are acceptable. Unowned ready work is not. Gas City's orchestrator fans out ready Beads and blocks work until dependencies close.

38. Factory Promotion Rule

Evaluate every manual solution afterward: would we run this again? If yes, encode a Formula, run again. If proven across multiple Rigs, promote into a Pack. If reusable CI, promote into gitlab_components. If Drupal product composition, promote into a Recipe/Site Template.

39. Final Operating Law

THOMAS SETS BUSINESS AND PRODUCT INTENT. BLU PRIORITIZES THE PORTFOLIO AND IMPROVES THE FACTORY. MAYOR-ORACLE OPERATES THE AUTHORITATIVE FACTORY. GAS CITY ORCHESTRATES. BEADS HOLDS DURABLE WORK. FORMULAS HOLD REPEATABLE METHODS. RIGS DEFINE ENGINEERING WORK DOMAINS. PACKS CARRY PROVEN FACTORY BEHAVIOR. GITLAB OWNS SOURCE, CI, PACKAGES, AND RELEASE. GITLAB_COMPONENTS OWNS SHARED CI. ORACLE OWNS FACTORY RUNTIME. NAS OWNS DURABILITY AND RESTORE EVIDENCE. 1PASSWORD STORES AND DELIVERS SECRETS. TARGET SYSTEMS AUTHORIZE AND ROTATE CREDENTIALS. DRUPAL OWNS DRUPAL PRODUCT BEHAVIOR. DDEV PROVES DRUPAL LOCALLY. STUDIO_UI OWNS SHARED HUMAN INTERFACE COMPONENTS. BLUCITY-DOCS OWNS BLUEFLY ENGINEERING DOCTRINE. GOOGLE DRIVE HOLDS RESEARCH AND STRATEGY, NOT COMPETING RUNTIME TRUTH. CUSTOM SERVICES REQUIRE AN INTERFACE. CUSTOM CODE REQUIRES A PROVEN GAP. CHAT IS NOT THE WORK GRAPH. LOCAL MACHINE STATE IS NOT AUTHORITY. GREEN CI IS NOT PRODUCT ACCEPTANCE. MERGED IS NOT DEPLOYED. DEPLOYED IS NOT HEALTHY.

PROVE SMALL. LEARN. ENCODE. REPEAT. SCALE. OWN LESS. SHIP THE PRODUCTS.