Product & Platform Authority Matrix¶
This matrix defines the canonical documentation and implementation authorities for Bluefly products and shared platform capabilities. Agents must consult it before creating documentation, services, CLIs, policies, schemas, UI libraries, or runtime capabilities.
The goal is not to put everything in one repository. The goal is to make ownership explicit and prevent duplicate implementations.
Product documentation authority¶
| Product | Canonical Vision | Canonical Architecture | Canonical API / Protocol | Canonical Runtime / Deployment | Canonical Roadmap |
|---|---|---|---|---|---|
| AMCS | Vision.md |
Architecture.md |
API.md |
Deployment.md |
Roadmap.md |
| OSSA | Vision.md |
Spec.md |
Protocol.md |
Runtime.md |
Roadmap.md |
| DUADP | Vision.md |
Spec.md |
Integrations.md |
Runtime.md |
Roadmap.md |
| ContextControl | Vision.md |
Architecture.md |
API.md |
Deployment.md |
Roadmap.md |
| ContractPlane | Vision.md |
Architecture.md |
API.md |
Deployment.md |
Roadmap.md |
| BluTown | Vision.md |
Architecture.md |
API.md |
Deployment.md |
Roadmap.md |
| Site Factory | Vision.md |
Architecture.md |
Integrations.md |
Deployment.md |
Roadmap.md |
| OtterMon | Vision.md when curated |
Architecture.md |
Integrations.md when curated |
Deployment.md when curated |
Roadmap.md when curated |
Do not create placeholder documents. Instantiate a canonical file only when curated content is ready.
Commercial product definition. Where a product has a curated commercial
definition — buyer, job to be done, positioning, packaging, pricing logic,
go-to-market, unit economics, north-star metric and kill criteria — it belongs
in a single Product-Definition.md alongside that product's Vision.md. It is
the commercial counterpart to Architecture.md and must not restate it.
Currently instantiated for:
products/AMCS/Product-Definition.md and
products/Technology-Reduction/Product-Definition.md.
Do not create one for a product that has no curated commercial content.
Commercial offer authority¶
A commercial offer is something a customer buys. It is not a platform
product and has no Architecture.md or API.md. Its canonical definition is a
Product-Definition.md, and its delivery artifacts live beside it.
| Offer | Canonical definition | Delivery method | Customer-facing copy | Reusable artifacts | Field authority |
|---|---|---|---|---|---|
| Technology Reduction | products/Technology-Reduction/Product-Definition.md |
Delivery-Method.md |
Sales-Package.md |
Delivery-Kit.md |
data-model.yaml |
| Migration Factory | products/migration-factory/offer.md |
— | — | — | — |
Technology Reduction comprises Maintenance Review (entry), Safe Removal (remediation) and Maintenance Watch (recurring). These are stages of one offer, not separate products, and must not be given separate authorities.
Known duplicate, not introduced by this entry: products/migration-factory/offer.md
and products/migration-factory/migration-factory-offer.md are byte-identical.
One should be removed and the other made canonical; recorded here so the next
author does not copy the pattern.
Platform implementation authority¶
| Capability | Canonical authority | Boundary |
|---|---|---|
| Shared agents | blueflyio/agentictools/agents |
Reusable agent definitions; not work state or project-local context. |
| Shared skills | blueflyio/agentictools/skills |
Reusable procedural knowledge. |
| Shared plugins | blueflyio/agentictools/plugins |
Reusable harness/agent plugins. |
| Agent marketplace | blueflyio/agentictools/agentic-marketplace |
Discovery/browse/install surface over OSSA/DUADP assets; not a second source registry. |
| Agent specification | blueflyio/ossa/openstandardagents |
OSSA schemas, validation, packaging, and agent-definition tooling. |
| Agent/service discovery | blueflyio/duadp/duadp |
DUADP discovery protocol. |
| Operator CLI | blueflyio/blu/blu-cli |
General Bluefly operator/developer commands and control-plane transport. |
| Context CLI | blueflyio/contextcontrol.ai/context-cli |
ContextControl-specific CLI behavior only. |
| Gas City reusable behavior | blueflyio/blu/blucity-packs |
Packs, formulas, reusable factory capabilities, commands, and checks. |
| Durable work state | Beads | Work graph, dependencies, blockers, priority, status, and receipts. |
| Agent/session execution | Gas City | Dispatch, sessions, events, formulas, packs, and worktree mechanics. |
| Source / CI / release | GitLab | Source authority, merge gates, CI, packages, containers, releases, and deployment provenance. |
| Shared CI | blueflyio/gitlab_components |
Reusable CI/CD components; consumer projects should not duplicate common pipelines. |
| GitLab security governance | blueflyio/security-policies |
GitLab-native security/compliance policies. |
| Authorization policy library | blueflyio/cedar-policies |
Reusable Cedar policies and authorization rules. |
| API schema registry | blueflyio/agent-platform/tools/api-schema-registry |
OpenAPI/schema discovery, registration, validation, metadata, and retrieval. |
| Shared UI system | blueflyio/agent-platform/tools/studio-ui |
Reusable React and Drupal Canvas/SDC design components for the ecosystem. |
| Testing / verification | blueflyio/dragonfly/dragonfly |
Shared evidence-backed verification where it adds value beyond native framework tests. |
| Contract SDK | blueflyio/contractplane.ai/contractplane-sdk |
ContractPlane client/SDK implementation. |
| Runtime composition | blueflyio/agent-platform/infra/agent-docker |
Reproducible containers, services, runtime configuration, and composition. |
| Infrastructure deployment | blueflyio/agent-platform/infra/iac |
Provider infrastructure, host bootstrap, networking, storage, and runtime projection. |
| Secure mesh networking | blueflyio/agent-platform/infra/agent-tailscale |
Tailscale-specific reusable infrastructure. |
| Drupal local Gas City integration | blueflyio/agent-platform/ddev-addons/ddev-gascity |
DDEV development integration for Gas City. |
| Drupal local BLU integration | blueflyio/agent-platform/ddev-addons/ddev-agent-blu |
DDEV development integration for BLU agents. |
| Drupal local OtterMon integration | blueflyio/agent-platform/ddev-addons/ddev_ottermon |
DDEV development integration for OtterMon. |
Product boundary¶
The factory architecture is intentionally simple:
- Drupal / ContextControl — human and customer frontend, content, Canvas, governed context, approvals, and factory UI.
- Gas City — backend operator and execution plane.
- Beads — durable work authority.
- GitLab — source, CI, packages, releases, and deployment provenance.
- ContractPlane + Cedar — contract/policy integration and authorization.
- Studio UI — shared UI/component system.
- Agent Docker + IaC — portable runtime composition and deployment.
No project should recreate another authority's capability merely for convenience.
Consolidation review¶
The following projects require capability review before further expansion because their stated responsibilities overlap the current factory architecture:
agent-platform/services/agent-routeragent-platform/services/workflow-engineagent-platform/services/agentic-flowsagent-platform/services/agent-meshagent-platform/services/agent-brainagent-platform/services/compliance-engineagent-platform/services/foundation-bridgeagent-platform/services/a2a-collectoragent-platform/services/agent-traceragent-platform/services/agent-protocol
Likely destinations must be proven from code and consumers, not assumed. Candidate convergence areas are Gas City, ContextControl, ContractPlane/Cedar, DUADP, LiteLLM/OpenClaw, OtterMon/OpenTelemetry, and OSSA.
Known merge/archive candidates¶
agent-platform/tools/technical-docs— curate unique durable material into BluCity-Docs, prove parity, then archive.agent-platform/tools/agent-buildkit— evaluate moving user-facing commands intoblu-cli; retain an independent library only when it has a clear reusable responsibility.agent-platform/apps/node-agent-marketplace— compare with the Agentic Marketplace and converge on one marketplace product.
Domain models¶
The repositories under agent-platform/models are domain/schema authorities unless actual trained model artifacts are explicitly present.
- RFP — RFP domain schemas and canonical data types.
- Orchestration — orchestration schemas/specifications; review against current Gas City schemas before expanding.
- AgentDev — agent development schemas/types/contracts.
- BluGuide — purpose and ownership must be clarified before expansion.
Trained or fine-tuned models, adapters, and weights should use an appropriate GitLab model/artifact mechanism and must not be conflated with schema repositories.
Rules¶
- Conceptual extraction: Do not move historical files verbatim into canonical locations. Extract current concepts and preserve provenance.
- Minimum viable documentation: Do not create placeholders.
- Reference authority: The Capability Registry remains the authority for capability IDs and confidence.
- No workstation identity: Durable documentation must not contain personal usernames, home-directory paths, or machine-specific workspace paths.
- Reuse before build: Reuse upstream and existing Bluefly capabilities before creating another service, registry, scheduler, workflow engine, memory system, CLI, or UI library.
- Implementation stays with the owner: BluCity-Docs defines doctrine and product architecture; source implementation belongs in the owning project.
- Evidence before archive: Archive only after unique capabilities, consumers, data, history, and migration parity are proven.