llms

BlueFly.io LLM Platform - Full Context

PRIMARY ENTRY POINT: This file (llms.txt) and AGENTS.md are the primary entry points for AI assistants and LLMs. All platform context has been consolidated here.

Complete inline context for AI assistants - no external links required Version: 3.0.0 | Last Updated: 2026-01-31 | Owner: Thomas Scola, Bluefly.io

Quick Links

AI Assistant Guidelines: AGENTS.md - Platform agents reference, essential commands
Separation of Duties: architecture/separation-of-duties.md - Architecture compliance rules
Technical Documentation: Technical Docs Wiki - Complete platform documentation

CRITICAL: Separation of Duties

ALL shared code MUST be in common_npm packages. NO EXCEPTIONS.

platform-agents is ONLY for agent definitions (OSSA manifests)
All other projects CONSUME common_npm packages
NEVER duplicate code across projects
NEVER create services in projects that should be in common_npm

Three-Tier Architecture

Tier 1: platform-agents/         → Agent definitions ONLY (OSSA YAML manifests)
Tier 2: common_npm/agent-*        → Infrastructure packages (TypeScript services)
Tier 3: gitlab-agent_ossa/       → Platform implementation (Go, 13 capabilities)

Common NPM Packages: STRICT OWNERSHIP

@bluefly/agent-brain

OWNERS: Vector search, semantic search, Qdrant, embeddings, RAG, codebase indexing, memories MUST USE: import { VectorSearchService } from '@bluefly/agent-brain'; FORBIDDEN: Creating vector/search/brain services elsewhere

@bluefly/agent-docker

OWNERS: Docker operations, Kubernetes operations, container management, deployment orchestration MUST USE: import { DockerService } from '@bluefly/agent-docker'; FORBIDDEN: Creating docker/kubernetes services elsewhere

@bluefly/agent-mesh

OWNERS: Agent-to-agent communication, service mesh, coordination, discovery, transport, auth MUST USE: import { MeshCoordinator } from '@bluefly/agent-mesh'; FORBIDDEN: Creating mesh/coordination services elsewhere

@bluefly/agent-protocol

OWNERS: MCP servers, MCP registry, protocol adapters, MCP integration MUST USE: import { MCPServerRegistry } from '@bluefly/agent-protocol'; FORBIDDEN: Creating MCP/protocol services elsewhere

@bluefly/agent-router

OWNERS: Agent routing, cost-aware routing, task routing, agent discovery MUST USE: import { CostAwareAgentRouter } from '@bluefly/agent-router'; FORBIDDEN: Creating router services elsewhere (DUPLICATED in 2 projects - MIGRATE!)

@bluefly/agent-tailscale

OWNERS: ALL Tailscale operations (subnet, DNS, SSH, certificates, webhooks, monitoring, etc.) MUST USE: import { TailscaleService } from '@bluefly/agent-tailscale'; FORBIDDEN: Creating ANY Tailscale services elsewhere (27 files found - MIGRATE!)

@bluefly/agent-tracer

OWNERS: Distributed tracing, OpenTelemetry, RPC tracing, trace analysis, observability MUST USE: import { TracerService } from '@bluefly/agent-tracer'; FORBIDDEN: Creating tracing services elsewhere

@bluefly/agentic-flows

OWNERS: Agent orchestration, multi-agent workflows, service registry, ecosystem orchestration MUST USE: import { UnifiedAgentPlatform } from '@bluefly/agentic-flows'; FORBIDDEN: Creating orchestration services elsewhere

@bluefly/compliance-engine

OWNERS: Audit services, compliance checks, policy validation, separation of duties validation MUST USE: import { ComplianceEngine } from '@bluefly/compliance-engine'; FORBIDDEN: Creating audit/compliance services elsewhere (48 files found - MIGRATE!)

@bluefly/foundation-bridge

OWNERS: LLM providers, model orchestration, provider routing, enterprise LLM services MUST USE: import { EnterpriseLLMService } from '@bluefly/foundation-bridge'; FORBIDDEN: Creating LLM provider services elsewhere

@bluefly/workflow-engine

OWNERS: Workflow execution, state management, step runners, error handling, workflow types MUST USE: import { WorkflowExecutor } from '@bluefly/workflow-engine'; FORBIDDEN: Creating workflow services elsewhere (8 files found - MIGRATE!)

@bluefly/kiro-supercharger

OWNERS: Kiro-specific optimizations and integrations MUST USE: import { KiroOptimizer } from '@bluefly/kiro-supercharger';

@bluefly/studio-ui

OWNERS: ALL React UI components, shared UI components, reusable UI patterns MUST USE: import { Button } from '@bluefly/studio-ui'; FORBIDDEN: Creating React components elsewhere

Project Ownership

platform-agents

ONLY OWNS: Agent definitions (OSSA manifests), agent packages, agent examples MUST NOT: Create services, utilities, or duplicate code from common_npm MUST: Import ALL services from common_npm packages

agent-buildkit

OWNS: CLI tools, command execution, buildkit-specific utilities MUST NOT: Create services that should be in common_npm MUST: Import ALL services from common_npm packages

technical-docs

OWNS: ALL documentation, API docs, cross-project documentation MUST USE: ApiDog for API documentation management

api-schema-registry

OWNS: OpenAPI schema registry, API schema management, schema validation MUST USE: ApiDog integration for schema management

models/

OWNS: Model definitions for specific use cases

models/agentdev/ - Agent development models
models/orchestration/ - Orchestration models
models/rfp/ - RFP automation models

security-policies

OWNS: ALL security policies, security configurations, security rules FORBIDDEN: Creating security policies elsewhere

gitlab_components

OWNS: ALL CI/CD components, GitLab CI templates, pipeline components FORBIDDEN: Creating CI/CD components elsewhere

Infrastructure

Distributed Kubernetes cluster (Mac M4 Control Plane + Mac M3 Worker Node) via Tailscale mesh network.

Network: Tailscale mesh (tailcf98b3.ts.net) with GL-BE3600 router (192.168.8.0/24 subnet routing).

Vast.ai GPU: Instance 29484611 (RTX 4090) for GPU compute.

Cloudflare Tunnel: f6da7bdf-d0f8-4796-a804-afb7984bbe11 for public webhook ingress.

Synology NAS: 192.168.68.60 (always-on storage/services).

Enforcement Rules

NEVER DO (VIOLATIONS WILL BE REJECTED)

❌ Create services in platform-agents - use common_npm packages
❌ Duplicate cost-aware-agent-router.service.ts - use @bluefly/agent-router
❌ Create Tailscale services in agent-buildkit - use @bluefly/agent-tailscale
❌ Create workflow services in agent-buildkit - use @bluefly/workflow-engine
❌ Create mesh services in agent-buildkit - use @bluefly/agent-mesh
❌ Create tracer services in agent-buildkit - use @bluefly/agent-tracer
❌ Create brain services in agent-buildkit - use @bluefly/agent-brain
❌ Create docker services in agent-buildkit - use @bluefly/agent-docker
❌ Create compliance services in agent-buildkit - use @bluefly/compliance-engine
❌ Create React components in other projects - use @bluefly/studio-ui
❌ Create security policies in other projects - use security-policies
❌ Create CI/CD components in other projects - use gitlab_components
❌ Create API schemas in other projects - use api-schema-registry
❌ Create documentation in other projects - use technical-docs
❌ Create models in other projects - use models/

ALWAYS DO

✅ Import services from common_npm packages
✅ Use @bluefly/agent-router for ALL routing
✅ Use @bluefly/agent-mesh for ALL coordination
✅ Use @bluefly/agent-tracer for ALL tracing
✅ Use @bluefly/workflow-engine for ALL workflows
✅ Use @bluefly/agent-brain for ALL vector/search
✅ Use @bluefly/agent-docker for ALL docker/k8s
✅ Use @bluefly/agent-tailscale for ALL Tailscale
✅ Use @bluefly/compliance-engine for ALL compliance
✅ Use @bluefly/studio-ui for ALL React components
✅ Use security-policies for ALL security
✅ Use gitlab_components for ALL CI/CD
✅ Use api-schema-registry for ALL schemas
✅ Use technical-docs for ALL documentation
✅ Use models/ for ALL model definitions

Migration Priority

PHASE 1: CRITICAL (Immediate)

cost-aware-agent-router.service.ts - Exact duplicate in 2 projects
All 27 Tailscale services - Massive duplication
Workflow services - Core functionality duplicated

PHASE 2: HIGH (This Week)

Agent-mesh services (5 files)
Agent-tracer services (3 files)
Agent-brain services (7 files)

PHASE 3: MEDIUM (Next Sprint)

Agent-docker services (4 files)
Compliance services (48 files)
Agent-protocol services (11 files)
Foundation-bridge services (6 files)

Agent Role Separation

Each agent must have ONE primary role. See Separation-of-Duties for full details.

Role	Access Tier	Conflicts With
Analyzer	`tier_1_read`	Executor, Approver
Reviewer	`tier_2_write_limited`	Executor, Approver
Executor	`tier_3_full_access`	Reviewer, Approver
Orchestrator	`tier_2_write_limited`	Executor (direct)
Approver	`tier_4_policy`	Executor, Reviewer

Platform Agents (16 Active)

All agents defined in platform-agents/packages/@ossa/*/agent.ossa.yaml:

vulnerability-scanner - Analyzer
merge-request-reviewer - Reviewer
pipeline-remediation - Executor
release-coordinator - Orchestrator
task-dispatcher - Orchestrator
drupal-standards-enforcer - Reviewer
code-quality-reviewer - Reviewer
issue-lifecycle-manager - Orchestrator
module-generator - Executor
recipe-publisher - Executor
cluster-operator - Executor
manifest-validator - Analyzer
documentation-aggregator - Executor
mcp-server-builder - Executor
cost-intelligence-monitor - Analyzer
kagent-catalog-sync - Executor

For complete documentation, see the GitLab Wiki.