@bluefly/openstandardagents 0.3.1 → 0.3.3

package/dist/spec/extensions/skills-compatibility.md

@@ -0,0 +1,292 @@
+# OSSA Skills Extension
+
+## Overview
+
+This extension defines OSSA compatibility with the [Anthropic Skills](https://github.com/anthropics/skills) and [Agent Skills](https://agentskills.io) specifications. It enables OSSA agents to be packaged and distributed as Skills, and allows Skills to be consumed by OSSA-compliant runtimes.
+
+**Version**: 0.3.3
+**Status**: Draft
+**Authors**: Bluefly AI Platform Team
+
+## Goals
+
+1. **Bidirectional Compatibility**: OSSA manifests can generate valid SKILL.md files
+2. **Progressive Disclosure**: Support the Skills metadata → instructions → resources pattern
+3. **Validation Alignment**: OSSA validation rules match Skills constraints
+
+## Skills Format Overview
+
+Skills use a simple folder structure:
+
+```
+my-skill/
+├── SKILL.md          # Required - YAML frontmatter + Markdown instructions
+├── references/       # Optional - On-demand documentation
+└── assets/           # Optional - Static resources (templates, data)
+```
+
+## SKILL.md Format
+
+```yaml
+---
+name: my-skill-name
+description: A clear description of what this skill does
+license: Apache-2.0
+compatibility: "Claude, Claude Code"
+metadata:
+  author: "Bluefly AI"
+  version: "1.0.0"
+allowed-tools: ["Read", "Write", "Bash"]
+---
+
+# My Skill Name
+
+Instructions for the agent to follow when this skill is active.
+
+## Examples
+- Example usage patterns
+
+## Guidelines
+- Best practices and constraints
+```
+
+## OSSA to Skills Mapping
+
+### Required Fields
+
+| Skills Field | OSSA Manifest Path | Transformation |
+|--------------|-------------------|----------------|
+| `name` | `metadata.name` | Validate 1-64 chars, lowercase alphanumeric + hyphens |
+| `description` | `metadata.description` | Validate 1-1024 chars |
+
+### Optional Fields
+
+| Skills Field | OSSA Manifest Path | Notes |
+|--------------|-------------------|-------|
+| `license` | `metadata.license` | Direct mapping |
+| `compatibility` | `spec.runtime.platforms` | Comma-separated list |
+| `metadata.*` | `metadata.annotations` | Key-value pairs |
+| `allowed-tools` | `spec.capabilities[].name` | Filter for tool capabilities |
+
+### Markdown Body
+
+The Skills markdown body maps to OSSA as follows:
+
+| Skills Section | OSSA Path |
+|----------------|-----------|
+| Instructions | `spec.instructions` or `spec.systemPrompt` |
+| Examples | `spec.examples[]` |
+| Guidelines | `spec.constraints[]` |
+
+## Progressive Disclosure
+
+Skills implement progressive disclosure in three stages:
+
+### Stage 1: Metadata (~100 tokens)
+```yaml
+name: my-skill
+description: What this skill does and when to use it
+```
+
+OSSA equivalent:
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: my-skill
+  description: What this skill does and when to use it
+```
+
+### Stage 2: Instructions (<5000 tokens)
+Full SKILL.md body loaded on activation.
+
+OSSA equivalent: `spec.instructions` field.
+
+### Stage 3: Resources (on-demand)
+References and assets loaded as needed via OpenAPI endpoints.
+
+OSSA equivalent: `runtime.resources[]` bindings with OpenAPI-first access.
+
+## Directory Conventions
+
+OSSA agents supporting Skills format SHOULD use these directories:
+
+| Directory | Purpose | OSSA Mapping |
+|-----------|---------|--------------|
+| `references/` | Documentation | `runtime.resources[type=documentation]` |
+| `assets/` | Static files | `runtime.resources[type=static]` |
+
+## Validation Rules
+
+To be Skills-compatible, OSSA manifests MUST pass these validations:
+
+### Name Validation
+```yaml
+# Skills constraint
+pattern: "^[a-z0-9-]{1,64}$"
+rules:
+  - Cannot start or end with hyphen
+  - Cannot contain consecutive hyphens
+  - Must match parent directory name (for file-based distribution)
+```
+
+### Description Validation
+```yaml
+# Skills constraint
+minLength: 1
+maxLength: 1024
+```
+
+## Generating SKILL.md from OSSA
+
+```bash
+# CLI command
+ossa export --format skills --output ./my-skill/
+
+# Generates:
+# - SKILL.md with YAML frontmatter
+# - references/ directory from documentation resources
+```
+
+## Consuming Skills in OSSA
+
+```bash
+# CLI command
+ossa import --format skills --path ./my-skill/
+
+# Creates:
+# - .agents/my-skill/manifest.yaml
+```
+
+## Example: Full Mapping
+
+### Skills SKILL.md
+```yaml
+---
+name: drupal-content-publisher
+description: Publishes content to Drupal CMS with proper validation and scheduling
+license: GPL-2.0-or-later
+compatibility: "Claude Code, Cursor"
+metadata:
+  author: "Bluefly AI"
+  version: "1.0.0"
+  category: "cms"
+allowed-tools: ["WebFetch", "Bash", "Read", "Write"]
+---
+
+# Drupal Content Publisher
+
+This skill helps you publish content to Drupal with proper validation.
+
+## Instructions
+
+1. Check if content exists using entity query
+2. Validate against Drupal schema
+3. Use JSON:API or REST to publish
+4. Verify publication status
+
+## Examples
+
+- Publish an article: "Publish 'My Article' with body text and image"
+- Update node: "Update node 123 with new title"
+
+## Guidelines
+
+- Always validate content before publishing
+- Check user permissions
+- Handle media uploads separately
+```
+
+### Equivalent OSSA Manifest
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: drupal-content-publisher
+  version: 1.0.0
+  description: Publishes content to Drupal CMS with proper validation and scheduling
+  license: GPL-2.0-or-later
+  annotations:
+    author: "Bluefly AI"
+    category: "cms"
+    skills.compatible: "true"
+    skills.platforms: "Claude Code, Cursor"
+spec:
+  type: worker
+  capabilities:
+    - name: web_fetch
+      type: tool
+    - name: bash
+      type: tool
+    - name: read
+      type: tool
+    - name: write
+      type: tool
+  instructions: |
+    This skill helps you publish content to Drupal with proper validation.
+
+    1. Check if content exists using entity query
+    2. Validate against Drupal schema
+    3. Use JSON:API or REST to publish
+    4. Verify publication status
+  examples:
+    - input: "Publish 'My Article' with body text and image"
+      description: "Publish an article"
+    - input: "Update node 123 with new title"
+      description: "Update existing node"
+  constraints:
+    - "Always validate content before publishing"
+    - "Check user permissions"
+    - "Handle media uploads separately"
+runtime:
+  platforms:
+    - claude-code
+    - cursor
+```
+
+## Schema Addition
+
+Add to `ossa-0.3.x.schema.json`:
+
+```json
+{
+  "definitions": {
+    "SkillsExtension": {
+      "type": "object",
+      "description": "Anthropic/AgentSkills.io compatibility extension",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable Skills format export/import"
+        },
+        "allowedTools": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Pre-approved tools (maps to spec.capabilities)"
+        },
+        "platforms": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Compatible platforms (Claude, Claude Code, Cursor, etc.)"
+        },
+        "progressiveDisclosure": {
+          "type": "object",
+          "properties": {
+            "metadataTokens": { "type": "integer", "default": 100 },
+            "instructionsTokens": { "type": "integer", "default": 5000 }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## References
+
+- [Anthropic Skills Repository](https://github.com/anthropics/skills)
+- [Agent Skills Specification](https://agentskills.io/specification)
+- [What Are Skills](https://agentskills.io/what-are-skills)
+- [Integrate Skills](https://agentskills.io/integrate-skills)
+- [OSSA Manifest Extensions](./manifest-extensions.md)

package/dist/spec/registry/README.md

@@ -291,7 +291,7 @@ $ ossa install blueflyio/k8s-security-scanner
 ⬇️  Downloading k8s-security-scanner@1.2.0...
 ✓ Checksum verified
 📦 Resolving dependencies...
-✓ @ossa/runtime@0.3.2
+✓ @ossa/runtime@0.3.3
 ✓ kubernetes-tools@1.28.4
 ✅ Installed k8s-security-scanner@1.2.0
 

package/dist/spec/registry/registry-spec.md

@@ -686,7 +686,7 @@ Retrieve agent dependencies with version resolution.
     "runtime": {
       "@ossa/runtime": {
         "required": "^0.3.0",
-        "resolved": "0.3.2",
+        "resolved": "0.3.3",
         "type": "runtime"
       }
     },
@@ -707,9 +707,9 @@ Retrieve agent dependencies with version resolution.
   },
   "dependency_tree": {
     "blueflyio/security-scanner@1.2.0": {
-      "@ossa/runtime@0.3.2": {},
+      "@ossa/runtime@0.3.3": {},
       "blueflyio/vuln-db-agent@2.1.5": {
-        "@ossa/runtime@0.3.2": {}
+        "@ossa/runtime@0.3.3": {}
       },
       "kubernetes-api@1.28.4": {}
     }
@@ -1163,9 +1163,9 @@ OSSA CLI resolves dependencies using semver:
 ```bash
 # Example dependency tree
 security-scanner@1.2.0
-├── @ossa/runtime@0.3.2
+├── @ossa/runtime@0.3.3
 ├── vuln-db-agent@2.1.5
-│   └── @ossa/runtime@0.3.2 (deduped)
+│   └── @ossa/runtime@0.3.3 (deduped)
 └── kubernetes-tools@1.28.4
 
 # CLI automatically:
@@ -1332,7 +1332,7 @@ Every published agent undergoes automated security scanning:
 ```yaml
 # Check dependencies for known vulnerabilities
 ✓ No vulnerable dependencies found
-  Scanned: @ossa/runtime@0.3.2, vuln-scanner-lib@2.1.0
+  Scanned: @ossa/runtime@0.3.3, vuln-scanner-lib@2.1.0
 ```
 
 #### 3. Secret Detection

package/dist/spec/v0.3.1/examples/agent-with-identity.ossa.yaml

@@ -0,0 +1,68 @@
+# OSSA v0.3.1 Agent with Identity Configuration
+# Demonstrates service account integration for automated git operations
+apiVersion: ossa/v0.3.2
+kind: Agent
+metadata:
+  name: typescript-worker
+  version: 1.0.0
+  description: TypeScript development agent with GitLab service account identity
+  labels:
+    team: platform
+    tier: development
+spec:
+  role: |
+    You are a TypeScript development assistant that manages code changes
+    for the agent-buildkit and related TypeScript projects.
+
+  llm:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    temperature: 0.2
+
+  # Agent Identity Configuration (v0.3.1+)
+  identity:
+    provider: gitlab
+    service_account:
+      id: 31840529
+      username: bot-ts-local
+      email: bot-ts-local@bluefly.io
+    token_source:
+      env_var: GITLAB_BOT_TS_TOKEN
+      file_path: ~/.tokens/bot-ts-local
+    patterns:
+      - "*/common_npm/*"
+      - "*/agent-buildkit"
+      - "*/agent-studio"
+    dora_tracking:
+      enabled: true
+      metrics:
+        - deployment_frequency
+        - lead_time
+        - change_failure_rate
+        - mttr
+    observability:
+      service_name: typescript-worker
+      service_namespace: development
+      service_version: "1.0.0"
+
+  tools:
+    - name: git
+      type: mcp
+      config:
+        server: git-mcp-server
+    - name: file-operations
+      type: mcp
+      config:
+        server: filesystem-mcp-server
+
+  autonomy:
+    level: supervised
+    require_approval:
+      - push_to_protected_branch
+      - delete_branch
+      - force_push
+
+  safety:
+    max_tokens_per_turn: 8000
+    rate_limits:
+      requests_per_minute: 30

package/dist/spec/v0.3.1/examples/drupal-content-writer.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.2
 kind: Agent
 metadata:
   name: drupal-content-writer

package/dist/spec/v0.3.1/examples/drupal-moderation-assistant.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.2
 kind: Agent
 metadata:
   name: drupal-moderation-assistant

package/dist/spec/v0.3.1/examples/multi-provider-identity.ossa.yaml

@@ -0,0 +1,236 @@
+# OSSA v0.3.1 Multi-Provider Identity Configuration
+# Enterprise-grade agent with fallback identity chain and compliance
+apiVersion: ossa/v0.3.2
+kind: Agent
+metadata:
+  name: enterprise-deployer
+  version: 2.0.0
+  description: Enterprise deployment agent with multi-provider identity and compliance
+  labels:
+    team: platform
+    tier: production
+    compliance: soc2
+  annotations:
+    security.ossa.io/audit-level: high
+    security.ossa.io/mfa-required: "true"
+spec:
+  role: |
+    You are an enterprise deployment orchestrator responsible for managing
+    production deployments across multiple cloud providers and git platforms.
+    You must ensure all operations are auditable, compliant, and follow
+    the principle of least privilege.
+
+  llm:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    temperature: 0.1
+    max_tokens: 16000
+
+  # Comprehensive Identity Configuration
+  identity:
+    # Primary: GitLab self-hosted
+    provider: gitlab
+    service_account:
+      id: 31840535
+      username: bot-ci-local
+      email: bot-ci-local@bluefly.io
+      display_name: CI/CD Bot
+      roles:
+        - maintainer
+
+    # Authentication with rotation policy
+    authentication:
+      method: project_access_token
+      scopes:
+        - api
+        - read_repository
+        - write_repository
+        - read_registry
+        - write_registry
+      auto_refresh: true
+      expiry_warning_days: 14
+      rotation_policy:
+        enabled: true
+        interval_days: 90
+        notify_on_rotation: true
+
+    # Multi-source token configuration
+    token_source:
+      env_var: GITLAB_BOT_CI_TOKEN
+      file_path: ~/.tokens/bot-ci-local
+      vault:
+        path: secret/data/ci/gitlab-token
+        key: token
+        role: ci-agent
+      kubernetes_secret:
+        name: gitlab-ci-token
+        namespace: ci-cd
+        key: token
+
+    # Auto-detection patterns
+    patterns:
+      - "*/gitlab_components"
+      - "*/infrastructure/*"
+      - "**/deploy/**"
+      - "**/ci-cd/**"
+
+    # Fallback identity chain for high availability
+    fallback:
+      - provider: github
+        service_account:
+          username: enterprise-ci-bot
+          email: ci-bot@enterprise.com
+        token_source:
+          env_var: GITHUB_CI_TOKEN
+          vault:
+            path: secret/data/ci/github-token
+        condition:
+          platform_unavailable: true
+
+      - provider: azure-devops
+        service_account:
+          username: ado-ci-service
+          email: ci-service@enterprise.onmicrosoft.com
+        token_source:
+          azure_key_vault:
+            vault_url: https://enterprise-vault.vault.azure.net
+            secret_name: ado-ci-token
+        condition:
+          pattern_match:
+            - "**/azure/**"
+
+    # Full DORA metrics tracking
+    dora_tracking:
+      enabled: true
+      metrics:
+        - deployment_frequency
+        - lead_time
+        - change_failure_rate
+        - mttr
+      labels:
+        environment: production
+        team: platform
+        cost_center: engineering
+      prometheus:
+        push_gateway: http://prometheus-pushgateway:9091
+        job_name: enterprise-deployer
+      classifications:
+        deployment_frequency:
+          elite: multiple_per_day
+          high: daily
+          medium: weekly
+          low: monthly
+        lead_time:
+          elite: "1"
+          high: "24"
+          medium: "168"
+          low: "720"
+
+    # Claude Code session integration
+    session:
+      init_on_start: true
+      propagate_to_subprocesses: true
+      git_attribution: true
+      heartbeat_interval: 60
+      timeout: 7200
+      hooks:
+        pre_prompt_submit: true
+        post_session: true
+
+    # OpenTelemetry observability
+    observability:
+      service_name: enterprise-deployer
+      service_namespace: production
+      service_version: "2.0.0"
+      service_instance_id: ${HOSTNAME}
+      resource_attributes:
+        deployment.environment: production
+        cloud.provider: multi
+
+    # Enterprise compliance
+    compliance:
+      require_mfa: true
+      ip_allowlist:
+        - 10.0.0.0/8
+        - 172.16.0.0/12
+        - 192.168.0.0/16
+      audit_logging: required
+      data_residency: us-east-1
+      frameworks:
+        - SOC2
+        - ISO27001
+
+    # Security policies
+    security:
+      token_encryption: both
+      minimum_token_length: 40
+      prohibited_actions:
+        - delete_production_branch
+        - disable_branch_protection
+        - modify_security_policies
+      required_approvals:
+        force_push: true
+        delete_protected_branch: true
+        modify_ci_config: true
+      rate_limits:
+        requests_per_minute: 100
+        requests_per_hour: 2000
+        git_operations_per_hour: 200
+
+  # Tool configuration
+  tools:
+    - name: kubernetes
+      type: mcp
+      config:
+        server: kubernetes-mcp-server
+        allowed_namespaces:
+          - production
+          - staging
+    - name: terraform
+      type: mcp
+      config:
+        server: terraform-mcp-server
+        workspace: production
+    - name: git
+      type: mcp
+      config:
+        server: git-mcp-server
+
+  # Strict autonomy controls
+  autonomy:
+    level: semi-autonomous
+    require_approval:
+      - deploy_to_production
+      - rollback_deployment
+      - scale_down_replicas
+      - modify_secrets
+    approval_timeout: 3600
+    escalation:
+      enabled: true
+      timeout: 1800
+      channels:
+        - slack://platform-oncall
+        - pagerduty://platform-critical
+
+  # Comprehensive safety configuration
+  safety:
+    max_tokens_per_turn: 16000
+    rate_limits:
+      requests_per_minute: 30
+      max_concurrent_requests: 5
+    circuit_breaker:
+      enabled: true
+      failure_threshold: 5
+      recovery_timeout: 300
+    kill_switch:
+      enabled: true
+      trigger_conditions:
+        - error_rate > 0.5
+        - latency_p99 > 30000
+      recovery_requires_approval: true
+
+  # State management
+  state:
+    storage: redis
+    ttl: 86400
+    encryption: aes-256-gcm

package/dist/spec/v0.3.1/examples/quick-wins/complete-agent-with-quick-wins.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.2
 kind: Agent
 metadata:
   name: example-agent-quick-wins