Skip to main content

Platform Agents Registry - Quick Start

Platform Agents Registry - Quick Start

One-page reference for common operations.

Installation

cd /Volumes/AgentPlatform/worktrees/shared/2026-01-29/platform-agents/registry-optimization
npm install --legacy-peer-deps

Common Commands

Validation

# Validate all agent manifests
npm run validate:agents

# Validate registry.yaml
npm run validate:registry

# Validate everything
npm run registry:validate-all

Registry Operations

# Sync registry from manifests
npm run registry:sync

# Migrate to OSSA v0.3.6
npm run registry:migrate-v0.3.6

# Publish to GitLab Package Registry
npm run registry:publish

Development

# Build TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint
npm run lint:fix

Quick Workflow

Adding a New Agent

# 1. Create agent directory
mkdir -p packages/@ossa/my-agent

# 2. Create manifest (use OSSA v0.3.6)
vim packages/@ossa/my-agent/manifest.ossa.yaml

# 3. Validate
npm run validate:agents

# 4. Sync registry
npm run registry:sync

# 5. Commit
git add packages/@ossa/my-agent/ registry.yaml
git commit -m "feat: add my-agent"

Updating an Agent

# 1. Edit manifest
vim packages/@ossa/agent-name/manifest.ossa.yaml

# 2. Validate
npm run validate:agents

# 3. Sync registry
npm run registry:sync

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

Git Workflow

# Pre-commit hook validates automatically
git add .
git commit -m "feat: description"
# Validation runs automatically ✅

# Push to origin
git push origin feature/branch-name

# Create MR
glab mr create --title "Title" --description "Description"

Validation Errors

# Check detailed errors
npm run validate:agents
cat validation-report.json

# Fix and retry
vim packages/@ossa/agent-name/manifest.ossa.yaml
npm run validate:agents

OSSA v0.3.6 Template

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

Troubleshooting

Validation Fails

# Check errors
npm run validate:agents | grep "Error:"

# Check version compliance
npm run validate:agents | grep "Version:"

Registry Sync Issues

# Manually sync
npm run registry:sync

# Validate registry
npm run validate:registry

Pre-Commit Hook Not Working

# Reinstall husky
npx husky init
npx husky add .husky/pre-commit "npm run validate:agents"

File Locations

.gitlab/ci/validate.yml     # CI pipeline
.husky/pre-commit           # Pre-commit hook
src/scripts/                # Automation scripts
src/validation/             # Validation schemas
registry.yaml               # Registry metadata
packages/@ossa/             # Agent manifests

Documentation

  • Complete Guide: REGISTRY.md
  • Changes: OPTIMIZATION.md
  • Deployment: NEXT_STEPS.md
  • Deliverables: DELIVERABLES.md
  • Summary: COMPLETION_SUMMARY.md

Support