@bluefly/openstandardagents 0.3.2 → 0.3.5

package/spec/v0.2.9/agent.md

@@ -1,1946 +0,0 @@
-# OSSA Agent Manifest Specification
-
-**Version**: 0.2.9
-**Status**: Draft
-**Last Updated**: 2025-12-04
-
-This document is the authoritative reference for OSSA agent manifests. All OSSA-compliant agents MUST conform to this specification.
-
----
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Manifest Structure](#manifest-structure)
-3. [Metadata Section](#metadata-section)
-4. [Spec Section](#spec-section)
-5. [Agent Types](#agent-types)
-6. [Capabilities](#capabilities)
-7. [Runtime Configuration](#runtime-configuration)
-8. [Triggers](#triggers)
-9. [Policies](#policies)
-10. [Examples](#examples)
-11. [Best Practices](#best-practices)
-12. [Anti-Patterns](#anti-patterns)
-13. [Migration Guide](#migration-guide)
-
----
-
-## Overview
-
-### What is an OSSA Agent?
-
-An OSSA agent is a declarative, framework-agnostic specification for AI agents. It defines:
-
-- **Identity**: Who the agent is (name, version, labels)
-- **Behavior**: What the agent does (role, reasoning strategy)
-- **Capabilities**: What tools and integrations the agent can use
-- **Runtime**: How the agent executes (LLM, state, observability)
-- **Policies**: Guardrails for safety, security, and reliability
-
-### Manifest Purpose and Lifecycle
-
-The agent manifest serves as:
-
-1. **Contract**: Defines agent behavior for runtime execution
-2. **Documentation**: Human-readable specification of agent purpose
-3. **Portability**: Enables migration between frameworks (LangChain, CrewAI, AutoGen, etc.)
-4. **Compliance**: Enforces regulatory requirements (FedRAMP, HIPAA, SOC2)
-5. **Version Control**: Tracks agent evolution with semver
-
-**Lifecycle**:
-```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-│ Author   │──▶│ Validate │──▶│ Deploy   │──▶│ Execute  │
-│ manifest │   │ schema   │   │ runtime  │   │ agent    │
-└──────────┘   └──────────┘   └──────────┘   └──────────┘
-```
-
-### Relationship to JSON Schema
-
-Every OSSA manifest MUST validate against the canonical JSON Schema:
-- **Schema URL**: `https://openstandardagents.org/schemas/v0.2.9/agent.json`
-- **Validation**: Required before deployment
-- **Extensions**: Framework-specific extensions are schema-validated
-
----
-
-## Manifest Structure
-
-All OSSA manifests follow Kubernetes-style resource format:
-
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: agent-identifier
-  version: 1.0.0
-spec:
-  # Agent specification
-```
-
-### Required Fields
-
-| Field | Type | Description | Example |
-|-------|------|-------------|---------|
-| `apiVersion` | string | OSSA API version | `ossa/v0.2.9` |
-| `kind` | string | Resource type | `Agent` |
-| `metadata` | object | Agent metadata | See [Metadata](#metadata-section) |
-| `spec` | object | Agent specification | See [Spec](#spec-section) |
-
-### Optional Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `extensions` | object | Framework-specific extensions |
-
----
-
-## Metadata Section
-
-The `metadata` section provides agent identity and classification.
-
-### Required Metadata
-
-#### `name`
-
-**Type**: `string`
-**Pattern**: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
-**Max Length**: 253 characters
-
-**Rules**:
-- Lowercase alphanumeric characters only
-- Hyphens allowed (not at start/end)
-- Kubernetes DNS-1123 subdomain format
-- Must be globally unique within namespace
-
-**Examples**:
-```yaml
-# Valid
-metadata:
-  name: security-scanner
-  name: code-reviewer-v2
-  name: doc-generator-123
-
-# Invalid
-metadata:
-  name: Security_Scanner  # No uppercase or underscores
-  name: -agent-name       # Cannot start with hyphen
-  name: agent.name        # No dots allowed
-```
-
-### Optional Metadata
-
-#### `version`
-
-**Type**: `string`
-**Pattern**: Semantic Versioning 2.0.0
-**Format**: `MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`
-
-**Rules**:
-- MUST follow semver 2.0.0 specification
-- Breaking changes MUST increment MAJOR
-- New features MUST increment MINOR
-- Bug fixes MUST increment PATCH
-
-**Examples**:
-```yaml
-metadata:
-  version: 1.0.0
-  version: 2.1.3-beta.1
-  version: 1.0.0+build.2024.12.04
-```
-
-#### `description`
-
-**Type**: `string`
-**Max Length**: 2000 characters
-
-Human-readable description of agent purpose and capabilities.
-
-**Example**:
-```yaml
-metadata:
-  description: |
-    Security vulnerability scanner for Kubernetes clusters.
-    Analyzes pod configurations, network policies, and RBAC
-    to identify security risks and compliance violations.
-```
-
-#### `labels`
-
-**Type**: `object<string, string>`
-**Value Max Length**: 63 characters
-
-Key-value pairs for organization and filtering. Used by runtime selectors.
-
-**Example**:
-```yaml
-metadata:
-  labels:
-    domain: security
-    team: platform
-    environment: production
-    compliance: fedramp
-```
-
-#### `annotations`
-
-**Type**: `object<string, string>`
-
-Arbitrary metadata for tooling. NOT used for filtering.
-
-**Example**:
-```yaml
-metadata:
-  annotations:
-    ossa.io/author: platform-team@example.com
-    ossa.io/docs: https://docs.example.com/agents/security-scanner
-    ossa.io/issue-tracker: https://github.com/org/repo/issues
-    buildkit.io/cost-center: security-ops
-```
-
----
-
-## Spec Section
-
-The `spec` section defines agent behavior, capabilities, and runtime configuration.
-
-### Required Spec Fields
-
-#### `role`
-
-**Type**: `string`
-**Min Length**: 1
-
-The agent's system prompt describing behavior and capabilities.
-
-**Example**:
-```yaml
-spec:
-  role: |
-    You are a security expert specializing in Kubernetes security.
-    Your role is to analyze cluster configurations and identify
-    security vulnerabilities based on CIS Kubernetes Benchmarks.
-
-    Provide actionable recommendations with remediation steps.
-    Prioritize findings by severity (Critical, High, Medium, Low).
-```
-
-**Best Practices**:
-- Be specific about domain expertise
-- Define output format expectations
-- Specify tone and communication style
-- Include constraints and limitations
-
-### Optional Spec Fields
-
-#### `taxonomy`
-
-**Type**: `object`
-
-Hierarchical classification for agent discovery.
-
-```yaml
-spec:
-  taxonomy:
-    domain: infrastructure      # Primary domain
-    subdomain: kubernetes       # Secondary classification
-    capability: troubleshooting # Specific function
-```
-
-**Common Domains**:
-- `infrastructure`: Cloud, Kubernetes, networking
-- `security`: Vulnerability scanning, compliance
-- `development`: Code review, testing
-- `documentation`: Generation, maintenance
-- `compliance`: Auditing, reporting
-
-#### `llm`
-
-**Type**: `object`
-
-LLM provider and configuration. See [Runtime Configuration](#runtime-configuration).
-
-#### `tools`
-
-**Type**: `array<Tool>`
-
-Available tools and integrations. See [Capabilities](#capabilities).
-
-#### `autonomy`
-
-**Type**: `object`
-
-Autonomous execution behavior (requires approval, escalation, etc.).
-
-#### `constraints`
-
-**Type**: `object`
-
-Resource limits and execution constraints.
-
-#### `observability`
-
-**Type**: `object`
-
-Logging, tracing, and metrics configuration.
-
-#### `state`
-
-**Type**: `object`
-
-State management (persistent, ephemeral, versioning).
-
-#### `security`
-
-**Type**: `object`
-
-Security policies (authentication, authorization, secrets).
-
-#### `reliability`
-
-**Type**: `object`
-
-Retry policies, circuit breakers, timeouts.
-
-#### `collaboration`
-
-**Type**: `object`
-
-Multi-agent communication and delegation.
-
-#### `safety`
-
-**Type**: `object`
-
-Content filtering, PII redaction, guardrails.
-
-#### `deployment`
-
-**Type**: `object`
-
-Runtime environment requirements.
-
-#### `reasoning`
-
-**Type**: `object`
-
-Reasoning strategy (ReAct, Chain-of-Thought, Tree-of-Thought).
-
-#### `prompts`
-
-**Type**: `object`
-
-Versioned prompt templates.
-
-#### `knowledge_graph`
-
-**Type**: `object`
-
-Knowledge graph integration.
-
-#### `identity`
-
-**Type**: `object`
-
-Identity management (session IDs, instance IDs, trace context).
-
----
-
-## Agent Types
-
-OSSA supports three agent types based on autonomy and collaboration patterns.
-
-### Worker Agent
-
-**Purpose**: Executes specific tasks with minimal autonomy.
-
-**Characteristics**:
-- Single-purpose, focused capability
-- Requires human approval for actions
-- Stateless or minimal state
-- Low complexity
-
-**Use Cases**:
-- Code formatting
-- Data validation
-- Simple transformations
-- Query execution
-
-**Example**:
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: code-formatter
-  labels:
-    type: worker
-spec:
-  taxonomy:
-    domain: development
-    subdomain: code-quality
-    capability: formatting
-  role: Format code according to project style guides
-  autonomy:
-    approval_required: false  # Safe, deterministic operation
-    max_turns: 1
-```
-
-### Orchestrator Agent
-
-**Purpose**: Coordinates multiple agents and complex workflows.
-
-**Characteristics**:
-- Multi-agent delegation
-- Workflow orchestration
-- State management across agents
-- Higher autonomy
-
-**Use Cases**:
-- Build pipelines
-- Security audits
-- Complex troubleshooting
-- Multi-step deployments
-
-**Example**:
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: security-orchestrator
-  labels:
-    type: orchestrator
-spec:
-  taxonomy:
-    domain: security
-    subdomain: orchestration
-    capability: audit
-  role: Orchestrate comprehensive security audits
-  collaboration:
-    delegation:
-      enabled: true
-      max_depth: 3
-      agents:
-        - vulnerability-scanner
-        - compliance-checker
-        - remediation-planner
-```
-
-### Hybrid Agent
-
-**Purpose**: Balances autonomy with human oversight.
-
-**Characteristics**:
-- Conditional autonomy
-- Escalation workflows
-- Approval gates for critical actions
-- Context-aware decision making
-
-**Use Cases**:
-- Interactive troubleshooting
-- Assisted deployments
-- Code review with recommendations
-- Compliance remediation
-
-**Example**:
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: deployment-assistant
-  labels:
-    type: hybrid
-spec:
-  taxonomy:
-    domain: infrastructure
-    subdomain: deployment
-    capability: assisted-deployment
-  role: Assist with production deployments
-  autonomy:
-    approval_required: true  # Require approval for prod changes
-    approval_gates:
-      - action: deploy
-        approvers:
-          - role:platform-admin
-      - action: database_migration
-        approvers:
-          - role:dba
-```
-
----
-
-## Capabilities
-
-Capabilities define tools and integrations available to the agent.
-
-### Tool Types
-
-#### MCP (Model Context Protocol)
-
-Connect to MCP servers for tool discovery and execution.
-
-```yaml
-spec:
-  tools:
-    - type: mcp
-      server: filesystem
-      namespace: default
-      capabilities:
-        - name: read_file
-          version: "1.0"
-        - name: write_file
-          version: "1.0"
-      auth:
-        type: none
-```
-
-#### Kubernetes
-
-Interact with Kubernetes API.
-
-```yaml
-spec:
-  tools:
-    - type: kubernetes
-      namespace: production
-      capabilities:
-        - name: get_pods
-        - name: describe_pod
-        - name: get_logs
-      auth:
-        type: bearer
-        credentials: ${KUBE_TOKEN}  # Reference, not actual secret
-```
-
-#### HTTP
-
-Call HTTP APIs.
-
-```yaml
-spec:
-  tools:
-    - type: http
-      name: github-api
-      endpoint: https://api.github.com
-      capabilities:
-        - name: create_issue
-          version: "2022-11-28"
-      auth:
-        type: bearer
-        credentials: ${GITHUB_TOKEN}
-      circuit_breaker:
-        enabled: true
-        failure_threshold: 5
-        timeout_seconds: 60
-```
-
-#### gRPC
-
-Call gRPC services.
-
-```yaml
-spec:
-  tools:
-    - type: grpc
-      name: audit-service
-      endpoint: audit.example.com:443
-      capabilities:
-        - name: log_event
-      auth:
-        type: mtls
-        credentials: ${MTLS_CERT}
-      transport:
-        protocol: grpc
-        tls:
-          enabled: true
-```
-
-#### Function
-
-Invoke serverless functions.
-
-```yaml
-spec:
-  tools:
-    - type: function
-      name: image-processor
-      capabilities:
-        - name: resize_image
-        - name: convert_format
-      config:
-        runtime: nodejs20
-        memory_mb: 512
-        timeout_seconds: 30
-```
-
-#### A2A (Agent-to-Agent)
-
-Communicate with other OSSA agents.
-
-```yaml
-spec:
-  tools:
-    - type: a2a
-      name: specialist-agent
-      capabilities:
-        - name: analyze_security
-      transport:
-        protocol: http
-        endpoint: http://specialist-agent.default.svc.cluster.local:8080
-```
-
-### Capability Configuration
-
-Each capability can define:
-
-#### Input/Output Schemas
-
-```yaml
-capabilities:
-  - name: create_ticket
-    version: "1.0"
-    input_schema:
-      type: object
-      required: [title, description]
-      properties:
-        title:
-          type: string
-        description:
-          type: string
-        priority:
-          type: string
-          enum: [low, medium, high, critical]
-    output_schema:
-      type: object
-      properties:
-        ticket_id:
-          type: string
-        url:
-          type: string
-```
-
-#### Retry Policy
-
-```yaml
-capabilities:
-  - name: external_api_call
-    retry_policy:
-      max_attempts: 3
-      backoff_strategy: exponential
-      initial_delay_ms: 1000
-      max_delay_ms: 30000
-      retryable_errors:
-        - RATE_LIMIT_EXCEEDED
-        - SERVICE_UNAVAILABLE
-```
-
-#### Error Handling
-
-```yaml
-capabilities:
-  - name: primary_service
-    error_handling:
-      fallback_capability: backup_service
-      on_error: fallback
-      error_mapping:
-        CONNECTION_REFUSED: SERVICE_UNAVAILABLE
-        TIMEOUT: DEADLINE_EXCEEDED
-```
-
-#### Caching
-
-```yaml
-capabilities:
-  - name: expensive_query
-    caching:
-      enabled: true
-      ttl_seconds: 3600
-      cache_key_fields:
-        - query_id
-        - parameters
-      invalidation_strategy: ttl
-```
-
-#### Timeouts
-
-```yaml
-capabilities:
-  - name: long_running_task
-    timeout:
-      execution_seconds: 300
-      connection_seconds: 10
-```
-
-#### Compliance Tagging
-
-```yaml
-capabilities:
-  - name: process_health_data
-    compliance_tags:
-      - pii
-      - phi
-      - hipaa
-      - gdpr
-```
-
----
-
-## Runtime Configuration
-
-### LLM Configuration
-
-```yaml
-spec:
-  llm:
-    provider: anthropic
-    model: claude-3-sonnet-20240229
-    temperature: 0.7
-    maxTokens: 4096
-    topP: 0.9
-
-    # Fallback models
-    fallback_models:
-      - provider: openai
-        model: gpt-4-turbo-preview
-      - provider: google
-        model: gemini-pro
-
-    # Retry configuration
-    retry_config:
-      max_attempts: 3
-      backoff_strategy: exponential
-
-    # Cost tracking
-    cost_tracking:
-      enabled: true
-      budget_alert_threshold: 100.00
-      cost_allocation_tags:
-        team: security
-        project: cluster-audit
-```
-
-### State Management
-
-```yaml
-spec:
-  state:
-    persistence:
-      enabled: true
-      backend: redis
-      encryption:
-        enabled: true
-        algorithm: AES-256-GCM
-
-    versioning:
-      enabled: true
-      max_versions: 10
-
-    ttl_seconds: 86400  # 24 hours
-
-    cleanup:
-      strategy: age_based
-      max_age_days: 30
-```
-
-### Observability
-
-```yaml
-spec:
-  observability:
-    logging:
-      level: info
-      format: json
-      destinations:
-        - type: stdout
-        - type: loki
-          endpoint: http://loki:3100
-
-    tracing:
-      enabled: true
-      exporter: otlp
-      endpoint: http://tempo:4317
-      sampling_rate: 1.0
-      pii_redaction: true
-
-    metrics:
-      enabled: true
-      exporter: prometheus
-      port: 9090
-      custom_metrics:
-        - name: agent_task_duration_seconds
-          type: histogram
-        - name: agent_errors_total
-          type: counter
-```
-
----
-
-## Triggers
-
-Define when the agent should execute.
-
-### Event Trigger
-
-```yaml
-spec:
-  triggers:
-    - type: event
-      source: kubernetes
-      filters:
-        namespace: production
-        resource: pod
-        event_type: created
-      conditions:
-        - field: metadata.labels.app
-          operator: equals
-          value: web-server
-```
-
-### Schedule Trigger
-
-```yaml
-spec:
-  triggers:
-    - type: schedule
-      cron: "0 */6 * * *"  # Every 6 hours
-      timezone: America/New_York
-      jitter_seconds: 300  # Random delay up to 5 minutes
-```
-
-### Manual Trigger
-
-```yaml
-spec:
-  triggers:
-    - type: manual
-      approval_required: true
-      approvers:
-        - user:admin@example.com
-        - role:platform-lead
-```
-
-### Webhook Trigger
-
-```yaml
-spec:
-  triggers:
-    - type: webhook
-      endpoint: /api/v1/agents/security-scanner/trigger
-      auth:
-        type: bearer
-        credentials: ${WEBHOOK_SECRET}
-      payload_schema:
-        type: object
-        required: [target_cluster]
-        properties:
-          target_cluster:
-            type: string
-```
-
----
-
-## Policies
-
-Policies define guardrails for agent execution.
-
-### Rate Limiting
-
-```yaml
-spec:
-  reliability:
-    rate_limit:
-      enabled: true
-      max_requests_per_minute: 60
-      max_concurrent_executions: 5
-      burst_size: 10
-```
-
-### Circuit Breaker
-
-```yaml
-spec:
-  reliability:
-    circuit_breaker:
-      enabled: true
-      failure_threshold: 5
-      success_threshold: 2
-      timeout_seconds: 60
-      half_open_max_requests: 3
-```
-
-### Retry Policy
-
-```yaml
-spec:
-  reliability:
-    retry:
-      max_attempts: 3
-      backoff_strategy: exponential
-      initial_delay_ms: 1000
-      max_delay_ms: 30000
-      jitter: true
-```
-
-### Escalation
-
-```yaml
-spec:
-  autonomy:
-    escalation:
-      enabled: true
-      triggers:
-        - condition: error_rate > 0.1
-          action: notify
-          recipients:
-            - pagerduty:on-call
-        - condition: consecutive_failures > 3
-          action: disable
-          notification:
-            - email:ops-team@example.com
-```
-
-### Resource Limits
-
-```yaml
-spec:
-  constraints:
-    execution:
-      max_duration_seconds: 600
-      max_memory_mb: 2048
-      max_cpu_millicores: 1000
-
-    output:
-      max_tokens: 4096
-      max_tool_calls_per_turn: 10
-      max_turns: 20
-```
-
----
-
-## Examples
-
-### Example 1: Minimal Worker Agent
-
-Simplest possible OSSA agent for code formatting.
-
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: code-formatter
-  version: 1.0.0
-  description: Formats Python code using Black
-spec:
-  role: Format Python code according to PEP 8 using Black formatter
-  llm:
-    provider: openai
-    model: gpt-4-turbo-preview
-    temperature: 0
-  tools:
-    - type: function
-      name: black-formatter
-      capabilities:
-        - name: format_code
-  autonomy:
-    approval_required: false
-    max_turns: 1
-```
-
-### Example 2: Production Orchestrator
-
-Enterprise-grade security orchestrator with full observability.
-
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: security-orchestrator
-  version: 2.1.0
-  description: |
-    Comprehensive security audit orchestrator for Kubernetes clusters.
-    Coordinates vulnerability scanning, compliance checking, and remediation.
-  labels:
-    domain: security
-    team: platform-security
-    environment: production
-    compliance: fedramp
-  annotations:
-    ossa.io/author: security-team@example.com
-    ossa.io/docs: https://docs.example.com/agents/security-orchestrator
-    cost-center: security-ops
-
-spec:
-  taxonomy:
-    domain: security
-    subdomain: orchestration
-    capability: comprehensive-audit
-
-  role: |
-    You are a security orchestration expert for Kubernetes environments.
-
-    Your responsibilities:
-    1. Coordinate vulnerability scanning across all namespaces
-    2. Verify compliance with CIS Kubernetes Benchmarks
-    3. Identify misconfigurations and security risks
-    4. Generate prioritized remediation plans
-
-    Output Format:
-    - Executive summary (max 3 paragraphs)
-    - Critical findings with immediate action items
-    - Detailed findings by severity
-    - Remediation roadmap with timeline
-
-    Escalate immediately if:
-    - Critical vulnerabilities with public exploits
-    - Compliance violations affecting certifications
-    - Active security incidents detected
-
-  llm:
-    provider: anthropic
-    model: claude-3-opus-20240229
-    temperature: 0.3
-    maxTokens: 8192
-    fallback_models:
-      - provider: openai
-        model: gpt-4-turbo-preview
-    retry_config:
-      max_attempts: 3
-      backoff_strategy: exponential
-    cost_tracking:
-      enabled: true
-      budget_alert_threshold: 500.00
-      cost_allocation_tags:
-        team: security
-        project: k8s-audit
-
-  tools:
-    - type: kubernetes
-      namespace: "*"
-      capabilities:
-        - name: list_pods
-        - name: get_pod_security_policies
-        - name: list_network_policies
-        - name: get_rbac_roles
-      auth:
-        type: bearer
-        credentials: ${KUBE_SA_TOKEN}
-      circuit_breaker:
-        enabled: true
-        failure_threshold: 5
-        timeout_seconds: 60
-
-    - type: a2a
-      name: vulnerability-scanner
-      capabilities:
-        - name: scan_cluster
-      transport:
-        protocol: grpc
-        endpoint: vuln-scanner.security.svc.cluster.local:8080
-
-    - type: a2a
-      name: compliance-checker
-      capabilities:
-        - name: check_cis_benchmark
-      transport:
-        protocol: grpc
-        endpoint: compliance.security.svc.cluster.local:8080
-
-    - type: http
-      name: remediation-tracker
-      endpoint: https://api.remediation.example.com
-      capabilities:
-        - name: create_ticket
-        - name: assign_owner
-      auth:
-        type: bearer
-        credentials: ${REMEDIATION_API_KEY}
-
-  collaboration:
-    delegation:
-      enabled: true
-      max_depth: 3
-      agents:
-        - vulnerability-scanner
-        - compliance-checker
-        - remediation-planner
-
-  autonomy:
-    approval_required: false  # Audit is read-only
-    escalation:
-      enabled: true
-      triggers:
-        - condition: critical_findings > 0
-          action: notify
-          recipients:
-            - pagerduty:security-on-call
-        - condition: compliance_violations > 10
-          action: notify
-          recipients:
-            - email:security-team@example.com
-
-  observability:
-    logging:
-      level: info
-      format: json
-      destinations:
-        - type: loki
-          endpoint: http://loki.monitoring:3100
-    tracing:
-      enabled: true
-      exporter: otlp
-      endpoint: http://tempo.monitoring:4317
-      sampling_rate: 1.0
-      pii_redaction: true
-    metrics:
-      enabled: true
-      exporter: prometheus
-      port: 9090
-
-  state:
-    persistence:
-      enabled: true
-      backend: redis
-      encryption:
-        enabled: true
-        algorithm: AES-256-GCM
-    versioning:
-      enabled: true
-      max_versions: 30
-    ttl_seconds: 604800  # 7 days
-
-  security:
-    authentication:
-      required: true
-      methods:
-        - mtls
-        - oauth2
-    authorization:
-      rbac:
-        enabled: true
-        roles:
-          - security-auditor
-    secrets:
-      provider: vault
-      path: /secret/agents/security-orchestrator
-
-  reliability:
-    retry:
-      max_attempts: 3
-      backoff_strategy: exponential
-      initial_delay_ms: 1000
-      max_delay_ms: 30000
-    circuit_breaker:
-      enabled: true
-      failure_threshold: 5
-      timeout_seconds: 120
-    rate_limit:
-      max_requests_per_minute: 30
-      max_concurrent_executions: 3
-
-  constraints:
-    execution:
-      max_duration_seconds: 1800  # 30 minutes
-      max_memory_mb: 4096
-      max_cpu_millicores: 2000
-    output:
-      max_tokens: 8192
-      max_tool_calls_per_turn: 50
-      max_turns: 30
-
-  triggers:
-    - type: schedule
-      cron: "0 2 * * *"  # Daily at 2 AM
-      timezone: UTC
-    - type: webhook
-      endpoint: /api/v1/agents/security-orchestrator/trigger
-      auth:
-        type: bearer
-        credentials: ${WEBHOOK_SECRET}
-
-  reasoning:
-    strategy: react
-    options:
-      max_iterations: 10
-      reflection_enabled: true
-
-  safety:
-    content_filtering:
-      enabled: true
-      blocklist:
-        - credentials
-        - api_keys
-    pii_detection:
-      enabled: true
-      redact: true
-```
-
-### Example 3: Security-Hardened Agent
-
-Agent with comprehensive security controls for regulated environments.
-
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: hipaa-compliant-agent
-  version: 1.0.0
-  labels:
-    compliance: hipaa
-    environment: production
-spec:
-  role: Process healthcare data in HIPAA-compliant manner
-
-  llm:
-    provider: anthropic
-    model: claude-3-sonnet-20240229
-
-  tools:
-    - type: http
-      name: fhir-api
-      endpoint: https://fhir.example.com
-      capabilities:
-        - name: read_patient
-          compliance_tags:
-            - phi
-            - hipaa
-      auth:
-        type: oauth2
-        credentials: ${FHIR_OAUTH_TOKEN}
-        scopes:
-          - patient.read
-      transport:
-        tls:
-          enabled: true
-          min_version: "1.3"
-          verify_cert: true
-
-  security:
-    authentication:
-      required: true
-      methods:
-        - mtls
-    authorization:
-      rbac:
-        enabled: true
-        roles:
-          - healthcare-provider
-    secrets:
-      provider: vault
-      path: /secret/hipaa/agents
-    audit:
-      enabled: true
-      log_all_requests: true
-      retention_days: 2555  # 7 years
-
-  state:
-    persistence:
-      enabled: true
-      backend: postgres
-      encryption:
-        enabled: true
-        algorithm: AES-256-GCM
-        key_management: aws-kms
-
-  observability:
-    logging:
-      level: info
-      pii_redaction: true
-    tracing:
-      enabled: true
-      pii_redaction: true
-
-  safety:
-    content_filtering:
-      enabled: true
-    pii_detection:
-      enabled: true
-      redact: true
-      types:
-        - ssn
-        - credit_card
-        - phone_number
-
-  compliance:
-    profiles:
-      - hipaa
-    audit:
-      enabled: true
-      retention_days: 2555
-```
-
-### Example 4: Multi-Model Agent with Fallbacks
-
-Agent using multiple LLMs with intelligent fallback.
-
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: resilient-agent
-  version: 1.0.0
-spec:
-  role: High-availability agent with multi-model fallback
-
-  llm:
-    # Primary model
-    provider: anthropic
-    model: claude-3-opus-20240229
-    temperature: 0.7
-    maxTokens: 4096
-
-    # Fallback chain
-    fallback_models:
-      - provider: openai
-        model: gpt-4-turbo-preview
-      - provider: google
-        model: gemini-pro
-      - provider: anthropic
-        model: claude-3-sonnet-20240229
-
-    # Aggressive retry
-    retry_config:
-      max_attempts: 5
-      backoff_strategy: exponential
-
-  reliability:
-    circuit_breaker:
-      enabled: true
-      failure_threshold: 3
-      success_threshold: 2
-      timeout_seconds: 60
-    retry:
-      max_attempts: 3
-      backoff_strategy: exponential
-      jitter: true
-
-  observability:
-    metrics:
-      enabled: true
-      custom_metrics:
-        - name: model_fallback_total
-          type: counter
-          labels:
-            - from_model
-            - to_model
-        - name: model_latency_seconds
-          type: histogram
-          labels:
-            - model
-```
-
-### Example 5: Agent with Compliance Profile
-
-Agent configured for FedRAMP Moderate compliance.
-
-```yaml
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: fedramp-agent
-  version: 1.0.0
-  labels:
-    compliance: fedramp-moderate
-    environment: gov-cloud
-  annotations:
-    fedramp.io/authorization-date: "2024-12-01"
-    fedramp.io/package-id: F24xxxxx
-
-spec:
-  role: FedRAMP Moderate compliant agent for federal agencies
-
-  llm:
-    provider: azure
-    model: gpt-4-turbo-usgov
-    cost_tracking:
-      enabled: true
-      cost_allocation_tags:
-        agency: dod
-        program: modernization
-
-  state:
-    persistence:
-      enabled: true
-      backend: postgres
-      encryption:
-        enabled: true
-        algorithm: AES-256-GCM
-        key_management: FIPS-140-2
-      storage:
-        allowed_regions:
-          - us-gov-west-1
-          - us-gov-east-1
-        data_residency: US
-
-  security:
-    authentication:
-      required: true
-      methods:
-        - mtls
-        - piv  # PIV/CAC cards
-    authorization:
-      rbac:
-        enabled: true
-    secrets:
-      provider: aws-secrets-manager
-      encryption: FIPS-140-2
-
-  observability:
-    logging:
-      retention_days: 2555  # 7 years
-      immutable: true
-      pii_redaction: true
-    tracing:
-      enabled: true
-      pii_redaction: true
-    audit:
-      enabled: true
-      log_all_requests: true
-      retention_days: 2555
-
-  compliance:
-    profiles:
-      - fedramp-moderate
-    controls:
-      - id: AC-2
-        description: Account Management
-        status: compliant
-      - id: AU-2
-        description: Audit Events
-        status: compliant
-      - id: SC-13
-        description: Cryptographic Protection
-        status: compliant
-
-  tools:
-    - type: http
-      name: government-api
-      endpoint: https://api.example.gov
-      auth:
-        type: mtls
-        credentials: ${MTLS_CERT}
-      transport:
-        tls:
-          enabled: true
-          min_version: "1.2"
-          cipher_suites:
-            - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
-      compliance_tags:
-        - fedramp
-        - fips-140-2
-```
-
----
-
-## Best Practices
-
-### Naming Conventions
-
-**DO**:
-- Use descriptive, purpose-driven names: `security-scanner`, `doc-generator`
-- Follow Kubernetes naming (lowercase, hyphens)
-- Include version suffix for major versions: `agent-v2`, `scanner-v3`
-- Use domain prefixes: `sec-scanner`, `dev-reviewer`
-
-**DON'T**:
-- Use generic names: `agent1`, `my-agent`
-- Use uppercase or underscores: `Security_Agent`
-- Include framework names: `langchain-agent`
-- Use dots or special characters: `agent.production`
-
-### Version Management
-
-**DO**:
-- Start at `1.0.0` for production releases
-- Use `0.x.y` for pre-production
-- Increment MAJOR for breaking changes
-- Increment MINOR for new features
-- Increment PATCH for bug fixes
-- Use pre-release tags: `1.0.0-beta.1`, `2.0.0-rc.2`
-
-**DON'T**:
-- Skip versions
-- Reuse version numbers
-- Use arbitrary versioning schemes
-
-### Capability Selection
-
-**DO**:
-- Grant minimum required capabilities (principle of least privilege)
-- Use capability versioning: `read_file:1.0`
-- Document why each capability is needed (in annotations)
-- Group related capabilities under single tool
-- Use compliance tags for sensitive capabilities
-
-**DON'T**:
-- Grant wildcard/admin capabilities unless absolutely required
-- Use deprecated capabilities
-- Mix unrelated capabilities in one tool
-
-### Error Handling Patterns
-
-**DO**:
-- Define retry policies for transient failures
-- Use circuit breakers for external dependencies
-- Implement fallback capabilities
-- Log errors with structured metadata
-- Escalate critical errors to humans
-
-**DON'T**:
-- Retry indefinitely
-- Ignore errors silently
-- Retry non-idempotent operations without safeguards
-- Expose error details to end users
-
-### Observability
-
-**DO**:
-- Enable tracing for all production agents
-- Redact PII in logs and traces
-- Use structured logging (JSON)
-- Define custom metrics for business KPIs
-- Set retention policies based on compliance requirements
-
-**DON'T**:
-- Log secrets or credentials
-- Disable observability in production
-- Use plain text logging for sensitive data
-
-### State Management
-
-**DO**:
-- Enable encryption for persistent state
-- Version state schemas
-- Set TTL for ephemeral state
-- Use cleanup policies to prevent unbounded growth
-- Back up critical state
-
-**DON'T**:
-- Store secrets in state
-- Use unencrypted state for sensitive data
-- Keep state indefinitely without TTL
-
-### Security
-
-**DO**:
-- Require authentication for all production agents
-- Use RBAC for authorization
-- Store secrets in dedicated secret managers (Vault, AWS Secrets Manager)
-- Enable audit logging
-- Use mTLS for inter-agent communication
-
-**DON'T**:
-- Embed secrets in manifests
-- Use API keys in plain text
-- Disable authentication for "internal" agents
-- Store credentials in state or logs
-
----
-
-## Anti-Patterns
-
-### ❌ Embedding Secrets
-
-**NEVER** embed actual secrets in manifests:
-
-```yaml
-# ❌ NEVER DO THIS
-spec:
-  tools:
-    - type: http
-      auth:
-        credentials: sk-1234567890abcdef  # Actual secret!
-```
-
-**✅ Use secret references instead**:
-
-```yaml
-spec:
-  tools:
-    - type: http
-      auth:
-        credentials: ${GITHUB_TOKEN}  # Reference to secret manager
-  security:
-    secrets:
-      provider: vault
-      path: /secret/agents/my-agent
-```
-
-### ❌ Overly Broad Capabilities
-
-**NEVER** grant more capabilities than needed:
-
-```yaml
-# ❌ NEVER DO THIS
-spec:
-  tools:
-    - type: kubernetes
-      namespace: "*"  # All namespaces!
-      capabilities:
-        - name: "*"  # All operations!
-```
-
-**✅ Grant minimum required**:
-
-```yaml
-spec:
-  tools:
-    - type: kubernetes
-      namespace: production  # Specific namespace
-      capabilities:
-        - name: get_pods  # Specific operations
-        - name: describe_pod
-```
-
-### ❌ Missing Observability
-
-**NEVER** deploy without observability:
-
-```yaml
-# ❌ NEVER DO THIS
-spec:
-  observability:
-    logging:
-      enabled: false
-    tracing:
-      enabled: false
-    metrics:
-      enabled: false
-```
-
-**✅ Enable full observability**:
-
-```yaml
-spec:
-  observability:
-    logging:
-      level: info
-      format: json
-    tracing:
-      enabled: true
-      sampling_rate: 1.0
-    metrics:
-      enabled: true
-```
-
-### ❌ No Error Handling
-
-**NEVER** omit error handling:
-
-```yaml
-# ❌ NEVER DO THIS
-spec:
-  tools:
-    - type: http
-      name: flaky-api
-      # No retry policy, no circuit breaker, no timeout!
-```
-
-**✅ Implement comprehensive error handling**:
-
-```yaml
-spec:
-  tools:
-    - type: http
-      name: flaky-api
-      capabilities:
-        - name: call_api
-          retry_policy:
-            max_attempts: 3
-            backoff_strategy: exponential
-          timeout:
-            execution_seconds: 30
-      circuit_breaker:
-        enabled: true
-        failure_threshold: 5
-```
-
-### ❌ Ignoring Compliance
-
-**NEVER** handle regulated data without compliance controls:
-
-```yaml
-# ❌ NEVER DO THIS for HIPAA/PII data
-spec:
-  tools:
-    - type: http
-      name: patient-api
-      # No compliance tags, no PII redaction, no audit logging!
-```
-
-**✅ Enable compliance controls**:
-
-```yaml
-spec:
-  tools:
-    - type: http
-      name: patient-api
-      capabilities:
-        - name: read_patient
-          compliance_tags:
-            - phi
-            - hipaa
-  safety:
-    pii_detection:
-      enabled: true
-      redact: true
-  security:
-    audit:
-      enabled: true
-      retention_days: 2555
-  compliance:
-    profiles:
-      - hipaa
-```
-
-### ❌ Unbounded Resource Usage
-
-**NEVER** allow unlimited execution:
-
-```yaml
-# ❌ NEVER DO THIS
-spec:
-  constraints:
-    execution:
-      max_duration_seconds: 0  # No limit!
-      max_turns: 0  # Infinite loops!
-```
-
-**✅ Set reasonable limits**:
-
-```yaml
-spec:
-  constraints:
-    execution:
-      max_duration_seconds: 600
-      max_turns: 20
-      max_memory_mb: 2048
-```
-
-### ❌ Hardcoded Configuration
-
-**NEVER** hardcode environment-specific values:
-
-```yaml
-# ❌ NEVER DO THIS
-spec:
-  tools:
-    - type: http
-      endpoint: https://api.production.example.com  # Hardcoded!
-```
-
-**✅ Use environment variables or config maps**:
-
-```yaml
-spec:
-  tools:
-    - type: http
-      endpoint: ${API_ENDPOINT}
-  deployment:
-    environment:
-      - name: API_ENDPOINT
-        valueFrom:
-          configMapKeyRef:
-            name: agent-config
-            key: api_endpoint
-```
-
----
-
-## Migration Guide
-
-### From v0.2.8 to v0.2.9
-
-**Breaking Changes**: None
-
-**New Features**:
-1. **Reasoning Strategies**: ReAct, Chain-of-Thought, Tree-of-Thought
-2. **Prompt Templates**: Versioned prompt management
-3. **Knowledge Graph Integration**: First-class knowledge graph support
-4. **agents.md Extension**: OpenAI repository-level agent guidance
-
-**Deprecated Features**:
-- None
-
-**Migration Steps**:
-
-#### 1. Update API Version
-
-```yaml
-# Before (v0.2.8)
-apiVersion: ossa/v0.2.8
-
-# After (v0.2.9)
-apiVersion: ossa/v0.2.9
-```
-
-#### 2. Add Reasoning Strategy (Optional)
-
-If your agent uses explicit reasoning, define it:
-
-```yaml
-spec:
-  reasoning:
-    strategy: react  # or chain_of_thought, tree_of_thought
-    options:
-      max_iterations: 10
-      reflection_enabled: true
-```
-
-#### 3. Migrate to Prompt Templates (Optional)
-
-If you have multiple prompt variants:
-
-```yaml
-# Before
-spec:
-  role: |
-    You are a helpful assistant.
-    # Embedded prompt
-
-# After
-spec:
-  role: |
-    {{prompt.system}}
-  prompts:
-    templates:
-      - name: system
-        version: "1.0"
-        content: |
-          You are a helpful assistant.
-      - name: task
-        version: "1.0"
-        content: |
-          Analyze the following: {{input}}
-```
-
-#### 4. Add Knowledge Graph (Optional)
-
-If using knowledge graphs:
-
-```yaml
-spec:
-  knowledge_graph:
-    provider: neo4j
-    connection:
-      uri: ${NEO4J_URI}
-    queries:
-      - name: get_related_entities
-        cypher: |
-          MATCH (e:Entity {id: $entity_id})-[:RELATED_TO]->(r)
-          RETURN r
-```
-
-#### 5. Add Identity Configuration (Optional)
-
-For multi-agent tracing:
-
-```yaml
-spec:
-  identity:
-    session_id_generation:
-      strategy: uuid
-    instance_id_generation:
-      strategy: hostname
-    trace_context:
-      propagation: w3c
-```
-
-#### 6. Validate Against New Schema
-
-```bash
-ossa validate agent.yaml --schema v0.2.9
-```
-
-### From v0.2.7 to v0.2.9
-
-Follow v0.2.8 → v0.2.9 migration, then:
-
-**Additional Changes**:
-1. Compliance profiles now use `compliance.profiles` instead of `spec.compliance`
-2. State encryption now requires explicit algorithm
-
-```yaml
-# Before (v0.2.7)
-spec:
-  compliance: fedramp
-  state:
-    encryption: true
-
-# After (v0.2.9)
-spec:
-  compliance:
-    profiles:
-      - fedramp-moderate
-  state:
-    persistence:
-      encryption:
-        enabled: true
-        algorithm: AES-256-GCM
-```
-
----
-
-## Validation
-
-To validate an agent manifest:
-
-```bash
-# Using OSSA CLI
-ossa validate agent.yaml
-
-# Using JSON Schema validator
-jsonschema -i agent.yaml \
-  https://openstandardagents.org/schemas/v0.2.9/agent.json
-
-# Using kubectl (if deployed to Kubernetes)
-kubectl apply --dry-run=client -f agent.yaml
-```
-
-**Common Validation Errors**:
-
-1. **Invalid name format**:
-   ```
-   Error: metadata.name must match pattern ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
-   Fix: Use lowercase, hyphens only
-   ```
-
-2. **Invalid semver**:
-   ```
-   Error: metadata.version must be valid semver
-   Fix: Use format MAJOR.MINOR.PATCH (e.g., 1.0.0)
-   ```
-
-3. **Missing required fields**:
-   ```
-   Error: spec.role is required
-   Fix: Add role field with agent's system prompt
-   ```
-
----
-
-## Schema References
-
-- **JSON Schema**: `https://openstandardagents.org/schemas/v0.2.9/agent.json`
-- **TypeScript Types**: See `types.ts` in this directory
-- **Validation CLI**: `npm install -g @bluefly/openstandardagents`
-
----
-
-## Contributing
-
-To propose changes to this specification:
-
-1. Open an issue: https://gitlab.com/blueflyio/openstandardagents/-/issues
-2. Discuss with community
-3. Submit merge request with changes to:
-   - `spec/v0.2.9/agent.md` (this file)
-   - `spec/v0.2.9/ossa-0.2.9.schema.json` (JSON Schema)
-   - `spec/v0.2.9/types.ts` (TypeScript definitions)
-
----
-
-**Document Version**: 1.0.0
-**Last Updated**: 2025-12-04
-**Status**: Draft
-**Authors**: OSSA Technical Committee