Platform Agents Repository Analysis

Last Updated: January 7, 2026 Repository: https://gitlab.com/blueflyio/platform-agents Purpose: Canonical agent definitions with bi-directional OSSA † GitLab Duo conversion

Overview

The platform-agents repository is the central hub for agent definitions in the GitLab Agent Platform. It provides:

1. 16 Canonical Agents - Production-ready agent specifications
2. Bi-directional Conversion - OSSA † GitLab Duo format translation
3. Agent Templates - Starting points for custom agents
4. Best Practices - Patterns and conventions
5. CI/CD Integration - Automated validation and publishing

Repository Structure

platform-agents/
 agents/                      # Agent definitions
‚    code-reviewer/
‚   ‚    ossa-agent.yml      # OSSA format
‚   ‚    gitlab-duo.yml      # GitLab Duo format
‚   ‚    README.md
‚   ‚    examples/
‚    security-analyst/
‚    test-generator/
‚    documentation-writer/
‚    ...
‚    [14 more agents]
‚
 converters/                  # Conversion tools
‚    ossa-to-gitlab/
‚   ‚    index.ts
‚   ‚    schema.ts
‚   ‚    tests/
‚    gitlab-to-ossa/
‚        index.ts
‚        schema.ts
‚        tests/
‚
 templates/                   # Agent templates
‚    basic-agent/
‚    multi-tool-agent/
‚    flow-orchestrator/
‚
 schemas/                     # JSON schemas
‚    ossa-v1.schema.json
‚    gitlab-duo-v1.schema.json
‚
 .gitlab-ci.yml              # CI/CD pipeline
 package.json
 README.md

The 16 Canonical Agents

1. Code Reviewer Agent

Purpose: Comprehensive code review with security, quality, and style analysis

OSSA Spec (agents/code-reviewer/ossa-agent.yml):

apiVersion: ossa/v1
kind: Agent
metadata:
  name: code-reviewer
  version: 2.1.0
  description: Reviews code for security, quality, and best practices
  tags: [code-review, security, quality]
  maintainer: blueflyio

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4.5
    parameters:
      temperature: 0.2
      max_tokens: 8192

  system_prompt: |
    You are an expert code reviewer with deep knowledge of:
    - Security vulnerabilities (OWASP Top 10, CWE)
    - Code quality metrics (complexity, maintainability)
    - Language-specific best practices
    - Performance optimization

    Analyze code systematically and provide:
    1. Security concerns (critical first)
    2. Quality issues
    3. Best practice violations
    4. Specific recommendations with examples

  tools:
    - name: read_file
      type: filesystem
      description: Read source files

    - name: git_diff
      type: git
      description: Get code changes

    - name: sast_scan
      type: security
      description: Run SAST analysis

    - name: gitlab_comment
      type: gitlab_api
      description: Post review comments

  inputs:
    - name: project_id
      type: integer
      required: true

    - name: merge_request_iid
      type: integer
      required: true

    - name: focus_areas
      type: array
      items:
        type: string
        enum: [security, quality, performance, style]
      default: [security, quality]

  outputs:
    - name: review_summary
      type: string

    - name: issues
      type: array
      items:
        type: object
        properties:
          severity: {type: string, enum: [critical, high, medium, low, info]}
          category: {type: string}
          file: {type: string}
          line: {type: integer}
          description: {type: string}
          recommendation: {type: string}

    - name: approval_status
      type: string
      enum: [approved, changes_requested, blocked]

  resources:
    token_limit: 100000
    timeout: 600
    memory: 1Gi

GitLab Duo Format (agents/code-reviewer/gitlab-duo.yml):

agent:
  name: code_reviewer
  version: "2.1.0"
  model: claude-sonnet-4.5

prompts:
  - role: system
    content: |
      You are an expert code reviewer...
      [same content as OSSA]

actions:
  - name: review_merge_request
    gitlab_api: true
    endpoints:
      - method: GET
        path: /projects/:project_id/merge_requests/:merge_request_iid
      - method: GET
        path: /projects/:project_id/merge_requests/:merge_request_iid/changes
      - method: POST
        path: /projects/:project_id/merge_requests/:merge_request_iid/notes

  - name: run_sast
    integration: security_scanner
    type: sast

parameters:
  project_id:
    type: integer
    required: true

  merge_request_iid:
    type: integer
    required: true

  focus_areas:
    type: array
    items: string
    enum: [security, quality, performance, style]
    default: [security, quality]

response_format:
  type: structured
  schema:
    type: object
    properties:
      review_summary:
        type: string
      issues:
        type: array
        items:
          type: object
          properties:
            severity: {type: string}
            category: {type: string}
            file: {type: string}
            line: {type: integer}
            description: {type: string}
            recommendation: {type: string}
      approval_status:
        type: string
        enum: [approved, changes_requested, blocked]

2. Security Analyst Agent

Purpose: Deep security analysis beyond standard SAST (Ultimate only)

Key Features:

• Vulnerability assessment
• Exploit analysis
• Compliance checking (SOC2, GDPR, PCI-DSS)
• Threat modeling

OSSA Spec: agents/security-analyst/ossa-agent.yml

apiVersion: ossa/v1
kind: Agent
metadata:
  name: security-analyst
  version: 1.8.0
  tier: ultimate  # GitLab Ultimate only

spec:
  model:
    provider: anthropic
    name: claude-opus-4.5  # More powerful model for security

  system_prompt: |
    You are a security expert specializing in:
    - Vulnerability assessment
    - Exploit analysis and remediation
    - Compliance frameworks
    - Threat modeling

  tools:
    - name: sast_scan
      type: security
    - name: dependency_scan
      type: security
    - name: secret_detection
      type: security
    - name: container_scan
      type: security
    - name: vulnerability_db
      type: database
      connection: cve_database

  compliance_frameworks:
    - SOC2
    - GDPR
    - PCI-DSS
    - HIPAA

3-16. Other Canonical Agents

3. Test Generator Agent

• Generates unit, integration, and E2E tests
• Achieves 80%+ coverage
• Supports pytest, jest, junit

4. Documentation Writer Agent

• Generates API docs (OpenAPI/Swagger)
• Creates README files
• Writes user guides

5. Bug Analyzer Agent

• Root cause analysis
• Suggests fixes
• Creates reproduction steps

6. Performance Optimizer Agent

• Identifies bottlenecks
• Suggests optimizations
• Database query analysis

7. Refactoring Agent

• Code smell detection
• Suggests refactoring
• Maintains functionality

8. Dependency Updater Agent

• Updates dependencies safely
• Checks for breaking changes
• Generates changelogs

9. CI/CD Optimizer Agent

• Analyzes pipeline performance
• Suggests parallelization
• Optimizes caching

10. Infrastructure as Code Agent

• Generates Terraform/CloudFormation
• Kubernetes manifests
• Helm charts

11. Database Migration Agent

• Generates migration scripts
• Schema validation
• Rollback strategies

12. API Designer Agent

• Designs REST/GraphQL APIs
• Generates OpenAPI specs
• Creates client SDKs

13. Localization Agent

• Translates strings
• Handles pluralization
• Culture-specific formatting

14. Accessibility Auditor Agent

• WCAG compliance
• Aria label validation
• Keyboard navigation

15. Data Analyst Agent

• Generates reports
• DORA metrics
• Custom analytics

16. Incident Responder Agent

• Analyzes logs
• Suggests remediation
• Creates postmortems

Bi-directional Conversion

The repository includes tools for converting between OSSA and GitLab Duo formats.

OSSA † GitLab Duo Converter

TypeScript Implementation (converters/ossa-to-gitlab/index.ts):

// converters/ossa-to-gitlab/index.ts
import { parse } from 'yaml';
import { OSSAAgent, GitLabDuoAgent } from './schema';

export function ossaToGitLabDuo(ossaYaml: string): GitLabDuoAgent {
  const ossa: OSSAAgent = parse(ossaYaml);

  return {
    agent: {
      name: ossa.metadata.name.replace(/-/g, '_'),
      version: ossa.metadata.version,
      model: ossa.spec.model.name,
    },

    prompts: [
      {
        role: 'system',
        content: ossa.spec.system_prompt
      }
    ],

    actions: convertTools(ossa.spec.tools),

    parameters: convertInputs(ossa.spec.inputs),

    response_format: {
      type: 'structured',
      schema: convertOutputs(ossa.spec.outputs)
    },

    resources: {
      max_tokens: ossa.spec.resources.token_limit,
      timeout: ossa.spec.resources.timeout
    }
  };
}

function convertTools(tools: OSSAAgent['spec']['tools']): GitLabDuoAgent['actions'] {
  return tools.map(tool => {
    switch (tool.type) {
      case 'gitlab_api':
        return {
          name: tool.name,
          gitlab_api: true,
          endpoints: extractEndpoints(tool)
        };

      case 'security':
        return {
          name: tool.name,
          integration: 'security_scanner',
          type: tool.name.includes('sast') ? 'sast' : 'dependency'
        };

      case 'filesystem':
        return {
          name: tool.name,
          type: 'file_operation'
        };

      default:
        return {
          name: tool.name,
          type: 'custom',
          implementation: tool.endpoint || tool.command
        };
    }
  });
}

function convertInputs(inputs: OSSAAgent['spec']['inputs']) {
  const params: Record<string, any> = {};

  for (const input of inputs) {
    params[input.name] = {
      type: input.type,
      required: input.required,
      default: input.default,
      enum: input.items?.enum
    };
  }

  return params;
}

function convertOutputs(outputs: OSSAAgent['spec']['outputs']) {
  const schema: any = {
    type: 'object',
    properties: {}
  };

  for (const output of outputs) {
    schema.properties[output.name] = {
      type: output.type,
      items: output.items,
      enum: output.enum
    };
  }

  return schema;
}

Usage:

# Convert OSSA to GitLab Duo format
npm run convert:ossa-to-gitlab \
  agents/code-reviewer/ossa-agent.yml \
  agents/code-reviewer/gitlab-duo.yml

# Validate conversion
npm run validate agents/code-reviewer/gitlab-duo.yml

GitLab Duo † OSSA Converter

TypeScript Implementation (converters/gitlab-to-ossa/index.ts):

// converters/gitlab-to-ossa/index.ts
import { stringify } from 'yaml';
import { GitLabDuoAgent, OSSAAgent } from './schema';

export function gitLabDuoToOSSA(gitlabAgent: GitLabDuoAgent): string {
  const ossa: OSSAAgent = {
    apiVersion: 'ossa/v1',
    kind: 'Agent',

    metadata: {
      name: gitlabAgent.agent.name.replace(/_/g, '-'),
      version: gitlabAgent.agent.version,
      description: extractDescription(gitlabAgent),
      platform: {
        source: 'gitlab-duo',
        converted_at: new Date().toISOString()
      }
    },

    spec: {
      model: {
        provider: detectProvider(gitlabAgent.agent.model),
        name: gitlabAgent.agent.model,
        parameters: {
          temperature: gitlabAgent.agent.temperature ?? 0.2,
          max_tokens: gitlabAgent.resources?.max_tokens ?? 8192
        }
      },

      system_prompt: gitlabAgent.prompts.find(p => p.role === 'system')?.content ?? '',

      tools: convertActions(gitlabAgent.actions),

      inputs: convertParameters(gitlabAgent.parameters),

      outputs: convertResponseFormat(gitlabAgent.response_format),

      resources: {
        token_limit: gitlabAgent.resources?.max_tokens ?? 100000,
        timeout: gitlabAgent.resources?.timeout ?? 300,
        memory: gitlabAgent.resources?.memory ?? '512Mi'
      }
    }
  };

  return stringify(ossa);
}

function convertActions(actions: GitLabDuoAgent['actions']): OSSAAgent['spec']['tools'] {
  return actions.map(action => {
    if (action.gitlab_api) {
      return {
        name: action.name,
        type: 'gitlab_api',
        description: `GitLab API: ${action.name}`,
        endpoints: action.endpoints
      };
    }

    if (action.integration === 'security_scanner') {
      return {
        name: action.name,
        type: 'security',
        description: `Security scan: ${action.type}`
      };
    }

    return {
      name: action.name,
      type: action.type || 'custom',
      description: `Custom tool: ${action.name}`
    };
  });
}

function detectProvider(modelName: string): string {
  if (modelName.includes('claude')) return 'anthropic';
  if (modelName.includes('gpt')) return 'openai';
  if (modelName.includes('gemini')) return 'google';
  return 'unknown';
}

Usage:

# Convert GitLab Duo to OSSA format
npm run convert:gitlab-to-ossa \
  agents/code-reviewer/gitlab-duo.yml \
  agents/code-reviewer/ossa-agent.yml

# Publish to OSSA registry
ossa publish agents/code-reviewer/ossa-agent.yml

CI/CD Pipeline

The repository uses GitLab CI/CD for automated validation, conversion, and publishing.

Pipeline Configuration (.gitlab-ci.yml):

stages:
  - validate
  - convert
  - test
  - publish

# Validate OSSA specifications
validate_ossa:
  stage: validate
  image: node:18
  script:
    - npm ci
    - npm run validate:ossa agents/*/ossa-agent.yml

# Validate GitLab Duo specifications
validate_gitlab:
  stage: validate
  image: node:18
  script:
    - npm ci
    - npm run validate:gitlab agents/*/gitlab-duo.yml

# Test bidirectional conversion
test_conversion:
  stage: convert
  needs: [validate_ossa, validate_gitlab]
  script:
    # Convert OSSA † GitLab Duo
    - |
      for agent in agents/*/ossa-agent.yml; do
        dir=$(dirname $agent)
        npm run convert:ossa-to-gitlab $agent $dir/gitlab-duo-generated.yml
        diff $dir/gitlab-duo.yml $dir/gitlab-duo-generated.yml || \
          echo "Warning: Conversion mismatch for $agent"
      done

    # Convert GitLab Duo † OSSA
    - |
      for agent in agents/*/gitlab-duo.yml; do
        dir=$(dirname $agent)
        npm run convert:gitlab-to-ossa $agent $dir/ossa-agent-generated.yml
        diff $dir/ossa-agent.yml $dir/ossa-agent-generated.yml || \
          echo "Warning: Conversion mismatch for $agent"
      done

# Run agent tests
test_agents:
  stage: test
  needs: [test_conversion]
  parallel:
    matrix:
      - AGENT:
        - code-reviewer
        - security-analyst
        - test-generator
        - documentation-writer
        - bug-analyzer
  script:
    - cd agents/$AGENT
    - npm ci
    - npm test

# Publish to OSSA registry
publish_ossa:
  stage: publish
  needs: [test_agents]
  script:
    - npm install -g @ossa/cli

    # Publish each agent
    - |
      for agent in agents/*/ossa-agent.yml; do
        ossa publish $agent --version $(yq eval '.metadata.version' $agent)
      done

  only:
    - tags

# Sync to GitLab Duo platform
publish_gitlab:
  stage: publish
  needs: [test_agents]
  script:
    # Deploy agents to GitLab Duo
    - |
      for agent in agents/*/gitlab-duo.yml; do
        glab duo agent deploy $agent
      done

  only:
    - tags

Usage Examples

Using Canonical Agents

Install from Repository:

# Clone repository
git clone https://gitlab.com/blueflyio/platform-agents.git
cd platform-agents

# Install agent to GitLab project
glab duo agent install \
  --from agents/code-reviewer/gitlab-duo.yml \
  --project 12345

# Or install from OSSA registry
ossa install blueflyio/code-reviewer@2.1.0

Use in GitLab CI/CD:

# .gitlab-ci.yml
include:
  - project: blueflyio/platform-agents
    file: /agents/code-reviewer/gitlab-ci.yml

code_review:
  extends: .code_reviewer
  variables:
    FOCUS_AREAS: "security,quality"

Creating Custom Agents

Start from Template:

# Copy template
cp -r templates/basic-agent agents/my-custom-agent

cd agents/my-custom-agent

# Edit OSSA specification
vim ossa-agent.yml

# Validate
npm run validate:ossa ossa-agent.yml

# Convert to GitLab Duo format
npm run convert:ossa-to-gitlab \
  ossa-agent.yml \
  gitlab-duo.yml

# Test locally
npm test

# Deploy
glab duo agent deploy gitlab-duo.yml

Best Practices

1. Agent Versioning

Follow semantic versioning:

• MAJOR: Breaking changes to interface
• MINOR: New features, backward compatible
• PATCH: Bug fixes

metadata:
  name: code-reviewer
  version: 2.1.3  # MAJOR.MINOR.PATCH

2. Comprehensive Documentation

Each agent should include:

• README.md - Overview and usage
• examples/ - Working examples
• CHANGELOG.md - Version history

3. Testing

Test agents with:

• Unit tests for conversion logic
• Integration tests with mock GitLab API
• End-to-end tests with real execution

// agents/code-reviewer/tests/agent.test.ts
describe('Code Reviewer Agent', () => {
  it('should detect SQL injection', async () => {
    const result = await agent.run({
      code: 'SELECT * FROM users WHERE id = ' + userId
    });

    expect(result.issues).toContainEqual(
      expect.objectContaining({
        severity: 'critical',
        category: 'sql_injection'
      })
    );
  });
});

4. Resource Limits

Set appropriate limits:

resources:
  token_limit: 100000   # Max tokens per execution
  timeout: 600          # 10 minutes
  memory: 1Gi          # Memory allocation
  max_executions: 100  # Rate limiting

5. Security

• Validate all inputs
• Sanitize outputs
• Use least-privilege permissions
• Audit all executions

Contribution Guidelines

Adding New Agents

1. Create Agent Directory:

   mkdir agents/my-new-agent
   cd agents/my-new-agent

2. Define OSSA Specification:

   # ossa-agent.yml
   apiVersion: ossa/v1
   kind: Agent
   metadata:
     name: my-new-agent
     version: 1.0.0
   spec:
     # ... agent specification

3. Convert to GitLab Duo:

   npm run convert:ossa-to-gitlab ossa-agent.yml gitlab-duo.yml

4. Add Tests:

   mkdir tests
   # Create tests/agent.test.ts

5. Add Documentation:

   # Create README.md
   # Create examples/

6. Submit MR:

   git checkout -b feat/add-my-new-agent
   git add agents/my-new-agent
   git commit -m "feat: add my-new-agent"
   git push origin feat/add-my-new-agent
   glab mr create

Updating Existing Agents

1. Update version in metadata.version
2. Add entry to CHANGELOG.md
3. Update tests if interface changed
4. Re-generate GitLab Duo format
5. Submit MR with clear description

Resources

Repository Links

• Main Repository: https://gitlab.com/blueflyio/platform-agents
• Issue Tracker: https://gitlab.com/blueflyio/platform-agents/-/issues
• MR Guidelines: https://gitlab.com/blueflyio/platform-agents/-/blob/main/CONTRIBUTING.md

Documentation

• OSSA Specification: https://openstandardagents.org
• GitLab Duo Agents: https://docs.gitlab.com/ee/user/gitlab_duo/agents/
• Agent SDK: https://gitlab.com/gitlab-org/duo-agent-sdk

Community

• Discussions: https://gitlab.com/blueflyio/platform-agents/-/issues?label_name=discussion
• Slack: https://blueflyio.slack.com #platform-agents
• Monthly Sync: First Thursday, 10am UTC

Next Steps

1. Explore Agents: Browse agents/ directory
2. Try Conversion: Convert between OSSA and GitLab Duo formats
3. Use in Project: Install canonical agent to your project
4. Create Custom Agent: Use templates to build your own
5. Contribute: Submit improvements or new agents

---

Related Documentation:

• Foundational Agents & Flows
• Agent Interoperability Standards
• CI/CD Agent Patterns