@bluefly/openstandardagents 0.2.8 → 0.2.9

package/.env.example

@@ -4,7 +4,7 @@
 # ===========================================
 # Version & Environment
 # ===========================================
-VERSION=0.2.8
+VERSION=0.2.9
 NODE_ENV=production
 LOG_LEVEL=info
 

package/.github/AGENTS.md

@@ -0,0 +1,245 @@
+# AGENTS.md - Repository-Level Agent Guidance
+
+> This file provides guidance for AI coding agents working on this repository.
+> Follows the [agents.md](https://agents.md) specification.
+
+## Overview
+
+This is the **OSSA (Open Standard for Scalable AI Agents)** repository - the OpenAPI for AI Agents.
+
+**Important**: This GitHub repository is a **public mirror** of our [GitLab repository](https://gitlab.com/blueflyio/openstandardagents). All CI/CD, testing, and releases happen on GitLab.
+
+## Development Environment
+
+### Setup
+
+```bash
+# Clone (from GitHub mirror)
+git clone https://github.com/blueflyio/openstandardagents.git
+cd openstandardagents
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+### Key Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| `spec/` | OSSA schema definitions (JSON Schema) |
+| `src/` | TypeScript CLI and validation library |
+| `examples/` | Example agent manifests for various platforms |
+| `docs/` | Public documentation |
+| `.gitlab/` | GitLab CI/CD and internal agents |
+| `.github/` | GitHub workflows and community tooling |
+
+### Technology Stack
+
+- **Language**: TypeScript (strict mode)
+- **Runtime**: Node.js 20+
+- **Package Manager**: npm (with legacy-peer-deps)
+- **Testing**: Jest
+- **Linting**: ESLint + Prettier
+- **Schema**: JSON Schema Draft-07
+
+## Testing
+
+### Running Tests
+
+```bash
+# All tests
+npm test
+
+# With coverage
+npm test -- --coverage
+
+# Specific file
+npm test -- schema.repository.test.ts
+
+# Watch mode
+npm test -- --watch
+```
+
+### Test Requirements
+
+- All schema changes require validation tests
+- All CLI commands require integration tests
+- Minimum 80% code coverage
+- Tests must pass on Node.js 20 and 22
+
+### Validation
+
+```bash
+# Validate all example manifests
+npm run validate
+
+# Validate specific manifest
+npx ossa validate examples/cursor/code-review-agent.ossa.json
+```
+
+## Pull Request Instructions
+
+### PR Workflow (GitHub Mirror)
+
+1. **Open PR on GitHub** - Community contributions welcome
+2. **Automated Triage** - OSSA agents label and categorize
+3. **Review** - Maintainers review on GitHub
+4. **GitLab Sync** - Approved PRs create GitLab MR
+5. **CI/CD** - Full test suite runs on GitLab
+6. **Merge** - Changes merge on GitLab
+7. **Mirror Sync** - GitHub automatically updated
+8. **PR Auto-Close** - Your PR closes when changes appear
+
+### Commit Convention
+
+Use [Conventional Commits](https://conventionalcommits.org):
+
+```bash
+# Feature (minor version bump)
+git commit -m "feat(schema): add agents_md extension support"
+
+# Bug fix (patch version bump)
+git commit -m "fix(cli): resolve validation timeout"
+
+# Breaking change (major version bump)
+git commit -m "feat!: redesign manifest schema
+
+BREAKING CHANGE: apiVersion format changed"
+
+# Documentation (no release)
+git commit -m "docs: update getting started guide"
+```
+
+### PR Title Format
+
+PR titles should follow conventional commits (becomes squash commit):
+
+- ✅ `feat: add LangGraph extension support`
+- ✅ `fix(schema): correct required fields`
+- ❌ `Updated some stuff`
+- ❌ `WIP`
+
+## Code Style
+
+### TypeScript Guidelines
+
+```typescript
+// ✅ Good: Explicit types, descriptive names
+export async function validateManifest(
+  manifest: OssaManifest,
+  options: ValidationOptions = {}
+): Promise<ValidationResult> {
+  // Implementation
+}
+
+// ❌ Bad: Any types, unclear names
+export async function validate(m: any, o?: any) {
+  // Implementation
+}
+```
+
+### Schema Guidelines
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "pattern": "^ossa/v[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "OSSA API version"
+    }
+  }
+}
+```
+
+### File Naming
+
+- Schema files: `ossa-{version}.schema.json`
+- Example manifests: `{name}.ossa.{json|yaml}`
+- Tests: `{name}.test.ts`
+- Services: `{name}.service.ts`
+
+## Security
+
+### Sensitive Data
+
+**NEVER** commit:
+- API keys or tokens
+- Private keys or certificates
+- Database credentials
+- Internal URLs or endpoints
+
+### Security Issues
+
+**DO NOT** open public issues for security vulnerabilities.
+
+Report via email: **ops@openstandardagents.org**
+
+## Architecture Notes
+
+### Schema Versioning
+
+- Current: `ossa/v0.2.9` (latest stable)
+- Development: `ossa/v0.2.9` (in progress)
+- Format: `ossa/v{major}.{minor}.{patch}`
+
+### Extension System
+
+Extensions allow platform-specific configuration:
+
+```yaml
+extensions:
+  cursor:
+    enabled: true
+    agent_type: composer
+  openai_agents:
+    enabled: true
+    model: gpt-4o
+  agents_md:
+    enabled: true
+    generate: true
+```
+
+### Supported Extensions
+
+| Extension | Platform | Status |
+|-----------|----------|--------|
+| `cursor` | Cursor IDE | Stable |
+| `openai_agents` | OpenAI Agents SDK | Stable |
+| `anthropic` | Claude/Anthropic | Stable |
+| `langchain` | LangChain | Stable |
+| `crewai` | CrewAI | Stable |
+| `kagent` | kAgent (K8s) | Stable |
+| `agents_md` | agents.md | New in v0.2.9 |
+
+## Common Tasks
+
+### Adding a New Extension
+
+1. Add schema definition in `spec/v{version}/ossa-{version}.schema.json`
+2. Create example in `examples/{extension}/`
+3. Add validator in `src/services/validation/`
+4. Write tests in `tests/`
+5. Update documentation
+
+### Updating Schema Version
+
+1. Copy `spec/v{old}/` to `spec/v{new}/`
+2. Update `$id`, `title`, and version references
+3. Make changes
+4. Update `src/types/index.ts`
+5. Run `npm run validate`
+
+---
+
+*Generated from OSSA agent manifests in `.github/agents/`*
+*Last updated: 2025-12-04*

package/.github/agents/github-issue-triage.ossa.yaml

@@ -0,0 +1,99 @@
+# OSSA Agent Manifest: GitHub Issue Triage Agent
+# Triages issues from GitHub and syncs to GitLab
+apiVersion: ossa/v0.2.9
+kind: Agent
+
+metadata:
+  name: github-issue-triage
+  version: 1.0.0
+  description: |
+    Triages GitHub issues, auto-labels based on content,
+    and syncs to GitLab issue tracker for tracking.
+  labels:
+    platform: github
+    domain: devops
+    workflow: issue-triage
+  annotations:
+    documentation: https://openstandardagents.org/docs/agents/github-issue-triage
+
+spec:
+  taxonomy:
+    domain: devops
+    subdomain: issue-management
+    capability: triage
+
+  role: |
+    You are a GitHub issue triage agent for OSSA.
+
+    Your responsibilities:
+    1. Welcome issue reporters and thank them for feedback
+    2. Auto-label issues based on content analysis:
+       - bug: Error reports, unexpected behavior
+       - enhancement: Feature requests, improvements
+       - documentation: Doc updates, clarifications
+       - question: Usage questions, help requests
+       - component:schema: Schema-related issues
+       - component:cli: CLI tool issues
+       - component:extensions: Platform extension issues
+    3. Detect duplicate issues and link them
+    4. Escalate security issues immediately
+    5. Create corresponding GitLab issues for tracking
+    6. Sync comments between platforms
+
+    Be helpful and responsive. Issue reporters are often users
+    trying to adopt OSSA and need guidance.
+
+  llm:
+    provider: openai
+    model: gpt-4o-mini
+    temperature: 0.2
+    maxTokens: 1500
+
+  tools:
+    - type: http
+      name: github-api
+      description: GitHub REST API for issue operations
+      endpoint: https://api.github.com
+      auth:
+        type: bearer
+        tokenPath: GITHUB_TOKEN
+
+    - type: http
+      name: gitlab-api
+      description: GitLab API for issue sync
+      endpoint: https://gitlab.com/api/v4
+      auth:
+        type: bearer
+        tokenPath: GITLAB_TOKEN
+
+  autonomy:
+    level: autonomous
+    approval_required: false
+    allowed_actions:
+      - label_issue
+      - comment_issue
+      - assign_issue
+      - create_gitlab_issue
+      - link_duplicate
+    blocked_actions:
+      - close_issue
+      - delete_issue
+
+  constraints:
+    cost:
+      maxTokensPerDay: 30000
+      maxTokensPerRequest: 2000
+    performance:
+      maxLatencySeconds: 15
+      timeoutSeconds: 60
+
+  observability:
+    logging:
+      level: info
+    metrics:
+      enabled: true
+      customMetrics:
+        - name: issues_triaged
+          type: counter
+        - name: duplicates_detected
+          type: counter

package/.github/agents/github-pr-triage.ossa.yaml

@@ -0,0 +1,137 @@
+# OSSA Agent Manifest: GitHub PR Triage Agent
+# Triages pull requests from GitHub mirror and syncs to GitLab
+apiVersion: ossa/v0.2.9
+kind: Agent
+
+metadata:
+  name: github-pr-triage
+  version: 1.0.0
+  description: |
+    Triages GitHub pull requests, validates contributions,
+    and creates corresponding merge requests on GitLab.
+  labels:
+    platform: github
+    domain: devops
+    workflow: pr-triage
+  annotations:
+    documentation: https://openstandardagents.org/docs/agents/github-pr-triage
+    source: https://gitlab.com/blueflyio/openstandardagents
+
+spec:
+  taxonomy:
+    domain: devops
+    subdomain: code-review
+    capability: pr-triage
+
+  role: |
+    You are a GitHub PR triage agent for the OSSA (Open Standard for Scalable AI Agents) project.
+
+    Your responsibilities:
+    1. Welcome contributors and explain the GitHub-to-GitLab workflow
+    2. Validate PR titles follow Conventional Commits format
+    3. Check PR content for:
+       - Schema changes (spec/**) - require careful review
+       - CLI changes (src/**) - require tests
+       - Documentation changes (docs/**) - can be fast-tracked
+       - Example additions (examples/**) - require validation
+    4. Auto-label PRs based on content type
+    5. Create corresponding GitLab MR when approved
+    6. Sync comments and reviews between platforms
+
+    Be welcoming to new contributors. Many are unfamiliar with the dual-repo workflow.
+    Provide clear guidance on how to contribute effectively.
+
+  llm:
+    provider: openai
+    model: gpt-4o
+    temperature: 0.3
+    maxTokens: 2000
+
+  tools:
+    - type: http
+      name: github-api
+      description: GitHub REST API for PR operations
+      endpoint: https://api.github.com
+      auth:
+        type: bearer
+        tokenPath: GITHUB_TOKEN
+      config:
+        headers:
+          Accept: application/vnd.github+json
+          X-GitHub-Api-Version: "2022-11-28"
+
+    - type: http
+      name: gitlab-api
+      description: GitLab API for MR creation
+      endpoint: https://gitlab.com/api/v4
+      auth:
+        type: bearer
+        tokenPath: GITLAB_TOKEN
+
+    - type: mcp
+      name: git-operations
+      description: Git operations for branch sync
+      server: git-mcp
+      capabilities:
+        - name: clone
+        - name: checkout
+        - name: push
+        - name: diff
+
+  autonomy:
+    level: supervised
+    approval_required: false
+    allowed_actions:
+      - label_pr
+      - comment_pr
+      - request_changes
+      - create_gitlab_mr
+      - sync_comments
+    blocked_actions:
+      - merge_pr
+      - close_pr_without_reason
+      - delete_branch
+
+  constraints:
+    cost:
+      maxTokensPerDay: 50000
+      maxTokensPerRequest: 4000
+    performance:
+      maxLatencySeconds: 30
+      timeoutSeconds: 120
+
+  observability:
+    logging:
+      level: info
+      format: json
+    metrics:
+      enabled: true
+      customMetrics:
+        - name: prs_triaged
+          type: counter
+          description: Number of PRs triaged
+        - name: gitlab_mrs_created
+          type: counter
+          description: Number of GitLab MRs created from GitHub PRs
+
+extensions:
+  cursor:
+    enabled: false
+
+  agents_md:
+    enabled: true
+    generate: true
+    output_path: .github/AGENTS.md
+    sections:
+      dev_environment:
+        enabled: true
+        custom: |
+          - This repo is a GitHub mirror of GitLab
+          - PRs here trigger triage to GitLab
+          - Use Conventional Commits for PR titles
+      pr_instructions:
+        enabled: true
+        custom: |
+          - PRs are reviewed here then synced to GitLab
+          - CI/CD runs on GitLab, not GitHub
+          - Maintainers will create GitLab MR from approved PRs

package/.github/workflows/issue-sync-to-gitlab.yml

@@ -0,0 +1,138 @@
+name: Issue Sync to GitLab
+
+on:
+  issues:
+    types: [opened, edited, closed, reopened, labeled]
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  # Triage new issues
+  triage-issue:
+    if: github.event_name == 'issues' && github.event.action == 'opened'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Auto-label Issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const title = issue.title.toLowerCase();
+            const body = (issue.body || '').toLowerCase();
+            const labels = ['github-issue'];
+
+            // Auto-detect issue type from title/body
+            if (title.includes('bug') || title.includes('error') || title.includes('fix')) {
+              labels.push('bug');
+            } else if (title.includes('feature') || title.includes('request') || title.includes('add')) {
+              labels.push('enhancement');
+            } else if (title.includes('doc') || title.includes('readme')) {
+              labels.push('documentation');
+            } else if (title.includes('question') || title.includes('help')) {
+              labels.push('question');
+            }
+
+            // Detect component from content
+            if (body.includes('schema') || body.includes('manifest')) {
+              labels.push('component:schema');
+            }
+            if (body.includes('cli') || body.includes('command')) {
+              labels.push('component:cli');
+            }
+            if (body.includes('extension') || body.includes('cursor') || body.includes('langchain')) {
+              labels.push('component:extensions');
+            }
+
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issue.number,
+              labels: labels
+            });
+
+      - name: Welcome Comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const author = issue.user.login;
+
+            const welcomeMessage = `## 👋 Thanks for opening an issue, @${author}!
+
+We appreciate your feedback on **OSSA (Open Standard for Scalable AI Agents)**.
+
+### 📋 What happens next?
+
+1. **🏷️ Auto-Labeling** - Issue has been automatically labeled based on content
+2. **🔗 GitLab Sync** - This issue will be synced to our [GitLab repository](https://gitlab.com/blueflyio/openstandardagents/-/issues)
+3. **👀 Triage** - Core team will review within 24-48 hours
+4. **💬 Updates** - You'll be notified here when there's progress
+
+### 🔍 Quick Links
+
+- 📖 [Documentation](https://openstandardagents.org)
+- 💬 [Discord Community](https://discord.gg/ossa)
+- 🦊 [GitLab Issues](https://gitlab.com/blueflyio/openstandardagents/-/issues)
+
+---
+
+*This repository is a public mirror. Active development happens on [GitLab](https://gitlab.com/blueflyio/openstandardagents).*`;
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issue.number,
+              body: welcomeMessage
+            });
+
+      - name: Notify GitLab Agent Platform
+        if: ${{ secrets.GITLAB_WEBHOOK_URL }}
+        run: |
+          curl -X POST "${{ secrets.GITLAB_WEBHOOK_URL }}" \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Event: issues" \
+            -d '{
+              "event": "github_issue_opened",
+              "issue_number": ${{ github.event.issue.number }},
+              "issue_title": "${{ github.event.issue.title }}",
+              "issue_url": "${{ github.event.issue.html_url }}",
+              "author": "${{ github.event.issue.user.login }}"
+            }'
+
+  # Sync issue closure
+  sync-issue-close:
+    if: github.event_name == 'issues' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Log Closure
+        run: |
+          echo "Issue #${{ github.event.issue.number }} closed"
+          echo "Closed by: ${{ github.event.sender.login }}"
+
+  # Sync new comments
+  sync-comment:
+    if: github.event_name == 'issue_comment' && github.event.action == 'created'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Notify GitLab of Comment
+        if: ${{ secrets.GITLAB_WEBHOOK_URL }}
+        run: |
+          # Skip bot comments
+          if [[ "${{ github.event.comment.user.login }}" == *"bot"* ]]; then
+            echo "Skipping bot comment"
+            exit 0
+          fi
+
+          curl -X POST "${{ secrets.GITLAB_WEBHOOK_URL }}" \
+            -H "Content-Type: application/json" \
+            -H "X-GitHub-Event: issue_comment" \
+            -d '{
+              "event": "github_comment_created",
+              "issue_number": ${{ github.event.issue.number }},
+              "comment_url": "${{ github.event.comment.html_url }}",
+              "author": "${{ github.event.comment.user.login }}"
+            }'