@bluefly/openstandardagents 0.3.2 → 0.3.3

package/spec/extensions/openapi/ossa-openapi-extensions.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://openstandardagents.org/schemas/v0.3.2/extensions/openapi/ossa-openapi-extensions.json",
+  "$id": "https://openstandardagents.org/schemas/v0.3.3/extensions/openapi/ossa-openapi-extensions.json",
   "title": "OSSA OpenAPI Extensions Schema",
-  "description": "JSON Schema for validating OpenAPI 3.x documents that use OSSA (Open Standard for Scalable AI Agents) extensions. This schema defines all OSSA-specific vendor extensions (x-ossa-*) that can be added to OpenAPI specifications to enable agent-aware APIs.",
-  "version": "0.3.2",
+  "description": "JSON Schema for validating OpenAPI 3.x documents that use OSSA (Open Standard for Software Agents) extensions. This schema defines all OSSA-specific vendor extensions (x-ossa-*) that can be added to OpenAPI specifications to enable agent-aware APIs.",
+  "version": "0.3.3",
   "type": "object",
   "properties": {
     "openapi": {
@@ -42,7 +42,7 @@
           "type": "string",
           "pattern": "^(0\\.[0-9]+\\.[0-9]+|[1-9][0-9]*\\.[0-9]+\\.[0-9]+)(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$",
           "description": "OSSA specification version (semver format)",
-          "examples": ["0.3.2", "1.0.0", "0.3.2-beta.1"]
+          "examples": ["0.3.3", "1.0.0", "0.3.3-beta.1"]
         },
         "compliance": {
           "type": "object",
@@ -136,7 +136,7 @@
       "additionalProperties": false,
       "examples": [
         {
-          "version": "0.3.2",
+          "version": "0.3.3",
           "compliance": {
             "level": "standard",
             "frameworks": ["SOC2", "GDPR"]
@@ -231,12 +231,12 @@
       "additionalProperties": false,
       "examples": [
         {
-          "version": "0.3.2",
+          "version": "0.3.3",
           "agent": {
             "id": "code-reviewer-agent",
             "type": "specialist",
             "compliance": {
-              "standards": ["OSSA-0.3.2", "SOC2-Type2"],
+              "standards": ["OSSA-0.3.3", "SOC2-Type2"],
               "validated": true,
               "validatedAt": "2025-01-15T10:30:00Z"
             }
@@ -728,7 +728,7 @@
         "description": "API for automated code review agent"
       },
       "x-ossa-metadata": {
-        "version": "0.3.2",
+        "version": "0.3.3",
         "compliance": {
           "level": "standard",
           "frameworks": ["SOC2"]
@@ -744,12 +744,12 @@
         }
       },
       "x-ossa": {
-        "version": "0.3.2",
+        "version": "0.3.3",
         "agent": {
           "id": "code-reviewer",
           "type": "specialist",
           "compliance": {
-            "standards": ["OSSA-0.3.2"],
+            "standards": ["OSSA-0.3.3"],
             "validated": true
           }
         }

package/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/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/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/spec/v0.3.2/MIGRATION-v0.3.1-to-v0.3.2.md

@@ -1,4 +1,4 @@
-# Migration Guide: OSSA v0.3.1 → v0.3.2
+# Migration Guide: OSSA v0.3.3 → v0.3.3
 
 > **Status**: Draft  
 > **Last Updated**: 2025-12-28
@@ -7,11 +7,11 @@
 
 ## Overview
 
-OSSA v0.3.2 introduces **Access Tiers & Separation of Duties** while maintaining backward compatibility with v0.3.1 manifests.
+OSSA v0.3.3 introduces **Access Tiers & Separation of Duties** while maintaining backward compatibility with v0.3.3 manifests.
 
 ### Key Changes
 
-- ✅ **Backward Compatible**: v0.3.1 manifests validate against v0.3.2 schema
+- ✅ **Backward Compatible**: v0.3.3 manifests validate against v0.3.3 schema
 - ✅ **Optional Features**: Access tiers are optional - existing agents work without changes
 - ✅ **Progressive Enhancement**: Add access tiers when ready
 
@@ -21,10 +21,10 @@ OSSA v0.3.2 introduces **Access Tiers & Separation of Duties** while maintaining
 
 ### Option 1: No Changes Required (Recommended for Existing Agents)
 
-**v0.3.1 agents continue to work without modification:**
+**v0.3.3 agents continue to work without modification:**
 
 ```yaml
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Agent
 metadata:
   name: my-agent
@@ -35,14 +35,14 @@ spec:
     model: claude-sonnet
 ```
 
-**This manifest validates against v0.3.2 schema** - no changes needed.
+**This manifest validates against v0.3.3 schema** - no changes needed.
 
 ### Option 2: Update API Version Only
 
 Simply update the `apiVersion` field:
 
 ```yaml
-apiVersion: ossa/v0.3.2  # Changed from v0.3.1
+apiVersion: ossa/v0.3.3  # Changed from v0.3.3
 kind: Agent
 metadata:
   name: my-agent
@@ -58,7 +58,7 @@ spec:
 Add access tier configuration for privilege separation:
 
 ```yaml
-apiVersion: ossa/v0.3.2
+apiVersion: ossa/v0.3.3
 kind: Agent
 metadata:
   name: my-agent
@@ -67,7 +67,7 @@ metadata:
 spec:
   type: analyzer  # Agent type
   
-  # Access Tier Configuration (NEW in v0.3.2)
+  # Access Tier Configuration (NEW in v0.3.3)
   access:
     tier: tier_1_read
     permissions:
@@ -77,7 +77,7 @@ spec:
       - write_*
     audit_level: standard
   
-  # Separation of Duties (NEW in v0.3.2)
+  # Separation of Duties (NEW in v0.3.3)
   separation:
     role: analyzer
     conflicts_with:
@@ -219,13 +219,13 @@ separation:
 
 ## Validation
 
-### Validate v0.3.1 Manifest Against v0.3.2 Schema
+### Validate v0.3.3 Manifest Against v0.3.3 Schema
 
 ```bash
 # Using OSSA CLI
 ossa validate agent.ossa.yaml
 
-# Schema accepts both v0.3.1 and v0.3.2
+# Schema accepts both v0.3.3 and v0.3.3
 ```
 
 ### Validate Access Tier Configuration
@@ -242,17 +242,17 @@ ossa audit --tier-violations
 
 ## Breaking Changes
 
-**None** - v0.3.2 is fully backward compatible with v0.3.1.
+**None** - v0.3.3 is fully backward compatible with v0.3.3.
 
 ### Deprecations
 
-None in v0.3.2.
+None in v0.3.3.
 
 ---
 
 ## Examples
 
-See `spec/v0.3.2/examples/access-tiers/` for complete examples:
+See `spec/v0.3.3/examples/access-tiers/` for complete examples:
 
 - `security-scanner.ossa.yaml` - Tier 1 (Read Only)
 - `code-critic.ossa.yaml` - Tier 1 (Read Only)
@@ -266,11 +266,11 @@ See `spec/v0.3.2/examples/access-tiers/` for complete examples:
 
 ### Do I need to migrate immediately?
 
-**No**. v0.3.1 manifests continue to work. Migrate when you need access tier features.
+**No**. v0.3.3 manifests continue to work. Migrate when you need access tier features.
 
-### Can I mix v0.3.1 and v0.3.2 agents?
+### Can I mix v0.3.3 and v0.3.3 agents?
 
-**Yes**. Both versions validate against v0.3.2 schema.
+**Yes**. Both versions validate against v0.3.3 schema.
 
 ### What if I don't specify an access tier?
 
@@ -285,7 +285,7 @@ See [Access Tier Selection Guide](#access-tier-selection-guide) above.
 ## Related Documentation
 
 - [Access Tiers Specification](access_tiers.yaml)
-- [Schema Reference](ossa-0.3.2.schema.json)
+- [Schema Reference](ossa-0.3.3.schema.json)
 - [Examples](../examples/access-tiers/)
 
 ---

package/spec/v0.3.2/UNIFIED-SCHEMA.md

@@ -1,4 +1,4 @@
-# OSSA v0.3.1 - Unified Agent Schema
+# OSSA v0.3.3 - Unified Agent Schema
 
 ## The Rocketship 🚀
 
@@ -13,7 +13,7 @@ llm:
   model: claude-sonnet-4-20250514
 ```
 
-**After (v0.3.1):**
+**After (v0.3.3):**
 ```yaml
 llm:
   provider: ${LLM_PROVIDER:-anthropic}
@@ -35,7 +35,7 @@ llm:
 
 ### Compatibility Matrix
 
-| Feature | OSSA v0.2.x | Duo | A2A | v0.3.1 |
+| Feature | OSSA v0.2.x | Duo | A2A | v0.3.3 |
 |---------|-------------|-----|-----|--------|
 | Runtime-configurable models | ❌ | ❌ | ✅ | ✅ |
 | Execution profiles | ❌ | ❌ | ✅ | ✅ |

package/spec/v0.3.2/access_tiers.yaml

@@ -1,11 +1,11 @@
 # =============================================================================
-# OSSA v0.3.2 - Access Tiers & Separation of Duties Specification
+# OSSA v0.3.3 - Access Tiers & Separation of Duties Specification
 # =============================================================================
 # Defines privilege levels, role separations, and access controls for agents
 # Issue: https://gitlab.com/blueflyio/openstandardagents/-/issues/363
 # =============================================================================
 
-apiVersion: ossa/v0.3.2
+apiVersion: ossa/v0.3.3
 kind: AccessTierSpec
 version: "1.0.0"
 

package/spec/v0.3.2/adapters/drupal.md

@@ -100,7 +100,7 @@ ECA (Event-Condition-Action) rules map naturally to OSSA Tasks with event trigge
 
 ```yaml
 # ECA Model → OSSA Task
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Task
 metadata:
   name: eca-node-publish
@@ -156,7 +156,7 @@ runtime:
 
 ```yaml
 # Maestro Template → OSSA Workflow
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Workflow
 metadata:
   name: content-approval-workflow
@@ -226,7 +226,7 @@ runtime:
 
 ```yaml
 # FlowDrop Diagram → OSSA Workflow
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Workflow
 metadata:
   name: user-registration-flow
@@ -299,7 +299,7 @@ runtime:
 
 ```yaml
 # AI Agent Runner → OSSA Agent
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Agent
 metadata:
   name: content-assistant
@@ -348,7 +348,7 @@ runtime:
 
 ```yaml
 # Minikanban Card → OSSA Task
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Task
 metadata:
   name: kanban-task
@@ -523,7 +523,7 @@ spec:
 
 ## OSSA Compliance
 
-This adapter implements OSSA v0.3.1 specification:
+This adapter implements OSSA v0.3.3 specification:
 
 - ✅ Task execution with deterministic semantics
 - ✅ Workflow orchestration with step dependencies
@@ -535,7 +535,7 @@ This adapter implements OSSA v0.3.1 specification:
 
 ## Related
 
-- [OSSA Specification v0.3.1](../README.md)
+- [OSSA Specification v0.3.3](../README.md)
 - [Symfony Adapter](./symfony.md)
 - [Node.js Adapter](./nodejs.md)
 - [Capability Registry](../capability-schema.md)

package/spec/v0.3.2/adapters/symfony.md

@@ -350,7 +350,7 @@ ossa:
 
 ```yaml
 # config/ossa/tasks/send-email.yaml
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Task
 metadata:
   name: send-email-symfony
@@ -419,7 +419,7 @@ runtime:
 
 ```yaml
 # config/ossa/workflows/user-onboarding.yaml
-apiVersion: ossa/v0.3.1
+apiVersion: ossa/v0.3.3
 kind: Workflow
 metadata:
   name: user-onboarding-symfony
@@ -640,7 +640,7 @@ php bin/console messenger:failed:retry --all
 
 ## OSSA Compliance
 
-This adapter implements OSSA v0.3.1 specification:
+This adapter implements OSSA v0.3.3 specification:
 
 - ✅ Task execution with deterministic semantics
 - ✅ Workflow orchestration with step dependencies
@@ -653,7 +653,7 @@ This adapter implements OSSA v0.3.1 specification:
 
 ## Related
 
-- [OSSA Specification v0.3.1](../README.md)
+- [OSSA Specification v0.3.3](../README.md)
 - [Drupal Adapter](./drupal.md)
 - [Node.js Adapter](./nodejs.md)
 - [Capability Registry](../capability-schema.md)