SEPARATION OF DUTIES - AI CONTEXT REFERENCE

MASTER CONFIGURATION: $BARE_REPOS/config.json (v0.1.0)

AUTHORITATIVE SOURCE: GitLab Wiki - Separation of Duties

See Also: OSSA Three-Tier Architecture

USE TOKENS: All paths use tokens from master config: $NAS_MOUNT, $BARE_REPOS, $WIKIS_BASE, $NPM_SCOPE, etc.

This local file provides AI assistant context. The authoritative documentation lives in the GitLab Wiki.

Last Synced: 2026-01-27 Last Updated: 2026-01-27 (Master config integration) Source: Project-Inventory.md + WIKIs directory comprehensive audit + OSSA v0.3.2 implementation

---

16 Canonical OSSA Agents

Service Accounts: Use agent name directly (NO bot- prefix)

---

GitLab Duo Agent Platform

External Agent: bluefly-platform

Single gateway to the OSSA agent mesh via GitLab Duo.

@bluefly-platform mention
    � GitLab Duo triggers CI job
    � CI job calls https://mesh.blueflyagents.com/v1/duo/route
    � Cloudflare Tunnel routes to agent-mesh.tailcf98b3.ts.net:3005 (always-on)
    � agent-mesh routes to appropriate OSSA agent
    � Agent executes and responds in GitLab

CRITICAL: Agents MUST work without home computer or network. All services run on always-on infrastructure accessible via Tailscale MagicDNS.

AI Catalog Item: gid://gitlab/Ai::Catalog::Item/2028 Enabled In: blueflyio group

Domain: blueflyagents.com

• mesh.blueflyagents.com � Cloudflare Tunnel � agent-mesh.tailcf98b3.ts.net:3005 (always-on)
• api.blueflyagents.com � Cloudflare Tunnel � agent-mesh.tailcf98b3.ts.net:3005 (always-on)
• brain.blueflyagents.com � agent-brain.tailcf98b3.ts.net:3003 (via Tailscale)

CRITICAL: All services accessible via Tailscale MagicDNS. No dependency on home network or Mac laptop.

---

Three-Tier OSSA Architecture

�                    TIER 1: AGENT DEFINITIONS                     �
�                    /platform-agents/                             �
�                                                                  �
�  - 16 canonical OSSA agent manifests (YAML)                     �
�  - registry.yaml (master catalog v4.0.0)                        �
�  - TypeScript monorepo                                           �
�  - Deploys to: GitLab Duo, K8s                                  �
�
                              �

�                 TIER 2: INFRASTRUCTURE PACKAGES                  �
�                    /common_npm/agent-*                           �
�                                                                  �
�  agent-protocol  � MCP server, auth, encryption                 �
�  agent-mesh      � gRPC coordination, discovery                 �
�  agent-brain     � Vector DB, semantic memory                   �
�  agent-router    � LLM gateway, multi-model                     �
�  agent-tracer    � OTEL tracing, metrics                        �
�  compliance-engine � FedRAMP/HIPAA/SOC2                         �
�
                              �

�               TIER 3: PLATFORM IMPLEMENTATION                    �
�                    /OssA/lab/gitlab-agent_ossa/                  �
�                                                                  �
�  - Go implementation for GitLab Agent                           �
�  - 13 capabilities (k8s-api, flux, runner, workspaces...)      �
�  - Adapters wrapping upstream modules                           �
�  - 7-phase turn lifecycle orchestrator                          �
�

Quick Decision: Where Does It Go?

---

Core Agent Platform Projects

platform-agents

Purpose: Agent manifest registry + Default Orchestrator Agent

RESPONSIBLE FOR

1. Agent Manifest Storage

   • OSSA v0.3.2 manifest files (.ossa.yaml)
   • Agent catalog (catalog.json)
   • Manifest versioning
   • Manifest discovery/querying

2. Default Orchestrator Agent (THE DEFAULT AGENT)

   • default_agents Drupal module
   • OrchestratorAgent service
   • Agent discovery
   • Task routing (LLM-based via agent-router)
   • Workflow coordination
   • Agent health monitoring

3. Manifest Validation

   • Uses @bluefly/openstandardagents npm package CLI
   • ManifestValidator service

4. CI Components

   • GitLab CI components for agent validation
   • Agent testing components
   • Agent deployment components

5. GitLab Duo Integration

   • Duo agent configurations
   • Duo workflow definitions

6. Webhooks (Production Authoritative)

   • Agent trigger webhooks
   • Event handlers
   • GitLab Webhook Auto-Fix System (Production ingress gateway)
     • Webhook signature verification
     • Event routing to orchestrator
     • Idempotency key management
     • Queue management (Redis/NATS)
     • Rate limiting and backpressure
   • Note: agent-buildkit webhook server is dev-only tooling

NOT RESPONSIBLE FOR

• Agent Execution � agent-buildkit
• OSSA Spec Definition � openstandardagents
• OSSA Compliance Services � ai_agents_ossa Drupal module
• Multi-Agent Orchestration � ai_agents_orchestra Drupal module
• CI/CD Components � gitlab_components
• Agent Routing Service � agent-router (separate service)
• Protocol Adapters � ai_agents_client Drupal module
• BuildKit Services � agent-buildkit
• Distributed Coordination � agent-mesh
• Observability � agent-tracer
• Knowledge Graph � agent-brain
• Service Account Token Management � agent-mesh (buildkit must call mesh API, not parse registry.yaml)
• Vast.ai Deployment Logic � agent-router (buildkit must request via router API, not implement provider logic)

Dependencies

• ai_agents_ossa - For OSSA compliance (permissions, access tiers)
• @bluefly/openstandardagents - For manifest validation
• agent-router - For LLM-based routing (orchestrator uses this)

---

agent-buildkit

Purpose: Agent lifecycle management, execution, deployment, CLI

RESPONSIBLE FOR

1. Agent Execution

   • Running agents
   • Execution runtime
   • Process management

2. Agent Lifecycle

   • Build/compile agents
   • Deploy agents
   • Agent registry management
   • Swarm coordination

3. BuildKit CLI

   • buildkit agents list
   • buildkit agents create
   • buildkit agents spawn
   • buildkit agents deploy
   • buildkit thinking (CLI wrapper - calls agentic-flows for sequential thinking)
   • buildkit orchestration (CLI wrapper - calls platform-agents orchestrator)
   • buildkit gitlab-kg (CLI wrapper - calls agent-brain)

4. Multi-Platform Deployment

   • Kubernetes
   • Docker
   • Serverless
   • Drupal modules

5. GitLab Webhook Auto-Fix System (Dev/CLI Tooling Only)

   • Local webhook server for development/testing
   • MR analysis and remediation orchestration
   • CLI commands for webhook management
   • Note: Production webhook ingress belongs in platform-agents

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• OSSA Spec � openstandardagents
• Orchestration Logic � platform-agents (orchestrator) or ai_agents_orchestra
• Flow Semantics � agentic-flows (buildkit only provides CLI wrappers like buildkit thinking)
• Flow Execution � workflow-engine (buildkit dispatches to workflow-engine, doesn't execute flows)
• Distributed Coordination � agent-mesh
• Knowledge Graph Storage � agent-brain (uses Neo4j/Qdrant)
• Production Webhook Ingress � platform-agents (buildkit webhook server is dev-only)
• Service Account Token Management � agent-mesh (must call mesh API: /v1/service-accounts/gitlab/:agentType/token)
• Vast.ai Deployment Orchestration � agent-router (must request via router API: /api/v1/vastai/deploy)

---

openstandardagents

Purpose: OSSA specification definition

RESPONSIBLE FOR

1. OSSA Specification

   • JSON Schema definitions
   • Specification documentation
   • Version management (v0.3.0, v0.3.2, etc.)

2. OSSA CLI Package

   • @bluefly/openstandardagents npm package
   • ossa validate command
   • ossa generate command
   • TypeScript types

3. Reference Implementations

   • Example agents
   • Best practices
   • Migration guides

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• Drupal Integration � Drupal modules

---

TypeScript Services (common_npm/)

agent-brain

Purpose: Knowledge graph & vector database service

RESPONSIBLE FOR

1. Knowledge Graph
   • Neo4j knowledge graph
   • Qdrant vector search
   • Relationship mapping
   • Semantic search
   • RAG pipelines

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• Orchestration � platform-agents or agent-brain orchestration layer

---

agent-chat

Purpose: Multi-modal AI chat interface

RESPONSIBLE FOR

1. Chat Interface
   • LibreChat integration
   • Multi-modal chat
   • Chat UI components

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• LLM Routing � agent-router

---

agent-mesh

Purpose: Distributed agent coordination with Tailscale + GitLab Duo Gateway

CRITICAL REQUIREMENT: Agents MUST work without home computer or network. Agent-mesh runs on always-on infrastructure (Vast.ai or dedicated server) accessible via Tailscale MagicDNS: agent-mesh.tailcf98b3.ts.net:3005

RESPONSIBLE FOR

1. Distributed Coordination

   • Agent-to-agent communication (WebSocket, gRPC, HTTP)
   • Automatic service discovery (Tailscale MagicDNS)
   • Task distribution
   • Load balancing
   • Autonomous Operation: Service runs on always-on infrastructure, listens on Tailscale IP (not localhost)

2. Mesh Services

   • Discovery service
   • Coordinator service
   • Transport service (A2A transport for agent-to-agent communication)
   • Auth service
   • Service Discovery: All services use Tailscale MagicDNS (no localhost/hardcoded IPs)
   • A2A (Agent-to-Agent) Transport: Service-to-service communication fabric, message routing between agents

3. GitLab Duo Gateway

   • /v1/duo/route - Routes requests to OSSA agents
   • /v1/duo/agents - Lists available agents
   • /v1/duo/health - Health check
   • Event-to-agent routing (pipeline_failed � pipeline-remediation)
   • Public Access: Via Cloudflare Tunnel (mesh.blueflyagents.com � agent-mesh.tailcf98b3.ts.net:3005)

4. GitLab Service Account Management (NEW - 2026-01-05)

   • Per-agent token management (separation of duties)
   • Token rotation endpoints (/v1/service-accounts/gitlab/:agentType/rotate)
   • Service account status (/v1/service-accounts/gitlab)
   • Rotation key management
   • Token metadata tracking (version, expiry, source)
   • Default token fallback for agents without dedicated tokens

5. Agent Types

   • Orchestrator, Worker, Monitor, Integrator, Governor, Critic

6. Vast.ai Registry (2026-01-07)

   • Vast.ai instance registration
   • Ephemeral GPU instance discovery
   • Instance health monitoring
   • Event routing to Vast.ai instances

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• Default Orchestrator � platform-agents
• Knowledge Graph � agent-brain
• Cloudflare Tunnel � Runs on GL-iNet router or always-on infrastructure (not agent-mesh)

Infrastructure Requirements

• Deployment: Always-on infrastructure (Vast.ai always-on instance or dedicated server)
• Network: Tailscale mesh network (independent of home network)
• Service Discovery: Tailscale MagicDNS (agent-mesh.tailcf98b3.ts.net:3005)
• Public Access: Cloudflare Tunnel routes to Tailscale MagicDNS hostname
• Configuration: Listens on TAILSCALE_IP environment variable (not localhost)

---

agent-protocol

Purpose: MCP (Model Context Protocol) server implementation - TOOLS/RESOURCES ONLY (NOT RUNTIME)

RESPONSIBLE FOR

1. MCP Protocol (Control Plane)

   • MCP server implementation (JSON-RPC 2.0)
   • Tool registration and exposure
   • Resource registration and exposure
   • Context routing
   • OpenAPI sync
   • Agent invocation protocol (MCP client/server communication)
   • Trace Propagation: Integrates with agent-tracer for distributed tracing across MCP calls

2. MCP Server Management

   • Exposing tools to LLMs via MCP
   • Exposing resources (files, data) via MCP
   • MCP server discovery
   • MCP server health checks

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• MCP Server Registry � mcp_registry Drupal module
• Agent Execution Runtime � agent-buildkit (agent-protocol exposes tools, buildkit executes)
• LLM Routing � agent-router (separate service)
• Vast.ai Deployment � agent-router (infrastructure/deployment/vastai)
• Workflow Execution � workflow-engine (agent-protocol exposes tools, workflow-engine executes)

---

agent-router

Purpose: LLM-based agent routing service + Vast.ai deployment orchestration

RESPONSIBLE FOR

1. Intelligent Routing

   • LLM-based task analysis
   • Agent capability matching
   • Routing recommendations

2. Routing API

   • /api/v1/chat/completions endpoint
   • Routing queries

3. LibreChat Integration

   • LibreChat integration
   • Drupal SSO

4. Vast.ai Deployment Infrastructure (AUTHORITATIVE)

   • Vast.ai event schemas (infrastructure/deployment/vastai/events.ts)
   • Vast.ai security (HMAC, replay protection, rate limiting)
   • Vast.ai worker orchestration
   • Vast.ai provider integration
   • Deployment API (/api/v1/vastai/deploy)
   • Cost API (/api/v1/vastai/costs)
   • Routing API (/api/v1/route - cost-aware routing decisions)
   • Enforcement: agent-buildkit MUST request deployments via router API, NOT implement provider logic

5. Middleware

   • Health metrics middleware
   • OpenAPI validation middleware

NOT RESPONSIBLE FOR

• MCP Protocol � agent-protocol (MCP is agent-protocol's responsibility)
• Default Orchestrator � platform-agents (orchestrator uses agent-router)
• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit

---

agent-studio

Purpose: Cross-platform IDE suite

RESPONSIBLE FOR

1. IDE Suite
   • macOS, iOS, Electron, VS Code, Web
   • Agent management UI
   • Development tools

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• Agent Definitions � platform-agents

---

agent-tracer

Purpose: Distributed observability and tracing - INTEGRATES WITH agent-protocol

RESPONSIBLE FOR

1. Observability

   • Distributed tracing (OpenTelemetry)
   • Performance monitoring
   • Phoenix integration
   • Prometheus metrics
   • Grafana dashboards

2. Vector Graph Architecture

   • Knowledge graph integration for trace analysis

3. MCP Trace Propagation

   • Integrates with agent-protocol for distributed tracing across MCP calls
   • Trace context propagation via MCP protocol
   • End-to-end observability for agent invocations

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• Knowledge Graph Storage � agent-brain
• MCP Protocol Implementation � agent-protocol (agent-tracer integrates with it, doesn't own it)

---

agent-tailscale

Purpose: Tailscale integration for distributed agent networking

RESPONSIBLE FOR

1. Tailscale Integration
   • Tailscale networking
   • VPN configuration
   • Network routing

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Distributed Coordination � agent-mesh (uses Tailscale)

---

agentic-flows

Purpose: OpenAPI-first agentic flow definitions + templates - OWNS SEQUENTIAL THINKING (8-STAGE)

RESPONSIBLE FOR

1. Flow Semantics (Definition Layer)

   • OpenAPI-first flow definitions
   • Flow templates (including "sequential thinking" 8-stage spec)
   • Versioned flow specifications
   • Flow contracts and interfaces
   • Cognitive workflow patterns (8-stage sequential thinking, reflection, planning, etc.)

2. Flow Publishing

   • Publishes flow specs to workflow-engine (registry/artifacts)
   • Signed artifacts + integrity checks
   • Flow versioning and resolution

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Flow Execution � workflow-engine (state management, step runners, DAG execution)
• Agent Runtime � agent-buildkit (process/container lifecycle)
• Multi-Agent Workflows � ai_agents_orchestra (Drupal module)

---

compliance-engine

Purpose: Enterprise compliance validation and enforcement - OWNS ALL CEDAR POLICIES

RESPONSIBLE FOR

1. Cedar Policy Management (Authoritative)

   • ALL Cedar policy definitions
   • Cedar policy evaluation engine
   • Cedar policy enforcement decisions
   • Policy version control
   • Policy storage and retrieval

2. Policy Enforcement

   • Automated compliance checking
   • Security policies (RBAC, encryption, audit)
   • Regulatory compliance (NIST 800-53, FedRAMP, SOC 2)
   • Governance
   • Audit trail

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• OSSA Compliance � ai_agents_ossa
• Agent Execution � agent-buildkit

---

foundation-bridge

Purpose: Integration bridge for foundation model providers

RESPONSIBLE FOR

1. Foundation Model Integration
   • Provider integration
   • Model bridging
   • Provider abstraction

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• LLM Routing � agent-router
• Agent Execution � agent-buildkit

---

workflow-engine

Purpose: Production workflow execution and orchestration - RUNTIME EXECUTION LAYER

CRITICAL CLARIFICATION: workflow-engine executes Langflow workflows (visual builder, DAG execution), NOT multi-agent orchestration semantics. Orchestration logic belongs in ai_agents_orchestra (Drupal module) or platform-agents (orchestrator agent).

RESPONSIBLE FOR

1. Workflow Execution (Runtime Layer)

   • Executes workflows (DAG/steps)
   • State management and persistence
   • Step dispatch and coordination
   • Retries at workflow level
   • Error handling and recovery
   • Workflow lifecycle management
   • Scope: Langflow visual workflows, NOT orchestration semantics

2. Flow Runtime Integration

   • Receives flow definitions from agentic-flows
   • Calls agent-protocol/tools/mesh/agent-buildkit as needed
   • Workflow registry and resolution
   • Runtime observability (trace per step + correlate flow/run IDs)

3. Visual Workflow Building (Langflow)

   • Langflow-Drupal integration
   • Visual workflow builder UI
   • Custom Drupal components

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit (workflow-engine dispatches to buildkit)
• Flow Definitions � agentic-flows (workflow-engine executes flows, doesn't define them)
• Multi-Agent Orchestration Semantics � ai_agents_orchestra (Drupal module) or platform-agents (orchestrator agent)
• Orchestration Logic � ai_agents_orchestra handles multi-agent workflows, coordination patterns

---

Other TypeScript Services

studio-ui

Purpose: React UI component library - Single source of truth for ALL UI components

RESPONSIBLE FOR

1. UI Components (77 total)

   • Forms: Input, Checkbox, Switch
   • Agent: ChatInterface, TokenUsageMeter
   • Charts: Chart components
   • Dashboard: Layouts, metrics displays
   • Navigation: Nav components, breadcrumbs
   • Theme: Design system, tokens
   • UI Primitives: Cards, badges, buttons, alerts

2. Design System

   • Tailwind CSS configuration
   • Design tokens
   • Component theming
   • Dark mode support

3. Component Library

   • Radix UI primitives
   • Accessible components (ARIA)
   • Responsive layouts
   • TypeScript types

NOT RESPONSIBLE FOR

• Business Logic → Consuming projects (agent-chat, agent-studio, agentdash, agent_marketplace)
• API Integration → Consuming projects
• State Management → Consuming projects
• Routing → Consuming projects
• Backend Services → agent-* packages

INTEGRATION STATUS (2026-01-27)

• ✅ agent-chat: ChatInterface, TokenUsageMeter, message components
• ✅ agent-studio: Full component library, forms, dashboards
• ✅ agentdash: DashboardShell, metrics, charts, monitoring
• ✅ agent_marketplace: React frontend with cards, search, filters

Rules

• ❌ NEVER duplicate UI components in other projects
• ✅ ALWAYS import from @bluefly/studio-ui
• ✅ ALL React UI components MUST be in studio-ui
• ✅ Consuming projects extend components via composition, NOT duplication

---

Drupal Modules

ai_agents_ossa (Drupal Module)

Purpose: OSSA compliance services for Drupal

RESPONSIBLE FOR

1. OSSA Compliance

   • OssaPermissionResolver - Access tier enforcement
   • Separation of duties
   • Policy enforcement
   • Approval workflows
   • Delegation tokens

2. OSSA Runtime

   • OSSA manifest loading
   • Capability resolution
   • Runtime bindings

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Orchestration � platform-agents (orchestrator) or ai_agents_orchestra
• Agent Execution � agent-buildkit

---

ai_agents_orchestra (Drupal Module)

Purpose: Multi-agent workflow orchestration

RESPONSIBLE FOR

1. Workflow Orchestration

   • Multi-agent workflows
   • DAG resolution
   • Parallel execution
   • Sequential execution

2. Workflow Templates

   • Pre-built workflows
   • Workflow patterns

NOT RESPONSIBLE FOR

• Default Orchestrator Agent � platform-agents (default_agents module)
• Agent Manifests � platform-agents
• OSSA Compliance � ai_agents_ossa

---

ai_agents_client (Drupal Module)

Purpose: Protocol adapters and client services

RESPONSIBLE FOR

1. Protocol Adapters

   • ProtocolRegistry
   • ProtocolAdapterInterface
   • MCP adapter
   • A2A adapter
   • OpenAI adapter
   • Claude adapter
   • GitLab Duo adapter
   • HTTP adapter

2. Client Services

   • HTTP client wrappers
   • API clients

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Orchestration � platform-agents or ai_agents_orchestra
• OSSA Compliance � ai_agents_ossa

---

Other Drupal Modules

---

Infrastructure Projects

gitlab_components

Purpose: Reusable CI/CD components

RESPONSIBLE FOR

1. CI/CD Components
   • GitLab CI templates
   • Component library
   • Reusable jobs
   • 60+ components for OSSA workflows

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• OSSA Spec � openstandardagents
• Agent-Specific CI � platform-agents

---

llm-platform

Purpose: Drupal 11 AI orchestration platform (main application)

RESPONSIBLE FOR

1. Main Application
   • Drupal 11 installation
   • Module integration
   • Admin UI
   • User interface

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Drupal Modules � all_drupal_custom/modules/
• Agent Execution � agent-buildkit

---

agent-docker

Purpose: Docker/Kubernetes containerization + NAS infrastructure orchestration

RESPONSIBLE FOR

1. Containerization

   • Docker images
   • Kubernetes manifests
   • Container orchestration

2. NAS Infrastructure (Synology NAS)

   • Container Manager deployments (NAS)
   • Docker Compose for always-on services (GitLab webhook server, agent-mesh, MinIO, PostgreSQL, Redis, cloudflared)
   • NAS-specific deployment configurations
   • MUST use @bluefly/agent-tailscale for all networking (subnet routing, DNS, service discovery)

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Agent Execution � agent-buildkit
• CI/CD � gitlab_components
• Tailscale Code � @bluefly/agent-tailscale (agent-docker uses it, doesn't own it)

---

api-schema-registry

Purpose: Master OpenAPI 3.1 specifications and shared schemas

RESPONSIBLE FOR

1. OpenAPI Schemas
   • Master OpenAPI 3.1 specs
   • Shared schemas
   • Schema registry

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• OSSA Spec � openstandardagents
• API Implementation � Individual services

---

technical-docs

Purpose: Unified documentation portal

RESPONSIBLE FOR

1. Documentation
   • Wiki content
   • Technical documentation
   • Architecture docs

NOT RESPONSIBLE FOR

• Agent Manifests � platform-agents
• Code � Individual projects

---

Comprehensive Agent-Flow Separation of Duties

KEY PRINCIPLE: BuildKit is described as the orchestrator of project CLIs (router/brain/workflow/etc.) - a control surface, not the canonical home for workflow semantics. 

Complete Service Ownership Matrix

Practical "Fix the Mix-Up" Rule Set

1. Flow semantics live in agentic-flows (including "sequential thinking" as a versioned template)
2. Flow execution lives in workflow-engine (state machine + step dispatch)
3. Agent execution lives in agent-buildkit (sandbox/container/process primitives)
4. Tools exposure lives in agent-protocol (MCP servers only)
5. Routing lives in agent-router (model/provider/cost/GPU decisions)
6. All allow/deny decisions live in compliance-engine; other services only enforce

Agent-Flow Integration Map

flowchart TB
  %% Clients
  subgraph Clients
    CHAT[agent-chat]
    STUDIO[agent-studio]
  end

  %% Control plane
  subgraph ControlPlane
    ROUTER[agent-router]
    COMP[compliance-engine]
    MESH[agent-mesh]
    TRACER[agent-tracer]
  end

  %% Flow definition + execution
  subgraph FlowPlane
    FLOWS[agentic-flows<br/>flow definitions/templates]
    WF[workflow-engine<br/>workflow runtime]
  end

  %% Agent runtime + tools
  subgraph RuntimePlane
    BUILDKIT[agent-buildkit<br/>agent execution runtime]
    PROTO[agent-protocol<br/>MCP tools]
    BRAIN[agent-brain]
  end

  %% Entry
  CHAT --> ROUTER
  STUDIO --> ROUTER

  %% Policy gates
  ROUTER -->|authz| COMP
  WF -->|authz per step| COMP
  PROTO -->|tool authz| COMP
  BUILDKIT -->|authz for exec| COMP

  %% Flow definition -> execution
  FLOWS -->|publish/resolve flow spec| WF

  %% Dispatch/transport
  ROUTER -->|dispatch| MESH
  MESH -->|invoke workflow| WF

  %% Workflow executes via runtime/tools
  WF -->|run step| BUILDKIT
  WF -->|tool call| PROTO
  PROTO --> BRAIN

  %% Observability
  CHAT -.traceparent/baggage.-> TRACER
  STUDIO -.traceparent/baggage.-> TRACER
  ROUTER -.-> TRACER
  MESH -.-> TRACER
  WF -.-> TRACER
  BUILDKIT -.-> TRACER
  PROTO -.-> TRACER
  BRAIN -.-> TRACER
  COMP -.decision_id.-> TRACER

What BuildKit Can Own Without Violating Separation

If BuildKit exposes "sequential thinking" to users/devs, scope it to:

• A built-in flow template ID (e.g., flow://sequential-8) stored in agentic-flows
• A CLI convenience wrapper: buildkit run flow sequential-8 ... → calls workflow-engine API/CLI
• Execution primitives only (step runner, retries, timeouts, sandboxing), not the flow semantics

---

🚨 Critical Violations to Fix

These violations exist in the current codebase and MUST be fixed:

1. agent-buildkit → agent-mesh Service Account Tokens

VIOLATION: agent-buildkit directly parses registry.yaml for service account tokens

FIX REQUIRED:

• ❌ Remove registry.yaml parsing from ServiceAccountTokenService in agent-buildkit
• ✅ Add HTTP client to call agent-mesh API: GET /v1/service-accounts/gitlab/:agentType/token
• ✅ Update all token retrieval to use mesh API

AUTHORITATIVE SOURCE: Line 234 of this document

2. agent-buildkit → agent-router Vast.ai Deployment

VIOLATION: agent-buildkit contains Vast.ai provider logic and deployment orchestration

FIX REQUIRED:

• ❌ Remove Vast.ai provider logic from agent-buildkit
• ✅ Add HTTP client to call agent-router API: POST /api/v1/vastai/deploy
• ✅ Update cost-aware routing to use router API: POST /api/v1/route

AUTHORITATIVE SOURCE: Line 236 of this document

3. Sequential Thinking Migration

VIOLATION: Sequential thinking (8-stage cognitive workflow) is implemented in agent-buildkit

FIX REQUIRED:

• ❌ Remove sequential thinking logic from agent-buildkit (keep CLI wrapper only)
• ✅ Move flow definitions/templates to agentic-flows package
• ✅ Move execution/state management to workflow-engine package
• ✅ Update buildkit thinking CLI to call workflow-engine API

AUTHORITATIVE SOURCE: Lines 210, 230, 516-521, 582-587 of this document

4. Production Webhook Ingress (existing)

VIOLATION: agent-buildkit contains production webhook server (dev-only is acceptable)

FIX REQUIRED:

• ✅ Keep buildkit webhook server as dev/testing tool only
• ✅ Implement production webhook gateway in platform-agents/src/servers/webhook.ts
• ✅ Add idempotency (Redis), queueing (NATS/Redis), rate limiting to production gateway

AUTHORITATIVE SOURCE: Line 229 of this document

5. ai_agents_ossa Copies OSSA Schemas Locally (NEW 2026-02-12)

VIOLATION: ai_agents_ossa/schemas/ contains static copies of OSSA JSON schemas (v0.2.5 through v0.4.4). These should reference the authoritative source in @bluefly/openstandardagents.

FIX REQUIRED:

• ❌ Remove static schema copies from ai_agents_ossa/schemas/
• ✅ Consume schemas from @bluefly/openstandardagents npm package at build/install time
• ✅ OR use Composer autoload to reference a vendored copy that tracks upstream

6. OSSA Package Scoped to @bluefly (STRATEGIC — NOT URGENT)

CONCERN: The OSSA specification npm package is published as @bluefly/openstandardagents. For a vendor-neutral open standard, this ties the spec to BlueFly.io's npm scope.

FUTURE ACTION (after community adoption):

• Migrate to openstandardagents (unscoped) or @ossa/cli
• Maintain @bluefly/openstandardagents as an alias during transition

---

Missing Projects — Added 2026-02-12

dragonfly (TypeScript Service)

Purpose: AI-powered autonomous Drupal testing platform — 7 OSSA agents, 40+ projects, PHP multi-version matrix

RESPONSIBLE FOR

1. Test Orchestration

   • 7 OSSA v0.4.1 agents (orchestrator, test-selector, test-runner, analysis, rector, reporter, quality-control)
   • Docker-based test matrix (PHP 8.2/8.3/8.4, Drupal 10/11)
   • Parallel test execution (40+ projects)
   • PHPUnit, PHPCS, PHPStan, Rector orchestration

2. AI-Powered Testing

   • Intelligent test selection via Qdrant (agent-brain)
   • GPU failure analysis via Vast.ai (agent-router)
   • Pattern learning, automated Rector upgrades with rollback

3. REST API + WebSocket

   • OpenAPI 3.1 spec, real-time progress streaming, GitLab CI integration

NOT RESPONSIBLE FOR

• DDEV Environment Management → alternative_services
• OSSA Spec Definition → openstandardagents
• Knowledge Graph Infrastructure → agent-brain (dragonfly USES it)
• GPU Routing → agent-router (dragonfly USES it)
• MCP Protocol → agent-protocol

---

alternative_services + alternative_dragonfly (Drupal Modules)

Purpose: DDEV management (39 #[Tool] plugins) + Dragonfly bridge (13 #[Tool] plugins)

RESPONSIBLE FOR

1. DDEV Operations (26 tools): lifecycle, config, database snapshots, Drush, Composer, logs, Xdebug, container exec, add-ons, provider pull, poweroff
2. Dragonfly Bridge (13 tools): test orchestration, compliance, Rector, EnvironmentTestCycle
3. DDEV Services: DdevManagerService, DdevProcessService, AddonRegistryService, DdevAddon entity

NATIVE INTEGRATION REQUIREMENTS (Drupal Contrib)

alternative_services MUST integrate closely with these contrib modules — they are the multiplier that makes 39 tools available everywhere:

The #[Tool] pattern IS the integration strategy. Write once, available in FlowDrop workflows, orchestration automations, MCP clients, AI agents, and ECA rules — all via contrib auto-derivation.

NOT RESPONSIBLE FOR

• Test Execution → dragonfly (TypeScript)
• MCP Protocol → drupal/mcp_server (contrib)
• DDEV Add-on Packaging → ddev-bluefly (GitHub)
• Visual Workflow Engine → drupal/flowdrop (contrib — alternative_services provides nodes, not the engine)
• External Automation Dispatch → drupal/orchestration (contrib — alternative_services provides tools, not webhooks)
• Dashboard Rendering → drupal/views + drupal/charts (contrib — alternative_services provides entity data, not views)

---

ddev-bluefly (DDEV Add-on — Planned, GitHub)

Purpose: DDEV add-on exposing Drupal-native MCP server from inside the web container

RESPONSIBLE FOR

1. DDEV Add-on packaging: install.yaml, docker-compose, web_extra_daemons
2. MCP Transport config: STDIO via Drush, HTTP via port 8808
3. Client config generation: Claude Desktop, Cursor, VS Code snippets
4. DDEV custom commands: bluefly-status, bluefly-tools, bluefly-mcp-config

NOT RESPONSIBLE FOR

• Tool Plugin Definitions → alternative_services
• MCP Protocol → drupal/mcp_server (contrib)
• Drupal Module Code → individual modules

Key Boundary: ddev-bluefly is PACKAGING ONLY — no PHP, no tool definitions, no MCP logic.

---

gitlab-ossa-agent (GitLab External Agent)

Purpose: GitLab Duo external agent — OSSA agent mesh access from GitLab UI URL: https://gitlab.com/blueflyio/ossa/lab/gitlab-ossa-agent

RESPONSIBLE FOR

1. GitLab Duo Integration: external agent registration, @bluefly-platform handler
2. Agent Mesh Gateway: routes GitLab events to OSSA agents

NOT RESPONSIBLE FOR

• Agent Mesh → agent-mesh
• Agent Manifests → platform-agents
• OSSA Spec → openstandardagents

---

Decision Tree: Where Does This Feature Go?

Is it DDEV environment management?

• YES → alternative_services Drupal module (Tool plugins)
• DDEV add-on packaging? → ddev-bluefly (GitHub)

Is it Drupal test orchestration?

• YES → dragonfly (TypeScript service)
• Drupal bridge to Dragonfly? → alternative_dragonfly submodule

Is it a GitLab Duo agent integration?

• YES → gitlab-ossa-agent (ossa/lab/)

Is it an OSSA manifest file?

• YES � platform-agents

Is it OSSA specification (JSON Schema, docs)?

• YES � openstandardagents

Is it agent execution/runtime?

• YES � agent-buildkit

Is it OSSA compliance (permissions, access tiers)?

• YES � ai_agents_ossa Drupal module

Is it multi-agent workflow orchestration?

• YES � ai_agents_orchestra Drupal module

Is it the default orchestrator agent?

• YES � platform-agents (default_agents module)

Is it a protocol adapter?

• YES � ai_agents_client Drupal module

Is it LLM-based routing service or Vast.ai deployment orchestration?

• YES � agent-router (separate service)
• Note: MCP protocol belongs in agent-protocol, NOT agent-router

Is it distributed agent coordination?

• YES � agent-mesh
• CRITICAL: Must run on always-on infrastructure (Vast.ai or dedicated server)
• Service Discovery: Uses Tailscale MagicDNS (agent-mesh.tailcf98b3.ts.net:3005)
• No Dependency: Must work without home network or Mac laptop

Is it observability/tracing?

• YES � agent-tracer

Is it knowledge graph/vector search?

• YES � agent-brain

Is it visual workflow building (Langflow)?

• YES � workflow-engine

Is it policy enforcement/compliance?

• YES � compliance-engine

Is it MCP server registry?

• YES � mcp_registry Drupal module

Is it MCP protocol implementation (JSON-RPC 2.0, agent invocation protocol)?

• YES � agent-protocol (NOT agent-router)

Is it a CI/CD component?

• YES � gitlab_components

Is it a Drupal module?

• YES � all_drupal_custom/modules/ (then synced to llm-platform)

Is it a TypeScript service?

• YES � common_npm/<service-name>/

---

Common Mistakes to Avoid

DON'T BUILD IN platform-agents:

• OSSA compliance services (use ai_agents_ossa)
• Protocol adapters (use ai_agents_client)
• Workflow orchestration services (use ai_agents_orchestra or keep in orchestrator)
• BuildKit services (use agent-buildkit)
• OSSA spec definition (use openstandardagents)
• Distributed coordination (use agent-mesh)
• Observability (use agent-tracer)
• Knowledge graph (use agent-brain)
• MCP server registry (use mcp_registry)
• Compliance enforcement (use compliance-engine)

DO BUILD IN platform-agents:

• Agent manifest files
• Default Orchestrator Agent (the default agent)
• Manifest validation (using @bluefly/openstandardagents)
• Agent catalog
• CI components for agents

---

Integration Points

platform-agents � ai_agents_ossa

• Uses OssaPermissionResolver for access control
• Uses OSSA compliance services

platform-agents � @bluefly/openstandardagents

• Uses CLI for manifest validation
• Uses TypeScript types (if needed)

platform-agents � agent-router

• Orchestrator uses agent-router for LLM-based routing

platform-agents � agent-buildkit

• BuildKit executes agents defined in platform-agents

platform-agents � agent-mesh

• Orchestrator can use agent-mesh for distributed coordination
• Service Discovery: Uses Tailscale MagicDNS (agent-mesh.tailcf98b3.ts.net:3005)
• Autonomous Operation: No dependency on home network or Mac laptop

platform-agents � agent-tracer

• Orchestrator publishes traces to agent-tracer

platform-agents � agent-brain

• Orchestrator can query agent-brain for knowledge graph

platform-agents � ai_agents_client

• Orchestrator uses ProtocolRegistry from ai_agents_client

---

Project Inventory Summary

Total Projects: 67+ (see /Volumes/AgentPlatform/config/agent-platform-project-inventory.md)

---

Agent Marketplace & Dashboard Projects

agent_marketplace (Public Marketplace - Headless)

Purpose: Monetization platform for selling fully-built AI agents

✅ RESPONSIBLE FOR

1. Public Marketplace

   • Agent discovery and browsing
   • Agent search and filtering
   • Agent detail pages
   • Reviews and ratings
   • Community features

2. Monetization

   • Payment processing (Stripe)
   • Subscription management
   • License key generation
   • Monthly recurring billing
   • Per-agent pricing
   • Revenue analytics

3. Distribution

   • Agent packaging
   • Version management (semver)
   • Installation commands
   • Changelogs
   • Documentation hosting

4. Analytics

   • Sales metrics
   • Revenue dashboard
   • Usage tracking (for billing)
   • Community metrics

❌ NOT RESPONSIBLE FOR

• Agent creation/authoring → agentdash
• Agent testing/validation → agentdash
• Platform analytics → agentdash
• Agent performance monitoring → agentdash
• OSSA manifest editing → agentdash
• Development tools → agentdash
• Cost optimization → agentdash
• Model routing → agentdash

Architecture

• Frontend: Next.js 14 (App Router) at agents.blueflyagents.com:3001
• Backend: Drupal 11 JSON:API + agent_marketplace module
• UI Components: @bluefly/studio-ui (React)
• Search: @bluefly/agent-brain (semantic search)
• Monitoring: @bluefly/agent-tracer
• API: RESTful + GraphQL

Dependencies

• @bluefly/studio-ui - React components
• @bluefly/agent-protocol - Agent orchestration (marketplace:sync)
• @bluefly/agent-brain - Semantic search
• @bluefly/agent-tracer - Performance metrics
• @bluefly/api-schema-registry - API contracts
• Drupal 11 JSON:API - Backend
• Next.js 14 - Frontend

---

agentdash (Internal Dashboard - Traditional Drupal)

Purpose: Agent creation, testing, analytics, and platform operations

✅ RESPONSIBLE FOR

1. Agent Creation

   • Visual agent builder
   • OSSA manifest editor
   • Agent testing framework
   • Agent validation
   • Workflow composition

2. Analytics & Monitoring

   • Platform health dashboard
   • Agent performance metrics
   • Cost analytics
   • Token usage tracking
   • Model comparison
   • Real-time tracing

3. Operations

   • Agent deployment
   • Agent orchestration
   • User/team management
   • API key management
   • Configuration management
   • Development sandbox

4. Publishing

   • Agent publishing to marketplace
   • Version tagging
   • Release notes
   • Documentation generation

❌ NOT RESPONSIBLE FOR

• Public marketplace UI → agent_marketplace
• Payment processing → agent_marketplace
• Subscription billing → agent_marketplace
• Public agent discovery → agent_marketplace
• License distribution → agent_marketplace
• Community features → agent_marketplace

Architecture

• Frontend: Drupal 11 themes/Twig templates
• Backend: Drupal 11 + agentdash_recipe
• Location: /Volumes/AgentPlatform/AgentDash (demo site)
• Monitoring: @bluefly/agent-tracer dashboard
• Workflows: @bluefly/workflow-engine + Langflow
• Protocol: @bluefly/agent-protocol orchestration

Dependencies

• @bluefly/agent-protocol - Agent orchestration
• @bluefly/agent-tracer - Observability dashboard
• @bluefly/workflow-engine - Visual builder
• @bluefly/agentic-flows - Flow composition
• @bluefly/agent-brain - Knowledge graph
• @bluefly/agent-router - Model routing
• @bluefly/agent-buildkit - Build automation
• @bluefly/compliance-engine - Policy validation
• Drupal 11 - Full stack

---

Agent Services API (Intelligence Core)

Purpose: Core agent capabilities as discoverable, composable Python FastAPI services

✅ RESPONSIBLE FOR

1. Intelligence Services

   • CI/CD orchestration (analysis, migration, optimization)
   • Security scanning (vulnerability detection, policy validation)
   • Documentation generation (AI-powered docs, API specs)
   • Cost optimization (token tracking, model routing recommendations)
   • All future agent capabilities

2. API Contract Management

   • OpenAPI 3.1 specifications
   • Pydantic model validation
   • Auto-generated SDK clients
   • Contract-first development
   • Type safety guarantees

3. Execution Layer

   • Project analysis (multi-language support)
   • Configuration generation (golden patterns)
   • Safe execution (dry-run, validation, rollback)
   • Impact measurement (metrics, ROI quantification)
   • Parallel processing (fleet-scale operations)

❌ NOT RESPONSIBLE FOR

• Public marketplace UI → agent_marketplace
• Agent creation tools → agentdash
• Payment processing → agent_marketplace
• Dashboard visualization → agentdash
• User authentication (delegates to upstream services)

Architecture

• Framework: Python FastAPI
• Validation: OpenAPI 3.1 + Pydantic
• Principles: SOLID, DRY, API-first
• Deployment: api.blueflyagents.com:3005
• Observability: @bluefly/agent-tracer integration
• Discovery: @bluefly/agent-protocol MCP server

Dependencies

• @bluefly/agent-tracer - OpenTelemetry tracing
• @bluefly/agent-protocol - MCP integration
• @bluefly/api-schema-registry - Schema storage
• FastAPI - Python web framework
• Pydantic - Data validation
• OpenAPI 3.1 - API specifications

---

Decision Tree: Where Does This Feature Go?

Is it a public-facing marketplace feature?

• ✅ YES → agent_marketplace
• ❌ NO → Check next question

Does it involve payment/billing/subscriptions?

• ✅ YES → agent_marketplace
• ❌ NO → Check next question

Is it an intelligent agent capability (analysis, generation, execution)?

• ✅ YES → Agent Services API (Python FastAPI)
• ❌ NO → Check next question

Does it involve agent creation/editing?

• ✅ YES → agentdash
• ❌ NO → Check next question

Does it involve platform monitoring/analytics/operations?

• ✅ YES → agentdash
• ❌ NO → Check next question

Does it involve agent discovery for purchase?

• ✅ YES → agent_marketplace
• ❌ NO → agentdash (internal tool)

---

Integration Points

Shared Services (All Three Use)

• @bluefly/agent-protocol - Agent orchestration
• @bluefly/agent-brain - Knowledge graph/search
• @bluefly/agent-router - Model routing
• @bluefly/agent-tracer - Observability
• @bluefly/api-schema-registry - API contracts

Data Flow

agentdash (Create/Test)
    ↓ Publish
agent_marketplace (Browse/Purchase)
    ↓ Install/Execute
Agent Services API (Intelligence)
    ↓ Usage Data
agentdash (Analytics)

API Boundaries

• agentdash API: Internal, admin auth
• agent_marketplace API: Public + authenticated, rate-limited
• Agent Services API: Service-to-service, API key auth

---

Rules & Best Practices

❌ NEVER

• Build UI components outside of @bluefly/studio-ui
• Duplicate agent capabilities across projects
• Mix payment processing with agent logic
• Embed intelligence services in UI layers
• Skip OpenAPI validation

✅ ALWAYS

• Use @bluefly/studio-ui for all React components
• Import types from Agent Services API OpenAPI specs
• Delegate agent execution to Agent Services API
• Apply SOLID principles in Python services
• Validate against OpenAPI 3.1 schemas
• Use @bluefly/agent-protocol for orchestration
• Integrate @bluefly/agent-tracer for observability

---

Enforcement

Before building ANY feature:

1. Check this document
2. Verify the correct project
3. Use existing services/modules when available
4. Document why it belongs in that project
5. Check WIKIs for architecture docs
6. Reference Project-Inventory.md for complete list

If unsure:

• DO NOT BUILD
• ASK FIRST
• Check WIKIs for architecture docs
• Reference this document
• Check Project-Inventory.md

---

Last Updated: 2026-01-27 (Agent Marketplace & Dashboard + Agent Services API) Status: AUTHORITATIVE - DO NOT DEVIATE Audit Source: Project-Inventory.md + WIKIs directory comprehensive audit + Network Infrastructure Audit 2026-01-07 + GitLab Webhook Auto-Fix System implementation + Agent Services API architecture

---

Recent AI Assistant Work

GitLab Webhook Auto-Fix System + Separation of Duties Enforcement (2026-01-05)

Projects: agent-buildkit, platform-agents, common_npm/agent-mesh, common_npm/agent-router

Completed Actions

1. GitLab Webhook Auto-Fix System (MVP in agent-buildkit)

   • Fixed build errors: agent-chat adapter (HTTP client), express/yaml dependencies
   • Created webhook server (src/servers/gitlab-webhook-server.ts) - DEV-ONLY
   • Created MR analysis service (src/services/mr-analysis.service.ts)
   • Created remediation orchestrator (src/services/mr-remediation-orchestrator.service.ts)
   • Created webhook manager (src/infrastructure/webhook-manager.service.ts)
   • Created CLI commands: webhooks:serve, webhooks:register
   • Created K8s deployment config (infrastructure/k8s/webhook-manager/deployment.yaml)
   • Created composition root (src/infrastructure/webhook-system-composition.ts)
   • Build status: 0 TypeScript errors

2. Separation of Duties Violations Identified

   • Webhook ingress in agent-buildkit � Should be in platform-agents for production
   • Service account token loading from registry.yaml � Should call agent-mesh API
   • Vast.ai deployment logic in buildkit � Should request via agent-router API

Next Steps (Required for Production-Grade Platform)

1. Move Production Webhook Ingress to platform-agents

   • Keep buildkit webhook server as dev-only tool
   • Implement production gateway in platform-agents/src/servers/webhook.ts
   • Add idempotency (Redis), queueing (NATS/Redis), rate limiting

2. Integrate agent-buildkit � agent-mesh for Service Accounts

   • Remove registry.yaml parsing from ServiceAccountTokenService
   • Add HTTP client to call agent-mesh API: /v1/service-accounts/gitlab/:agentType/token
   • Update all token retrieval to use mesh API

3. Integrate agent-buildkit � agent-router for Vast.ai

   • Remove Vast.ai provider logic from buildkit
   • Add HTTP client to call agent-router API: /api/v1/vastai/deploy
   • Update cost-aware routing to use router API: /api/v1/route

4. Fix Broken Webhooks

   • Audit existing webhooks at https://gitlab.com/groups/blueflyio/-/hooks
   • Delete broken webhooks
   • Register new webhook via buildkit gitlab webhooks:register

5. Add CI Gates

   • Forbidden import checks (@bluefly/*/src/**)
   • Contract tests (supertest + mocks)
   • Security gates (SAST, dependency scanning)

Architecture Decisions

• Dev vs Production: Buildkit webhook server is dev-only; production ingress in platform-agents
• Service Boundaries: Buildkit is execution runtime; platform-agents owns orchestration
• Token Management: agent-mesh is authoritative; buildkit is client
• Vast.ai: agent-router is authoritative; buildkit requests deployments

---

Autonomous Agents Architecture (2026-01-07)

CRITICAL REQUIREMENT: Agents MUST work without home computer or network.

Completed Actions

1. Agent-Mesh Code Updates

   • Removed hardcoded localhost:3005 references
   • Added TAILSCALE_IP environment variable support
   • Updated to listen on Tailscale IP (not localhost)
   • Added AGENT_MESH_URL environment variable for service discovery

2. Cloudflare Tunnel Migration

   • Updated configuration to route to agent-mesh.tailcf98b3.ts.net:3005
   • Migrating tunnel from Mac laptop to always-on infrastructure (GL-iNet router or Vast.ai)
   • Updated documentation for autonomous architecture

3. Wiki Documentation Updates

   • Updated infrastructure/cloudflare/tunnel-setup.md for autonomous architecture
   • Updated runbooks/agent-mesh.md with CRITICAL requirement and Tailscale MagicDNS
   • Updated architecture/agent-mesh.md with autonomous requirement
   • Updated developer-guides/npm/agent-mesh.md with Tailscale IP configuration

4. Service Discovery Architecture

   • All services use Tailscale MagicDNS (no localhost/hardcoded IPs)
   • Agent-mesh: agent-mesh.tailcf98b3.ts.net:3005
   • Agent services: agent-{name}.tailcf98b3.ts.net:{port}
   • Vast.ai instances: vastai-{id}.tailcf98b3.ts.net:{port}

Architecture Decisions

• Always-On Infrastructure: Agent-mesh runs on Vast.ai always-on instance or dedicated server
• Tailscale MagicDNS: All service discovery via Tailscale (independent of home network)
• Cloudflare Tunnel: Routes to Tailscale MagicDNS hostnames (not localhost or hardcoded IPs)
• Autonomous Operation: Agents can operate independently without home network or Mac laptop

Next Steps

1. Deploy agent-mesh to always-on infrastructure (Vast.ai)
2. Update Cloudflare Tunnel config to route to agent-mesh.tailcf98b3.ts.net:3005
3. Test autonomous operation (home network offline)
4. Update all agent configurations to use Tailscale MagicDNS

---

gitlab-agent_ossa Consolidation & CI/CD Refactoring (2026-01-03)

Project: OssA/lab/gitlab-agent_ossa

Completed Actions

1. GitLab Agent Consolidation

   • Removed duplicate stub directories (agents/gitlab/, agents/agent-gitlab-duo/)
   • Moved stubs to __DELETE_LATER/ for cleanup
   • Updated OpenAPI schema references to point to canonical manifests in packages/@ossa/
   • Verified registry.yaml already correctly references consolidated agent manifests

2. CI/CD Component Refactoring (DRY)

   • Created go-ossa-build CI component in gitlab_components/templates/go-ossa-build/
   • Refactored .gitlab-ci.yml to use reusable components:
     • golden@release/v0.1.x - Release automation, workflow governance
     • go-ossa-build@release/v0.1.x - Go/Bazel/OSSA validation and build jobs
   • Removed inline CI jobs in favor of component-based approach
   • Removed obsolete package and distribute stages

3. Branch Management & Merge Requests

   • Merged all feature branches into release/v0.1.x:
     • feature/49-ossa-v0.3.2-complete
     • feature/50-ossa-wrapper-naming
     • feature/51-add-release-automation
     • feature/52-fix-release-automation
     • feature/53-fix-distribute-job
     • bugfix/52-release-cli-simplification
     • bugfix/ci-component-version
   • Created MR !28: release/v0.1.x � main
   • MR !28 Status: Opened, can be merged (pipeline failed but mergeable)
   • MR !28 Web: https://gitlab.com/blueflyio/ossa/lab/gitlab-agent_ossa/-/merge_requests/28

4. Release Automation

   • Configured golden component with auto_release_on_main: true
   • Tag creation will occur automatically after MR !28 merges to main
   • Current latest tag: v18.8.0-rc1

Architecture Decisions

• DRY Principle: All CI/CD logic centralized in gitlab_components for reuse
• Component-Based CI: Projects consume components rather than duplicating jobs
• OSSA Compliance: All validation jobs use go-ossa-build component
• Release Strategy: Dev tags on release/v0.1.x, production tags on main merge

Notes

• Merge API calls encountered 404 errors (likely token permissions)
• MR !28 requires manual merge or token with merge permissions
• Once merged, golden component will automatically create release tag

---

Infrastructure: Networking

Domain: blueflyagents.com (Cloudflare) VPN: Tailscale mesh network (tailcf98b3.ts.net) CRITICAL: Agents MUST work without home computer or network. All services run on always-on infrastructure.

Public Access (Cloudflare Tunnel)

Private Access (Tailscale MagicDNS)

Deployment Target:

• Always-On: Vast.ai always-on instances or dedicated server (agent-mesh, agent-router, agent-brain)
• Ephemeral: Vast.ai spot instances (GPU compute for LLM inference)

Cloudflare Tunnel: Runs on GL-iNet router or always-on infrastructure (not Mac laptop)

---

Deprecated Services

doc-engine (DEPRECATED)

Status: ❌ DEPRECATED as of 2025-Q4

Replacement: technical-documentation project (GitLab Wiki)

Reason: Consolidating documentation into GitLab Wiki for better collaboration, version control, and integration with CI/CD pipelines.

Migration Path:

• ❌ Do NOT create new content in doc-engine
• ✅ Use technical-docs GitLab project wiki
• ✅ Migrate existing doc-engine content to GitLab Wiki
• ✅ Update all references to point to GitLab Wiki URLs

Archive Location: $BARE_REPOS/agent-platform/doc-engine.git (read-only archive)