Skip to content

The Bluefly Constitution

This document is authority. It is the single document you would hand a new agent to rebuild the system correctly if every repository were deleted tomorrow. Its canonical machine-readable form is constitution/constitution.yaml; CLAUDE.md, AGENTS.md, ai.json, and llms.txt are generated projections of it.

Version 1.0.0 · Ratified 2026-06-20 · Owner: [email protected]

I. Mission

Bluefly exists to manufacture governed digital organizations.

II. Vision

Any organization should be able to purchase a Product, deploy a Factory, and receive a governed digital organization, without needing to understand the underlying systems.

III. The Axiom

Bluefly owns composition. Bluefly does not own implementation.

Every future decision is tested against this. The moment someone proposes "let's build our own scheduler / agent runtime / chat framework / orchestration engine," the Constitution rejects it. Bluefly never becomes another platform. Bluefly is the thing that assembles platforms into products.

Supporting axioms: - factory.yaml is the single source of truth; every output is generated and authoritative nowhere. - Compose first. Custom code is the last option. Exhaust Drupal, AGUI, MCP, Gas City, and existing Bluefly capability before building anything. - Ship Products, not technology. The customer buys a Product; the Factory is how Bluefly manufactures it.

IV. Authority Order

1. Bluefly Constitution      ← this document (supreme)
2. Product Contracts
3. Factory Contracts
4. Generated Outputs
5. Implementation Systems

If two documents disagree, the higher authority wins. Any document (CLAUDE.md, AGENTS.md, a factory, a README, an architecture note) that contradicts the Constitution is wrong and must be corrected or superseded. All prior architecture documents are superseded by this one.

Nothing may redefine the Constitution. Products conform to it. Factories conform to it. Agents conform to it. Documentation conforms to it. Generated artifacts conform to it.

V. Architecture

PRODUCT  ─▶  FACTORY  ─▶  OUTPUTS  ─▶  DOMAINS  ─▶  SYSTEMS
  • Product: what the customer buys (e.g. AMCS Healthcare Factory). The root of everything.
  • Factory: how Bluefly manufactures the Product. Defined by factory.yaml.
  • Outputs: generated artifacts, authoritative nowhere.
  • Domains: ownership boundaries (seven).
  • Systems: the upstreams the outputs compile into.

The Rule (hard to violate): Product → Factory → Output → Capability → System. If a feature can't be expressed this way, it is at the wrong layer.

The Compile Chain (Gas City execution): Factory ─compile▶ Pack ─imports▶ Formula ─instantiates▶ Order ─dispatches▶ Agent ─performs▶ Bead. Factory is a Bluefly primitive. Everything below it is Gas City. Never rebuild Gas City.

VI. Authority Boundaries (ownership)

Bluefly owns Product, Factory, Outputs, Composition. Each upstream owns its implementation:

Concern Owner
Business authority (content, structure, workflows, templates, recipes, permissions, business facts) Drupal
Execution Gas City
Memory authority ContextControl
Contract authority ContractPlane
Policy authority Cedar
Verification authority Dragonfly
Factory authoring UX (audience: builder) Canvas
Factory runtime UX (audience: user) AGUI (extended, never replaced)
Operator edge UX (audience: operator) OpenClaw (no policy/memory/governance/deployment/content authority)
Infrastructure UX (audience: administrator) Gas City Dashboard
Transport (discovery/routing/federation) A2A (never authority)

The seven domains (authority, governance, runtime, experience, network, delivery, marketplace) are ownership boundaries, not contract sections. In each, Bluefly owns composition; the upstream owns implementation.

VII. Compilation Rules

  • factory.yaml compiles top-down; nothing downstream becomes authoritative.
  • Outputs are keyed by the seven domains and regenerated from the contract, never hand-edited into authority.
  • The Factory Contract gate (scripts/factory.py check) must pass before a Factory is real.

VIII. Design Rules

  • Domains are ownership boundaries; outputs are generated artifacts.
  • AGUI is extended, never replaced. The four experience surfaces stay distinct (four audiences).
  • A2A is transport, never governance, memory, identity, or execution.
  • Factory compiles into Gas City primitives; never rebuild Gas City.
  • "Let's build another service" is answered by "which Product, Factory, Output, Domain emits it?"; no answer means it doesn't belong.

IX. Open-Source-First Rules

Evaluate before any custom code: Drupal Core/CMS/Recipes/Site-Templates/AI · AGUI · MCP · Gas City · existing Bluefly capability. Never build: workflow engines, schedulers, supervisors, orchestration runtimes, chat frameworks; those live below the Factory boundary, in Gas City.

X. Product Strategy

Bluefly sells Factories, not technology. Product line: AMCS Factories. Catalog: amcs-healthcare (first), amcs-higher-education, amcs-municipality, amcs-membership, amcs-nonprofit. The operator API is blu-cli (blu factory create|deploy|verify|audit|upgrade|publish|recover); gc remains the runtime API beneath it.

XI. Conformance

Every Product, Factory, Agent, document, and generated artifact must declare and demonstrate conformance to this Constitution. To test any proposal, ask: "Show me where this fits in the Constitution." If it can't be placed, it is off track.

  • scripts/constitution.py project regenerates the projections (CLAUDE.md, AGENTS.md, ai.json, llms.txt) from constitution.yaml.
  • scripts/constitution.py verify detects projection drift (fails if a projection was hand-edited out of sync).
  • scripts/constitution.py conform <file> checks a document/contract does not contradict the Authority Order.