Skip to main content

README

Agent Generator

Auto-generate 66 OSSA agent manifests from separation-of-duties.md

Overview

This tool parses the separation-of-duties.md file and automatically generates:

  • OSSA v0.3.3 compliant agent manifests (YAML)
  • MCP tool definitions (JSON)
  • Agent profiles with proper separation of duties
  • Full validation and error checking

Features

  • DRY: Uses config.json tokens for all paths
  • Type-Safe: Zod validation for all schemas
  • SOLID: Clean architecture with dependency injection
  • Comprehensive Testing: Full test suite with Jest
  • Error Handling: Clear, actionable error messages

Installation

npm install
npm run build

Usage

Generate All Agent Manifests

npm run dev -- generate-agents \
  --input /Volumes/AgentPlatform/wikis/blueflyio/separation-of-duties.md \
  --output ./platform-agents \
  --overwrite

Generate MCP Tool Definitions

npm run dev -- generate-mcp-tools \
  --input /Volumes/AgentPlatform/wikis/blueflyio/separation-of-duties.md \
  --output ./mcp-tools \
  --overwrite

Validate Generated Manifests

npm run dev -- validate-manifests --path ./platform-agents

List All Projects

# List all projects
npm run dev -- list-projects

# List only canonical agents
npm run dev -- list-projects --canonical

CLI Commands

[object Object]

Generate OSSA agent manifests from separation-of-duties.md

Options:

  • -i, --input <path> - Path to separation-of-duties.md (default: uses config.json token)
  • -o, --output <path> - Output directory (default: ./platform-agents)
  • --format <format> - Output format: yaml|json (default: yaml)
  • --overwrite - Overwrite existing manifests

Example:

agent-generator generate-agents \
  --input /Volumes/AgentPlatform/wikis/blueflyio/separation-of-duties.md \
  --output /path/to/platform-agents \
  --overwrite

[object Object]

Generate MCP tool definitions for agents

Options:

  • -i, --input <path> - Path to separation-of-duties.md
  • -o, --output <path> - Output directory (default: ./mcp-tools)
  • --overwrite - Overwrite existing files

Example:

agent-generator generate-mcp-tools \
  --output ./mcp-tools \
  --overwrite

[object Object]

Validate OSSA manifests in a directory

Options:

  • -p, --path <path> - Path to manifests directory (default: ./platform-agents)

Example:

agent-generator validate-manifests --path ./platform-agents

[object Object]

List all projects from separation-of-duties.md

Options:

  • -i, --input <path> - Path to separation-of-duties.md
  • --canonical - Show only 16 canonical agents

Example:

agent-generator list-projects --canonical

Architecture

agent-generator/
├── src/
│   ├── types/
│   │   └── schemas.ts          # Zod schemas for validation
│   ├── parsers/
│   │   └── separation-of-duties-parser.ts  # Markdown parser
│   ├── generators/
│   │   ├── ossa-manifest-generator.ts      # OSSA manifest generator
│   │   └── mcp-tool-generator.ts           # MCP tool generator
│   ├── utils/
│   │   ├── config-loader.ts    # Config.json loader with token resolution
│   │   └── file-writer.ts      # File operations
│   ├── __tests__/              # Test suite
│   ├── cli.ts                  # CLI interface
│   └── index.ts                # Exports
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

Development

Run Tests

npm test

Watch Mode

npm run test:watch

Build

npm run build

Lint

npm run lint

Format

npm run format

Generated Manifest Structure

Each generated manifest follows OSSA v0.3.3 specification:

apiVersion: ossa/v0.4.9
kind: Agent
metadata:
  name: agent-name
  version: 1.0.0
  description: Agent purpose
  author: BlueFly.io Platform Team
  license: Apache-2.0
  repository: https://gitlab.com/blueflyio/platform-agents/...
  tags: [ossa, bluefly, platform, ...]

spec:
  role: |
    System prompt with:
    - PURPOSE
    - RESPONSIBILITIES
    - NOT RESPONSIBLE FOR
    - CRITICAL RULES
  
  llm:
    provider: anthropic
    model: claude-sonnet-4
    parameters:
      temperature: 0.7
      max_tokens: 4096
  
  tools:
    - type: function
      name: execute
      description: ...
      input_schema: {...}
      output_schema: {...}
  
  runtime:
    type: docker
    image: node:20-alpine
  
  dependencies:
    agents:
      - id: dependency-agent
        version: ^1.0.0
    services:
      - type: database
        provider: postgresql
  
  extensions:
    skills_compatibility:
      enabled: true
      platforms: [langchain, crewai, autogen, gitlab-duo]
    llms_txt:
      enabled: true
    agents_md:
      enabled: true

MCP Tool Structure

{
  "name": "agent-name",
  "description": "Agent purpose",
  "version": "0.4.9",
  "protocol": "mcp/1.0",
  "tools": [
    {
      "name": "agent-name_execute",
      "description": "Execute operations",
      "inputSchema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": ["execute", "validate", "status", "cancel"]
          },
          "parameters": {
            "type": "object"
          }
        },
        "required": ["action"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "object" },
          "error": { "type": "string" }
        }
      }
    }
  ],
  "security": {
    "authentication": {
      "type": "oauth2",
      "provider": "gitlab"
    },
    "authorization": {
      "rbac": {
        "roles": ["admin", "user", "agent"]
      }
    }
  }
}

Configuration

The tool uses config.json for all paths and tokens:

  • $NAS_MOUNT - NAS mount point
  • $WIKIS_BASE - Wikis base directory
  • $BARE_REPOS - Bare repositories directory
  • $ORG_NAME - Organization name
  • $NPM_SCOPE - NPM package scope

Paths are automatically resolved using token substitution.

Testing

Full test coverage with Jest:

  • Parser tests: Markdown parsing and extraction
  • Generator tests: OSSA manifest generation
  • MCP tests: MCP tool definition generation
  • Integration tests: End-to-end workflow

Coverage Threshold: 80%

Error Handling

Clear, actionable error messages with Zod validation:

Validation Error at spec.capabilities[0].name:
  Required field 'name' is missing
  Expected: string matching ^[a-z0-9_]+$
  Location: manifest.yaml:15:5

  Fix: Add a valid capability name

License

Apache-2.0

Author

BlueFly.io Platform Team