Platform Agents Registry

Canonical registry of production-ready OSSA agents for the BlueFly Agent Platform.

Overview

This registry serves as the single source of truth for all platform agents, including their capabilities, dependencies, health checks, and deployment configurations.

Total Agents: 16 canonical OSSA agents
OSSA Version: v0.3.6
Package: @bluefly/platform-agents
Registry URL: https://agents.bluefly.io

Structure

platform-agents/
├── packages/@ossa/           # Agent manifests (16 agents)
│   ├── agent-selector/
│   │   ├── manifest.ossa.yaml
│   │   ├── package.json
│   │   └── SKILL.md
│   ├── ci-fixer-worker/
│   ├── cluster-operator/
│   ├── code-quality-reviewer/
│   ├── code-reviewer/
│   ├── communications-manager/
│   ├── content-planner/
│   ├── creative-designer/
│   ├── data-analyst/
│   ├── data-ingestion-worker/
│   ├── default-orchestrator/
│   ├── deployment-orchestrator/
│   ├── deployment-worker/
│   ├── developer-agent/
│   ├── document-specialist/
│   └── documentation-aggregator/
├── src/
│   ├── registry/             # Registry core logic
│   ├── scripts/              # Automation scripts
│   │   ├── validate-manifests.ts
│   │   ├── validate-registry.ts
│   │   ├── sync-registry.ts
│   │   └── publish-registry.ts
│   └── validation/           # Validation schemas
│       └── ossa-schema.ts    # OSSA v0.3.6 Zod schema
├── .gitlab/ci/
│   └── validate.yml          # CI validation pipeline
├── .husky/
│   └── pre-commit            # Pre-commit validation hook
├── registry.yaml             # Registry metadata and agent catalog
└── package.json

Agents

Orchestrators (2)

default-orchestrator: Workflow orchestration and agent coordination
deployment-orchestrator: Deployment orchestration and rollback management

Workers (13)

ci-fixer-worker: CI/CD pipeline analysis and automated fixes
cluster-operator: Kubernetes operations and infrastructure management
code-quality-reviewer: Code analysis and quality metrics
code-reviewer: Merge request review and code suggestions
communications-manager: Notification and stakeholder communication
content-planner: Content planning and documentation updates
creative-designer: UI design and asset creation
data-analyst: Data analysis and metrics tracking
data-ingestion-worker: Data ingestion and transformation
deployment-worker: Application deployment and health checks
developer-agent: Code generation and refactoring
document-specialist: Documentation generation and technical writing
documentation-aggregator: Documentation aggregation and search indexing

Selector (1)

agent-selector: Agent recommendation and capability matching

Validation

Pre-Commit Hook

Automatically validates manifests before commit:

# Automatically runs on git commit
git add packages/@ossa/agent-name/manifest.ossa.yaml
git commit -m "feat: update agent manifest"
# Pre-commit hook validates manifest

Manual Validation

# Validate all agent manifests
npm run validate:agents

# Validate registry.yaml
npm run validate:registry

# Validate everything
npm run registry:validate-all

CI Pipeline

GitLab CI automatically validates:

All agent manifests on change
OSSA v0.3.6 compliance
Registry consistency
TypeScript linting
Unit tests

Registry Sync

Sync registry.yaml from agent manifests:

# Update registry.yaml from all manifests
npm run registry:sync

# This will:
# - Scan all agent manifests
# - Extract capabilities, dependencies, metadata
# - Update registry.yaml with current state
# - Update dependency graph
# - Update last_updated timestamp

Publishing

Publish to GitLab Package Registry:

# Publish registry (validates, tests, builds, publishes)
npm run registry:publish

# This will:
# 1. Validate all manifests
# 2. Run tests
# 3. Build TypeScript
# 4. Publish to GitLab Package Registry

OSSA v0.3.6 Compliance

All agents must use OSSA v0.3.6:

apiVersion: ossa/v0.4.9
kind: Agent
metadata:
  name: agent-name
  version: 1.0.0
  namespace: blueflyio
  description: Agent description
  labels:
    domain: category
    tier: worker
spec:
  access:
    tier: tier_2_write_limited
    permissions:
      - read:repository
    prohibited:
      - write:credentials
  taxonomy:
    domain: category
    subdomain: subcategory
    capability: primary-capability
  autonomy:
    level: fully_autonomous
  capabilities:
    - name: capability-name
      description: What it does
      category: reasoning
      autonomy: fully_autonomous

Required Fields

apiVersion: Must be ossa/v0.3.6
kind: Must be Agent
metadata.name: Kebab-case identifier
metadata.version: Semantic version
metadata.namespace: Namespace (blueflyio)
spec.access: Access tier and permissions
spec.taxonomy: Domain classification
spec.autonomy: Autonomy level
spec.capabilities: Array of capabilities

Dependency Graph

The registry tracks agent dependencies:

spec:
  dependency_graph:
    default-orchestrator:
      - agent-mesh
      - agent-selector
    cluster-operator:
      - kubectl
      - helm
      - terraform

Deployment Targets

Agents can be deployed to multiple Kubernetes clusters:

spec:
  deployment_targets:
    kubernetes:
      clusters:
        - name: production
          context: bluefly-prod
          region: us-east-1
          agents:
            - agent-selector
            - default-orchestrator
        - name: orbstack-local
          context: orbstack
          region: local
          agents:
            - agent-selector
            - developer-agent

Health Checks

All agents expose health check endpoints:

spec:
  health_checks:
    global:
      interval: 30s
      timeout: 5s
      failure_threshold: 3
    endpoints:
      - path: /health
        method: GET
        expected_status: 200
      - path: /ready
        method: GET
        expected_status: 200

Observability

Registry supports OpenTelemetry tracing and Prometheus metrics:

spec:
  observability:
    tracing:
      enabled: true
      provider: opentelemetry
      endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT}
    metrics:
      enabled: true
      provider: prometheus
      port: 9090

Development Workflow

Adding a New Agent

Create agent directory:
```
mkdir -p packages/@ossa/my-agent
```

Create manifest:

# Use OSSA v0.3.6 schema
cat > packages/@ossa/my-agent/manifest.ossa.yaml

Validate:
```
npm run validate:agents
```
Sync registry:
```
npm run registry:sync
```

Commit:

git add packages/@ossa/my-agent/
git commit -m "feat: add my-agent"
# Pre-commit hook validates automatically

Updating an Agent

Edit manifest:

vim packages/@ossa/agent-name/manifest.ossa.yaml

Validate:
```
npm run validate:agents
```
Sync registry:
```
npm run registry:sync
```

Commit:

git add packages/@ossa/agent-name/manifest.ossa.yaml registry.yaml
git commit -m "feat: update agent-name capabilities"

Automation

Registry Sync (Automated)

Registry automatically syncs from manifests every 5 minutes:

spec:
  automation:
    registry_sync:
      enabled: true
      interval: 5m
      source: manifests

Validation (Automated)

Validation runs:

Pre-commit (Git hook)
Pre-push (Git hook)
CI pipeline (Merge requests, main/development)

Publishing (Manual)

Publishing requires manual trigger:

npm run registry:publish

API

The registry exposes a REST API:

Base URL: https://registry.bluefly.io/api/v1
Endpoints:
- GET /agents - List all agents
- GET /agents/:id - Get agent details
- GET /agents/:id/manifest - Get agent manifest
- GET /health - Health check
- GET /metrics - Prometheus metrics

Integration

BuildKit CLI

Agents integrate with the BuildKit CLI:

buildkit agent list
buildkit agent info agent-selector
buildkit agent deploy cluster-operator --cluster production

Agent Mesh

Agents discover each other via the Agent Mesh:

extensions:
  agent_mesh:
    endpoint: mesh.bluefly.internal:3005
    discovery: true

Compliance

OSSA Version: v0.3.6 (strict enforcement)
Validation: Pre-commit, pre-push, CI pipeline
Required Fields: Enforced by Zod schema
Fail on Error: Yes (blocks commits and merges)

Troubleshooting

Validation Errors

# Check which agents are invalid
npm run validate:agents

# View detailed errors
cat validation-report.json

Registry Sync Issues

# Manually sync registry
npm run registry:sync

# Check registry validity
npm run validate:registry

Version Non-Compliance

# Find agents not using OSSA v0.3.6
npm run validate:agents | grep "Version non-compliant"

# Update agent manifest
vim packages/@ossa/agent-name/manifest.ossa.yaml
# Change: apiVersion: ossa/v0.4.9

Platform Agents Registry

Platform Agents Registry

Overview

Structure

Agents

Orchestrators (2)

Workers (13)

Selector (1)

Validation

Pre-Commit Hook

Manual Validation

CI Pipeline

Registry Sync

Publishing

OSSA v0.3.6 Compliance

Required Fields

Dependency Graph

Deployment Targets

Health Checks

Observability

Development Workflow

Adding a New Agent

Updating an Agent

Automation

Registry Sync (Automated)

Validation (Automated)

Publishing (Manual)

API

Integration

BuildKit CLI

Agent Mesh

Compliance

Troubleshooting

Validation Errors

Registry Sync Issues

Version Non-Compliance

Links