Skip to content

Bluefly Operational Model (v6)

Bluefly is not an orchestration platform. Bluefly is a first-class Gas City distribution: a collection of reusable packs, orders, formulas, prompts, doctor checks, and policies, with a thin blu CLI focused on installation, discovery, policy, and developer experience.

Target Architecture

                         Gas City Runtime
                                │
          ┌─────────────────────┴─────────────────────┐
     Core Packs (blucity-packs)                Optional Packs
    ├── Drupal                                ├── Government
    ├── Oracle                                ├── AI
    ├── Compliance                            ├── Commerce
    ├── OSSA                                  └── Observability
    └── Contracts
                                │
                                ▼
                       Local City (city.toml)
                                ▲
                                │
               blu (Thin UX / Delegation CLI)

1. Runtime Ownership Layer

Layer Owner Role
Git History Git Canonical file change history.
Structured Runtime State Dolt / Beads Persistent relational tables (work, run logging).
Work Graph Beads Task-gated execution sequencing.
Runtime Gas City Orchestration of the six primitives.
Multi-agent Workflow Pack-configured Agents Roles (mayor, witness, worker) are Pack configuration, not a hardcoded Gas Town runtime.
Telemetry gascity-otel Performance metrics and trace logging.
Dashboard gascity-dashboard Editorial ambient dashboard interface.
Federation Wasteland Cross-city marketplace wanted board.
Terminal Runtime tmux-adapter / OpenClaw Safe interactive session rendering.
Developer Experience Blu Developer CLI and environment bootstrap.
Business Policy Bluefly Custom compliance policies and configuration.

2. Pack Architecture & Deployment Boundary

All reusable behaviors are authored in modular Packs rather than embedded in orchestrator scripts.

  • Canonical Location: Authored and version-controlled inside the local workspace repository: blucity-packs.
  • GitLab Deployment: Commits pushed to GitLab trigger pipelines that deploy updated packs and city config to the Oracle production runtime via governed blucity CI (stamp → deploy:oracle → gc-site-bind → verify). NAS holds custodian mirrors and artifacts — not live Gas City execution. See oracle-canonical-architecture.

3. Thin blu CLI & Delegation Contract

The blu binary is the developer UX, not the execution framework. It is restricted to: 1. Discovery: Locating and listing active cities, packs, and capabilities. 2. Installation: Setting up development tools (DDEV, Gas City, etc.). 3. Bootstrap: Initializing cities (gc init) and setups. 4. Policy Integration: Enforcing local workspace safety policies. 5. Delegation: Resolving commands and forwarding them directly to gc, bd, doctor, or pack orders. Do not add a gt control plane.

4. Adoption Priority Decision Framework

All capabilities must be classified using this deterministic decision process: - Adopt: Already exists upstream. Use natively without changes. - Configure: Exists upstream; requires custom config. Supply custom configuration (e.g. city.toml). - Extend: Use supported extension points. Write custom doctor checks, prompt overlays, or commands. - Wrap: Thin UX wrapper only. Create thin blu CLI delegation commands. - Build: Only if no upstream primitive exists. Author custom pack behaviors or local utilities.

5. "Never Build This Again" Catalog

To prevent future platform bloat, the following capabilities are permanently forbidden from being implemented in Bluefly:

  1. Custom Schedulers or Task Queues: Gas City owns execution queueing and pool scaling.
  2. Custom Agent Role Systems: Express roles through packs, prompts, formulas, and configuration (not hardcoded directories or classes).
  3. Custom Telemetry Scrapers: Telemetry is routed natively via OTLP; do not write supervisor console parsers.
  4. Custom Dashboards: Extend gascity-dashboard.
  5. Custom Federation Protocols: Use Wasteland.
  6. Architecture Encoded in Directory Layout: Keep identity and behavior in configuration, not filesystem paths.

6. Declarative Resource Reconciliation Model

Under the Gas City runtime architecture, the platform is treated as a set of declarative resources reconciled into running states on target environments.

Core Governing Invariant

[!IMPORTANT] No runtime object may be modified directly. Every runtime change must originate from an authored resource and be applied through Gas City reconciliation.

[!IMPORTANT] When introducing or modifying a capability, consult current docs.gascity.com first. If an equivalent capability already exists as a Pack, Formula, Order, or Agent configuration, adopt or extend it rather than creating a parallel implementation. Gas Town is a predecessor pack, not a second platform layer.

Platform Reuse Constitution

Before introducing any implementation, answer these questions in order: 1. Does an upstream owner already provide this? 2. Can Gas City express it? 3. Can a Pack express it? 4. Can a Formula execute it? 5. Can an Order trigger it? 6. Can an existing Agent perform it? 7. Can a Contract express it? 8. Can a Schema express it? 9. Can MCP expose it? 10. Can AG-UI present it? 11. Can a thin adapter bridge the gap?

If any answer is Yes: STOP. Use the existing platform capability. Do not introduce a new implementation.

Only after every option has been exhausted may a custom implementation be proposed, and it must include evidence explaining why the platform could not satisfy the requirement.

Authority Resolution Rules

Before writing code, determine who owns the capability. Allowed authorities in order of precedence: 1. Upstream 2. Gas City 3. Pack 4. Formula 5. Order 6. Agent 7. Contract 8. Schema 9. MCP 10. AG-UI 11. Thin Adapter 12. Repository (last engineering owner)

If ownership cannot be established, stop, produce evidence, and do not implement.

Platform Execution Order

READY Bead
        │
        ▼
Resolve Authority
        │
        ▼
Run Platform Reuse Constitution
        │
        ▼
Existing Capability Found?
        │
   ┌────┴────┐
   │         │
  Yes        No
   │         │
Reuse      Evidence
Capability  Collected
   │         │
   └────┬────┘
        ▼
Implement (Repository Implementation is the last resort)
        ▼
Verify
        ▼
Commit
        ▼
Merge Request
        ▼
CI
        ▼
Artifact
        ▼
Gas City Reconciliation
        ▼
Runtime Verification
        ▼
Receipt
        ▼
Close READY Bead

Customer Onboarding & Dependency Lifecycle

Organization (Bluefly Business Graph)
    │
    ▼
Customer (Bluefly Business Graph)
    │
    ▼
Contract (Bluefly Business Graph)
    │
    ▼
Product (Bluefly Business Graph)
    │
    ▼
Environment (Bluefly Business Graph)
    │
    ▼
Authority Resolution & Reuse Constitution
    │
    ▼
City Model (city.toml)
    │
    ├──────────────┐
    ▼              ▼
Policies       Capabilities
    │              │
    └──────┬───────┘
           ▼
       Gas City
           ▼
Runtime Configuration (Generated Projection)
           ▼
Runtime Services (Generated Projection)
           ▼
Runtime State (Runtime Persistence)

Declarative Reconciliation Diagram

Repository / Business Graph
    │
    ▼
Capability Definition (Pack / Artifact / Policy / Product)
    │
    ▼
Pack Build / OCI Compile
    │
    ▼
GitLab Registry / Pack Registry
    │
    ▼
Gas City Reconciler
    │
    ├─────────────┐
    ▼             ▼
City Model (city.toml)    Runtime Policies
    │             │
    └──────┬──────┘
           ▼
   Runtime Configuration & Services
           ▼
     Runtime Target
           ▼
    Runtime Persistence State (Dolt / DuckDB / Volumes)

Resource Registry Matrix

Resource Author Source of Truth Distribution Runtime Authority Reconciler
Organization Bluefly Platform Ledger Platform Bluefly Bluefly
Customer Customer Platform Ledger Platform Bluefly Bluefly
Contract Bluefly Platform Ledger Platform Bluefly Bluefly
Product Product Team Platform Ledger Platform Bluefly Bluefly
Environment Customer Platform Ledger Platform Bluefly Bluefly
Capability Definition Engineering Team Git Repository Pack Registry Gas City Gas City
Deployment Definition Engineering Team Git Repository Repository (Engineering Source) Gas City Gas City
City Model Engineering Team Git Repository (City) City Registry Gas City Gas City
Artifact GitLab CI GitLab Registry GitLab Registry Gas City Gas City
Policy Engineering Team Git Repository Policy Library Bluefly / Cedar Gas City (when expressed as Pack/Order config)
Runtime Configuration Gas City Gas City Generated Projection Gas City Gas City
Runtime Services Gas City Gas City Generated Projection Gas City Gas City
Runtime State Runtime Target Persistent Storage Runtime Persistence Runtime Target Gas City
Engineering Workspace None None None None None (Flagged as drift)
Legacy Ingress Config None None None None None (Flagged as drift)

7. Platform Architecture: The Five Orthogonal Systems

Rather than thinking in terms of directories or repository boundaries, the platform operates as five cooperating, orthogonal systems:

System Owns Responsibilities
Business Graph (Bluefly) Organizations, Customers, Contracts, Products, Environments, Repositories Governs customer onboarding, entitlement mapping, topology layouts, and billing lifecycles.
Work graph (Beads) Durable work units, dependencies, status Holds the work that survives sessions. Prefix-scoped; not a federated list.
Orchestration (Gas City) Agents, Formulas, Packs, Rigs, Events, Orders, city lifecycle Runs formulas as bead graphs and reconciles desired configuration to running sessions.
Capability Catalog (Packs) Reusable agents, formulas, orders, metadata, versioning Declares capabilities; the City is the local/root Pack plus deployment details.
Runtime Target Execution, persistence, health, lifecycle Runs workloads, maintains local persistence, and reports health.

8. Platform Backlog & Enduring Responsibilities

Beads (durable work)

  • Hold the work graph: tasks, dependencies, status, and prefix-scoped namespaces.
  • Survive sessions: work remains when agents crash or recycle.

Packs (reusable capabilities)

  • Package reusable capabilities: agents, formulas, orders, doctor checks (e.g. OpenClaw, Drupal).
  • Version capability contracts: declare constraints for dependencies and APIs.
  • Publish capability metadata: schemas, templates, and defaults.

Gas City (orchestration)

  • Resolve City models: compile pack.toml + city.toml; bind machine-local paths from .gc/site.toml.
  • Run Formulas: materialize Beads, fan ready work to Agents, gate on dependencies, drain when the method requires it.
  • Reconcile desired state: sessions, orders, health patrol.
  • Verify runtime health: gc doctor and doctor checks. Treat a flagless gc doctor as capable of starting managed Dolt until upstream clarifies.
  • Record execution receipts: structured outcome traces for governed work.