@bluefly/openstandardagents 0.2.4

package/website/content/docs/openapi-extensions/root-extensions.md

@@ -0,0 +1,364 @@
+# Root-Level Extensions
+
+Extensions that can be added at the root level of an OpenAPI 3.1 specification.
+
+---
+
+## x-ossa-metadata
+
+Embeds comprehensive OSSA agent metadata in OpenAPI spec root. Provides governance, compliance, security, and observability metadata.
+
+### Location
+
+Root level of OpenAPI spec
+
+### Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | string | OSSA specification version (e.g., "0.2.2", "1.0.0") |
+| `compliance.level` | string | Compliance level: "basic" \| "standard" \| "advanced" \| "enterprise" |
+| `compliance.frameworks` | string[] | List of compliance frameworks (e.g., ["OSSA", "OpenAPI 3.1"]) |
+| `governance.approved` | boolean | Whether specification has been approved |
+| `governance.approvedBy` | string | Entity that approved (optional) |
+| `governance.approvalDate` | string | Date of approval in YYYY-MM-DD format (optional) |
+| `security.classification` | string | Security level: "public" \| "internal" \| "confidential" \| "restricted" |
+| `security.authentication` | string | Auth requirement: "required" \| "optional" \| "none" |
+| `security.encryption` | string | Encryption requirements (e.g., "tls1.3") |
+| `observability.tracing` | boolean | Enable distributed tracing |
+| `observability.metrics` | boolean | Enable metrics collection |
+| `observability.logging` | boolean | Enable structured logging |
+
+### Example (YAML)
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Kubernetes Troubleshooter Agent API
+  version: 1.0.0
+
+x-ossa-metadata:
+  version: 0.2.2
+  compliance:
+    level: enterprise
+    frameworks:
+      - OSSA
+      - OpenAPI 3.1
+      - RFC7807
+  governance:
+    approved: true
+    approvedBy: Platform Team
+    approvalDate: 2024-01-15
+  security:
+    classification: internal
+    authentication: required
+    encryption: tls1.3
+  observability:
+    tracing: true
+    metrics: true
+    logging: true
+
+paths:
+  # ... paths ...
+```
+
+### Example (JSON)
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Kubernetes Troubleshooter Agent API",
+    "version": "1.0.0"
+  },
+  "x-ossa-metadata": {
+    "version": "0.2.2",
+    "compliance": {
+      "level": "enterprise",
+      "frameworks": ["OSSA", "OpenAPI 3.1", "RFC7807"]
+    },
+    "governance": {
+      "approved": true,
+      "approvedBy": "Platform Team",
+      "approvalDate": "2024-01-15"
+    },
+    "security": {
+      "classification": "internal",
+      "authentication": "required",
+      "encryption": "tls1.3"
+    },
+    "observability": {
+      "tracing": true,
+      "metrics": true,
+      "logging": true
+    }
+  }
+}
+```
+
+### Use Cases
+
+- **Enterprise compliance** - Document governance and approval workflows
+- **Security audits** - Declare security classification and requirements
+- **Observability** - Enable tracing, metrics, and logging at spec level
+- **Multi-framework compliance** - Track compliance with multiple standards
+
+---
+
+## x-ossa
+
+Core OSSA compliance information with agent identification and validation metadata.
+
+### Location
+
+Root level or `info` section of OpenAPI spec
+
+### Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | string | OSSA specification version (e.g., "0.2.2") |
+| `agent.id` | string | Unique agent identifier (DNS subdomain format) |
+| `agent.type` | string | Agent type (see table below) |
+| `agent.compliance.standards` | string[] | Architectural standards (e.g., ["openapi-first", "dry", "solid"]) |
+| `agent.compliance.validated` | boolean | Whether agent has been validated |
+| `agent.compliance.validatedAt` | string | ISO 8601 timestamp of validation |
+
+### Agent Types
+
+| Type | Description |
+|------|-------------|
+| `orchestrator` | Coordinates multiple agents and workflows |
+| `worker` | Performs specific tasks and operations |
+| `specialist` | Specialized domain expertise |
+| `critic` | Reviews and validates agent outputs |
+| `judge` | Makes decisions and evaluates outcomes |
+| `monitor` | Observes and reports on system state |
+| `gateway` | Entry point for agent communication |
+| `governor` | Enforces policies and compliance |
+| `integrator` | Connects systems and protocols |
+| `voice` | Handles audio/speech interactions |
+
+### Example
+
+```yaml
+openapi: 3.1.0
+info:
+  title: My Agent API
+  version: 1.0.0
+
+x-ossa:
+  version: 0.2.2
+  agent:
+    id: k8s-troubleshooter
+    type: worker
+    compliance:
+      standards:
+        - openapi-first
+        - dry
+        - crud
+        - solid
+        - type-safe
+      validated: true
+      validatedAt: "2024-01-15T10:30:00Z"
+
+paths:
+  # ... paths ...
+```
+
+### Use Cases
+
+- **Agent registry** - Unique ID enables agent discovery and registration
+- **Type-based routing** - Route requests based on agent type
+- **Validation tracking** - Track when agent spec was last validated
+- **Standards compliance** - Document architectural standards followed
+
+---
+
+## x-agent
+
+Agent-specific capabilities, tools, environment, and rules configuration.
+
+### Location
+
+Root level or `info` section of OpenAPI spec
+
+### Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `capabilities` | string[] | List of agent capability names |
+| `tools` | string[] | List of tools/MCP servers available |
+| `environment` | object | Environment-specific configuration (key-value pairs) |
+| `rules` | string[] | List of rules or policies the agent follows |
+
+### Example
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Data Processing Agent API
+  version: 1.0.0
+
+x-agent:
+  capabilities:
+    - data-transformation
+    - csv-parsing
+    - json-validation
+  tools:
+    - postgres-mcp
+    - redis-mcp
+    - file-system-mcp
+  environment:
+    processingTimeout: 300
+    maxFileSize: "100MB"
+    enableCaching: true
+  rules:
+    - no-external-api-calls
+    - validate-all-inputs
+    - encrypt-sensitive-data
+
+paths:
+  # ... paths ...
+```
+
+### Use Cases
+
+- **Capability discovery** - List all capabilities agent provides
+- **Tool requirements** - Document MCP servers and tools needed
+- **Environment config** - Define environment-specific settings
+- **Policy enforcement** - Declare rules and constraints agent follows
+
+---
+
+## Parameter Extensions
+
+Standard parameters for agent-to-agent communication.
+
+### x-ossa-agent-id
+
+Standard header parameter for agent identification.
+
+**Location**: Parameter definition in `components.parameters` or operation-level `parameters`
+
+**Example**:
+
+```yaml
+components:
+  parameters:
+    X-Ossa-Agent-Id:
+      name: X-OSSA-Agent-ID
+      in: header
+      description: Unique identifier of the agent making the request
+      required: false
+      schema:
+        type: string
+        pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
+      example: "k8s-troubleshooter"
+
+paths:
+  /api/v1/capabilities:
+    get:
+      summary: Get agent capabilities
+      parameters:
+        - $ref: '#/components/parameters/X-Ossa-Agent-Id'
+```
+
+### x-ossa-version
+
+Standard header parameter for OSSA specification version.
+
+**Location**: Parameter definition in `components.parameters` or operation-level `parameters`
+
+**Example**:
+
+```yaml
+components:
+  parameters:
+    X-Ossa-Version:
+      name: X-OSSA-Version
+      in: header
+      description: OSSA specification version the agent supports
+      required: false
+      schema:
+        type: string
+        pattern: "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$"
+      example: "0.2.2"
+
+paths:
+  /api/v1/execute:
+    post:
+      summary: Execute agent capability
+      parameters:
+        - $ref: '#/components/parameters/X-Ossa-Version'
+```
+
+---
+
+## Schema Extensions
+
+### x-ossa-capability-schema
+
+Extends schema definition with capability metadata, linking OpenAPI schemas to OSSA capabilities.
+
+**Location**: Schema definition in `components.schemas`
+
+**Schema**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `capabilityName` | string | Name of the capability this schema represents |
+| `input` | boolean | Whether this is an input schema (default: false) |
+| `output` | boolean | Whether this is an output schema (default: false) |
+| `validation.required` | boolean | Whether validation is required (optional) |
+| `validation.strict` | boolean | Whether to use strict validation (optional) |
+
+**Example**:
+
+```yaml
+components:
+  schemas:
+    DataProcessingInput:
+      type: object
+      required: [csvData]
+      properties:
+        csvData:
+          type: string
+          description: CSV content to process
+      x-ossa-capability-schema:
+        capabilityName: data-transformation
+        input: true
+        validation:
+          required: true
+          strict: true
+
+    DataProcessingOutput:
+      type: object
+      properties:
+        jsonData:
+          type: array
+          items:
+            type: object
+      x-ossa-capability-schema:
+        capabilityName: data-transformation
+        output: true
+```
+
+---
+
+## Best Practices
+
+1. **Use x-ossa-metadata for enterprise deployments** - Document compliance, governance, and security
+2. **Always include x-ossa at root** - Provides core agent identification
+3. **Use x-agent for capability listing** - Makes agent discoverable
+4. **Define standard parameters once** - Reference X-OSSA-Agent-ID and X-OSSA-Version from components
+5. **Link schemas to capabilities** - Use x-ossa-capability-schema for validation
+
+---
+
+## References
+
+- [Operation-Level Extensions](operation-extensions)
+- [Examples & Patterns](examples)
+- [OSSA Specification v0.2.2](../Technical/Specification-Deep-Dive)
+- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0)

package/website/content/docs/pre-release/index.md

@@ -0,0 +1,175 @@
+# Pre-Release Specifications
+
+> **Warning**: These specifications are in development and may change before stable release. Do not use in production.
+
+## Development Versions
+
+OSSA follows semantic versioning. Development specs are marked with `-dev` suffix to indicate they are not yet stable.
+
+### v0.2.4-dev - Transport & Security
+
+**Status**: Development
+**Target Release**: February 2025
+**Milestone**: [v0.2.4 - Transport & Security](https://github.com/blueflyio/openstandardagents/milestones/12)
+
+#### New Features
+
+1. **Transport Metadata for Capabilities**
+   - Protocol support: `http`, `grpc`, `a2a`, `mcp`, `websocket`, `custom`
+   - Streaming modes: `none`, `request`, `response`, `bidirectional`
+   - Binding paths for endpoints
+
+2. **State/Memory Specification**
+   - Mode: `stateless`, `session`, `long_running`
+   - Storage types: `memory`, `vector-db`, `kv`, `rdbms`, `custom`
+   - Retention configuration
+
+3. **Security Scopes and Compliance Tags**
+   - OAuth2-style scopes per capability
+   - Compliance tags: `pii`, `hipaa`, `gdpr`, `fedramp`, `soc2`
+
+4. **Capability Versioning**
+   - Version field (major.minor)
+   - Deprecation flags and messages
+
+5. **Google ADK Extension**
+   - A2A protocol support
+   - Agent hierarchies
+   - MCP integration
+   - Streaming modalities
+
+#### Framework Alignment
+
+- Google Agent Development Kit (ADK)
+- OpenAI Agents SDK
+- Microsoft Agent Framework
+
+---
+
+### v0.2.5-dev - Multi-Agent Composition
+
+**Status**: Development
+**Target Release**: March 2025
+**Milestone**: [v0.2.5 - Multi-Agent Composition](https://github.com/blueflyio/openstandardagents/milestones/13)
+
+#### New Features
+
+1. **AgentGraph Resource Type**
+   ```yaml
+   apiVersion: ossa/v0.2.5
+   kind: AgentGraph  # New!
+   metadata:
+     name: customer-support-cluster
+   spec:
+     agents:
+       - ref: triage-agent
+         role: entry
+       - ref: resolver-agent
+         role: worker
+     edges:
+       - from: triage-agent
+         to: resolver-agent
+         condition: standard-issue
+     process: sequential
+   ```
+
+2. **Process Patterns**
+   - `sequential`: Agents execute one after another
+   - `parallel`: Agents execute simultaneously
+   - `hierarchical`: Manager delegates to workers
+   - `conditional`: Branching based on conditions
+   - `loop`: Iterative execution
+
+3. **Edge Routing**
+   - From/to agent references
+   - Condition expressions
+   - Priority ordering
+
+4. **Shared State**
+   - Schema definition
+   - Persistence options
+   - Checkpointing and recovery
+
+#### Framework Alignment
+
+- CrewAI (crews, manager agents)
+- MetaGPT (SOPs, role pipelines)
+- Microsoft AF (workflows)
+- Google ADK (agent graphs)
+- LangGraph (state machines)
+
+---
+
+## Using Development Specs
+
+### Installation
+
+Development specs are available in the repository:
+
+```bash
+# Clone the repository
+git clone https://github.com/blueflyio/openstandardagents.git
+cd openstandardagents
+
+# View development specs
+ls spec/v0.2.4-dev/
+ls spec/v0.2.5-dev/
+```
+
+### Validation
+
+```bash
+# Install CLI (if not already installed)
+npm install -g @bluefly/openstandardagents
+
+# Validate against development schema
+ossa validate your-agent.yaml --version 0.2.4-dev
+```
+
+### Examples
+
+Development examples are in the spec directories:
+
+- `spec/v0.2.5-dev/examples/customer-support-graph.ossa.yaml` - Sequential process
+- `spec/v0.2.5-dev/examples/research-team.ossa.yaml` - Hierarchical process
+- `spec/v0.2.5-dev/examples/parallel-processors.ossa.yaml` - Parallel process
+
+---
+
+## Providing Feedback
+
+We welcome feedback on development specifications:
+
+1. **GitHub Issues**: [Create an issue](https://github.com/blueflyio/openstandardagents/issues/new)
+2. **Discussions**: Comment on milestone issues
+3. **Pull Requests**: Submit improvements
+
+### v0.2.4 Issues
+- [#220 - Transport metadata](https://github.com/blueflyio/openstandardagents/issues/220)
+- [#221 - State/memory block](https://github.com/blueflyio/openstandardagents/issues/221)
+- [#222 - Security scopes](https://github.com/blueflyio/openstandardagents/issues/222)
+- [#223 - Capability versioning](https://github.com/blueflyio/openstandardagents/issues/223)
+- [#224 - Google ADK extension](https://github.com/blueflyio/openstandardagents/issues/224)
+- [#225 - MS AF adapter](https://github.com/blueflyio/openstandardagents/issues/225)
+
+### v0.2.5 Issues
+- [#211-212 - AgentGraph resource](https://github.com/blueflyio/openstandardagents/issues/211)
+- [#213 - Process patterns](https://github.com/blueflyio/openstandardagents/issues/213)
+- [#214 - Edge routing](https://github.com/blueflyio/openstandardagents/issues/214)
+- [#215 - Shared state](https://github.com/blueflyio/openstandardagents/issues/215)
+- [#216-218 - Adapter examples](https://github.com/blueflyio/openstandardagents/issues/216)
+- [#219 - Validation rules](https://github.com/blueflyio/openstandardagents/issues/219)
+
+---
+
+## Roadmap
+
+| Version | Focus | Status | Target |
+|---------|-------|--------|--------|
+| v0.2.3 | Documentation & Examples | **Stable** | Released |
+| v0.2.4 | Transport & Security | Development | Feb 2025 |
+| v0.2.5 | Multi-Agent Composition | Development | Mar 2025 |
+| v0.3.0 | Gamma Release | Planned | Apr 2025 |
+| v1.0.0 | Genesis Release | Planned | TBD |
+
+See [milestones](https://github.com/blueflyio/openstandardagents/milestones) for full details.

package/website/content/docs/quick-reference.md

@@ -0,0 +1,17 @@
+---
+title: "Quick Reference"
+---
+
+# Quick Reference
+
+- Root: `x-ossa-metadata`, `x-ossa`, `x-agent`
+- Operation: `x-ossa-capability`, `x-ossa-autonomy`, `x-ossa-constraints`, `x-ossa-tools`, `x-ossa-llm`
+- Parameters: `x-ossa-agent-id`, `x-ossa-version`
+- Schemas: `x-ossa-capability-schema`
+
+**Validation**:
+```bash
+ossa validate examples/openapi-extensions/worker-agent-api.openapi.yml --openapi --verbose
+```
+
+**Links**: [OpenAPI-Extensions](./OpenAPI-Extensions) · [Examples](./Examples)