AGENTS.md

PRIMARY ENTRY POINT: This file (AGENTS.md) and llms.txt are the primary entry points for AI assistants. All AI assistant guidelines have been consolidated here.

AUTHORITATIVE SOURCE: This file is the master reference for AI assistants working with the BlueFly Agent Platform.

Quick Links

• LLM Context: llms.txt - Full platform context (26K tokens)
• Separation of Duties: architecture/separation-of-duties.md - Architecture compliance rules
• Technical Documentation: Technical Docs Wiki - Complete platform documentation

Core Principle: platform-agents is ONLY for Agent Definitions

CRITICAL: platform-agents is ONLY for agent definitions (OSSA manifests). All services, utilities, and integrations MUST use common_npm packages.

platform-agents Structure

platform-agents/
 packages/@ossa/*/          # Agent definitions ONLY (agent.ossa.yaml)
 examples/                   # Agent examples ONLY
 integrations/               # Integration configs ONLY (not services)

What platform-agents OWNS

• Agent definitions (packages/@ossa/*/agent.ossa.yaml)
• Agent examples (examples/)
• Integration configurations (not implementations)

What platform-agents DOES NOT OWN

• Services (use @bluefly/agent-* packages)
• Utilities (use @bluefly/agent-* packages)
• Business logic (use @bluefly/agent-* packages)
• Duplicated code from common_npm

Agent Implementation Requirements

ALL Agents MUST Use Common NPM Packages

Agents MUST import services from common_npm packages:

//  CORRECT - Use common_npm packages
import { CostAwareAgentRouter } from '@bluefly/agent-router';
import { MeshCoordinator } from '@bluefly/agent-mesh';
import { TracerService } from '@bluefly/agent-tracer';
import { WorkflowExecutor } from '@bluefly/workflow-engine';
import { VectorSearchService } from '@bluefly/agent-brain';
import { DockerService } from '@bluefly/agent-docker';
import { TailscaleService } from '@bluefly/agent-tailscale';
import { ComplianceEngine } from '@bluefly/compliance-engine';
import { EnterpriseLLMService } from '@bluefly/foundation-bridge';
import { MCPServerRegistry } from '@bluefly/agent-protocol';
import { UnifiedAgentPlatform } from '@bluefly/agentic-flows';

** FORBIDDEN - Never create services in platform-agents:**

//  WRONG - Don't create services in platform-agents
class MyRouter { }  // Use @bluefly/agent-router instead
class MyTracer { }  // Use @bluefly/agent-tracer instead
class MyWorkflow { }  // Use @bluefly/workflow-engine instead

Essential Commands

# Agent Marketplace
buildkit agents marketplace list
buildkit agents marketplace validate <agentId>

# Agent Management
buildkit agents list
buildkit agents spawn <agentId>

# Validate agent separation of duties
ossa validate agent.ossa.yaml --check separation
npx @bluefly/compliance-engine validate --check-role-conflicts

Agent Role Separation

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

Platform Agents (16 Active)

All agents are 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

Using Agents from Other Projects

All projects MUST call agents from platform-agents, not duplicate them:

//  CORRECT - Call agents from platform-agents
import { spawnAgent } from '@bluefly/platform-agents';
await spawnAgent('vulnerability-scanner', { projectId: '123' });

//  WRONG - Don't create agents in other projects
class MyVulnerabilityScanner { }  // Use platform-agents instead

Common NPM Packages for Agents

Enforcement

Violations will be rejected:

• Creating services in platform-agents
• Duplicating agent logic in other projects
• Not using common_npm packages
• Creating agents outside platform-agents

For complete documentation, see the GitLab Wiki.