@bluefly/openstandardagents 0.3.1 → 0.3.3

package/spec/v0.3.2/schemas/unified-llm.yaml

@@ -0,0 +1,91 @@
+# OSSA v0.3.3 - Unified LLM Configuration Schema
+# Compatible with: OSSA, GitLab Duo, Google A2A, MCP
+# Zero hardcoded models, runtime-configurable, multi-provider
+
+$schema: http://json-schema.org/draft-07/schema#
+$id: https://openstandardagents.org/schemas/v0.3.3/unified-llm.yaml
+
+title: Unified LLM Configuration
+description: |
+  Universal LLM configuration that works across OSSA, GitLab Duo, Google A2A, and MCP.
+  Eliminates hardcoded model names and enables runtime model selection.
+
+type: object
+required:
+  - provider
+  - model
+properties:
+  provider:
+    type: string
+    description: LLM provider name (runtime-configurable via env var)
+    default: ${LLM_PROVIDER:-anthropic}
+    examples:
+      - anthropic
+      - openai
+      - google
+      - groq
+      - ollama
+      - bedrock
+
+  model:
+    type: string
+    description: Model identifier (runtime-configurable via env var)
+    default: ${LLM_MODEL:-claude-sonnet}
+    examples:
+      - claude-sonnet-4
+      - gpt-4o
+      - gemini-2.0-flash
+      - llama-3.3-70b
+      - mixtral-8x7b
+
+  profile:
+    type: string
+    description: Execution profile for task-specific optimization (A2A compatible)
+    default: ${LLM_PROFILE:-balanced}
+    enum:
+      - fast
+      - balanced
+      - deep
+      - safe
+
+  temperature:
+    type: number
+    description: Sampling temperature
+    default: ${LLM_TEMPERATURE:-0.1}
+    minimum: 0.0
+    maximum: 2.0
+
+  maxTokens:
+    type: integer
+    description: Maximum tokens in response
+    default: ${LLM_MAX_TOKENS:-16000}
+
+  topP:
+    type: number
+    description: Nucleus sampling threshold
+    default: ${LLM_TOP_P:-0.9}
+
+  fallback_models:
+    type: array
+    items:
+      type: object
+      required: [provider, model]
+      properties:
+        provider:
+          type: string
+        model:
+          type: string
+        condition:
+          type: string
+          enum: [on_error, on_timeout, on_rate_limit, always]
+
+  retry_config:
+    type: object
+    properties:
+      max_attempts:
+        type: integer
+        default: ${LLM_RETRY_ATTEMPTS:-3}
+      backoff_strategy:
+        type: string
+        enum: [exponential, linear, constant]
+        default: ${LLM_BACKOFF_STRATEGY:-exponential}

package/spec/v0.3.2/taxonomy.yaml

@@ -0,0 +1,363 @@
+# =============================================================================
+# OSSA v0.3.3 - Agent Taxonomy Specification
+# =============================================================================
+# Hierarchical classification system for agents with cross-cutting concerns
+# Now includes access tier integration for separation of duties
+# Issues:
+#   - https://gitlab.com/blueflyio/openstandardagents/-/issues/194 (taxonomy)
+#   - https://gitlab.com/blueflyio/openstandardagents/-/issues/363 (separation of duties)
+# =============================================================================
+
+apiVersion: ossa/v0.3.3
+kind: TaxonomySpec
+version: "2.0.0"
+
+# =============================================================================
+# ACCESS TIER INTEGRATION
+# Links taxonomy to access_tiers.yaml for separation of duties
+# =============================================================================
+access_tier_reference: "./access_tiers.yaml"
+
+# =============================================================================
+# PRIMARY DOMAINS
+# Top-level classification - every agent belongs to exactly one domain
+# =============================================================================
+domains:
+  security:
+    description: "Authentication, authorization, encryption, compliance, vulnerability management"
+    subdomains:
+      - auth                 # Authentication & authorization
+      - encryption          # Encryption & key management
+      - compliance          # Regulatory compliance (SOC2, ISO, GDPR)
+      - vulnerability       # Vulnerability scanning & remediation
+      - secrets             # Secrets management & rotation
+      - threat-detection    # Threat detection & response
+    examples:
+      - security-scanner
+      - compliance-checker
+      - secret-detector
+      - threat-modeler
+
+  infrastructure:
+    description: "DevOps, CI/CD, deployment, configuration, cloud resources"
+    subdomains:
+      - ci-cd               # CI/CD pipeline management
+      - gitops              # GitOps workflows
+      - deployment          # Deployment automation
+      - configuration       # Configuration management
+      - networking          # Network configuration
+      - storage             # Storage management
+      - kubernetes          # Kubernetes orchestration
+      - cloud               # Cloud provider management
+    examples:
+      - deployment-manager
+      - pipeline-fixer
+      - infrastructure-provisioner
+      - incident-responder
+
+  documentation:
+    description: "Documentation, wiki, guides, knowledge management"
+    subdomains:
+      - api-docs            # API documentation
+      - user-guides         # User guides & tutorials
+      - wiki                # Wiki management
+      - knowledge-base      # Knowledge base management
+      - changelog           # Changelog & release notes
+    examples:
+      - documentation-generator
+      - wiki-manager
+      - api-docs-generator
+
+  backend:
+    description: "API, database, services, business logic"
+    subdomains:
+      - api                 # API design & implementation
+      - database            # Database management
+      - services            # Microservices
+      - messaging           # Message queues & events
+      - caching             # Caching strategies
+      - integration         # System integration
+    examples:
+      - api-builder
+      - database-migrator
+      - service-orchestrator
+
+  frontend:
+    description: "UI/UX, web, mobile interfaces"
+    subdomains:
+      - web                 # Web applications
+      - mobile              # Mobile applications
+      - design-system       # Design system components
+      - accessibility       # Accessibility (a11y)
+      - performance         # Frontend performance
+    examples:
+      - ui-reviewer
+      - accessibility-checker
+      - design-system-manager
+
+  data:
+    description: "Data engineering, analytics, ML/AI operations"
+    subdomains:
+      - analytics           # Business analytics
+      - ml-ops              # ML operations
+      - etl                 # Extract, transform, load
+      - data-quality        # Data quality & validation
+      - data-governance     # Data governance
+      - streaming           # Real-time data streaming
+    examples:
+      - analytics-collector
+      - ml-model-manager
+      - data-quality-checker
+
+  agents:
+    description: "OSSA agents, automation, orchestration, meta-operations"
+    subdomains:
+      - orchestration       # Multi-agent orchestration
+      - workers             # Worker agents
+      - supervisors         # Supervisor agents
+      - mesh                # Agent mesh networking
+      - training            # Agent training & improvement
+      - registry            # Agent registry management
+    examples:
+      - master-orchestrator
+      - agent-trainer
+      - workflow-builder
+
+  development:
+    description: "Software development, code quality, testing"
+    subdomains:
+      - code-review         # Code review automation
+      - testing             # Test generation & execution
+      - refactoring         # Code refactoring
+      - debugging           # Debugging assistance
+      - ide                 # IDE integration
+    examples:
+      - code-reviewer
+      - test-generator
+      - refactoring-assistant
+
+  content:
+    description: "Content management, editing, publishing"
+    subdomains:
+      - authoring           # Content authoring
+      - editing             # Content editing
+      - publishing          # Content publishing
+      - research            # Research & knowledge gathering
+      - localization        # Internationalization & localization
+    examples:
+      - content-orchestrator
+      - editor
+      - researcher
+      - publisher
+
+# =============================================================================
+# CROSS-CUTTING CONCERNS
+# Tags that can apply to any agent regardless of domain
+# An agent can have multiple concerns
+# =============================================================================
+concerns:
+  quality:
+    description: "Testing, code quality, standards enforcement"
+    applies_to: ["development", "backend", "frontend", "infrastructure"]
+
+  observability:
+    description: "Metrics, logging, tracing, monitoring"
+    applies_to: ["*"]  # All domains
+
+  governance:
+    description: "Policies, compliance, audit trails"
+    applies_to: ["*"]
+
+  performance:
+    description: "Optimization, caching, scaling"
+    applies_to: ["*"]
+
+  architecture:
+    description: "Design patterns, system structure"
+    applies_to: ["development", "backend", "infrastructure", "agents"]
+
+  cost:
+    description: "FinOps, resource optimization, budget management"
+    applies_to: ["infrastructure", "data", "agents"]
+
+  reliability:
+    description: "SRE, uptime, resilience, disaster recovery"
+    applies_to: ["infrastructure", "backend", "agents"]
+
+# =============================================================================
+# AGENT TYPE CLASSIFICATION
+# Based on OSSA spec.type field - now with access tier recommendations
+# =============================================================================
+agent_types:
+  analyzer:
+    description: "Read-only analysis, scanning, auditing - no modifications"
+    typical_domains: ["security", "development", "data"]
+    recommended_tier: tier_1_read
+    can_delegate_to: []
+
+  worker:
+    description: "Executes specific tasks, limited write access"
+    typical_domains: ["development", "documentation", "content"]
+    recommended_tier: tier_2_write_limited
+    can_delegate_to: ["analyzer"]
+
+  operator:
+    description: "Modifies production systems, requires approval"
+    typical_domains: ["infrastructure", "agents"]
+    recommended_tier: tier_3_write_elevated
+    can_delegate_to: ["worker", "analyzer"]
+
+  supervisor:
+    description: "Coordinates other agents, can delegate"
+    typical_domains: ["agents", "infrastructure"]
+    recommended_tier: tier_3_write_elevated
+    can_delegate_to: ["worker", "analyzer"]
+
+  orchestrator:
+    description: "High-level coordination, workflow management"
+    typical_domains: ["agents"]
+    recommended_tier: tier_3_write_elevated
+    can_delegate_to: ["supervisor", "worker", "analyzer"]
+
+  governor:
+    description: "Defines policies, cannot execute - ISOLATED"
+    typical_domains: ["security", "agents"]
+    recommended_tier: tier_4_policy
+    can_delegate_to: ["operator"]  # Delegation only, not execution
+    isolation: strict
+
+  specialist:
+    description: "Deep expertise in narrow domain"
+    typical_domains: ["security", "data", "backend"]
+    recommended_tier: tier_1_read  # Most specialists are analyzers
+    can_delegate_to: []
+
+  critic:
+    description: "Reviews and provides feedback, cannot approve"
+    typical_domains: ["development", "security"]
+    recommended_tier: tier_1_read
+    prohibited_actions: ["approve", "merge", "execute"]
+    can_delegate_to: []
+
+# =============================================================================
+# DOMAIN-TIER MAPPINGS
+# Recommended access tiers by domain for separation of duties
+# =============================================================================
+domain_tier_recommendations:
+  security:
+    default_tier: tier_1_read
+    rationale: "Security agents should analyze, not modify"
+    exceptions:
+      - role: remediator
+        tier: tier_3_write_elevated
+        requires: governor_approval
+      - role: policy_definer
+        tier: tier_4_policy
+
+  infrastructure:
+    default_tier: tier_3_write_elevated
+    rationale: "Infrastructure requires elevated access"
+    separation_required:
+      - readers: ["monitor", "cost_reporter"]
+        tier: tier_1_read
+      - operators: ["deployer", "provisioner"]
+        tier: tier_3_write_elevated
+
+  documentation:
+    default_tier: tier_2_write_limited
+    rationale: "Doc changes are low-risk"
+
+  development:
+    default_tier: tier_2_write_limited
+    rationale: "Code generation is sandboxed"
+    separation_required:
+      - critics: ["reviewer", "analyzer"]
+        tier: tier_1_read
+        prohibited: ["approve", "merge"]
+      - generators: ["scaffolder", "test_writer"]
+        tier: tier_2_write_limited
+
+  agents:
+    default_tier: tier_3_write_elevated
+    rationale: "Agent orchestration needs elevated access"
+    separation_required:
+      - governors: ["policy_definer", "compliance_enforcer"]
+        tier: tier_4_policy
+        isolation: strict
+      - orchestrators: ["coordinator", "scheduler"]
+        tier: tier_3_write_elevated
+
+  backend:
+    default_tier: tier_2_write_limited
+    separation_required:
+      - analyzers: ["db_analyzer", "api_auditor"]
+        tier: tier_1_read
+      - operators: ["db_migrator", "service_deployer"]
+        tier: tier_3_write_elevated
+
+  data:
+    default_tier: tier_1_read
+    rationale: "Data access is sensitive - read-only by default"
+    exceptions:
+      - role: etl_operator
+        tier: tier_3_write_elevated
+        requires: data_governance_approval
+
+# =============================================================================
+# USAGE IN AGENT MANIFESTS
+# =============================================================================
+# Example usage in OSSA agent manifest:
+#
+# metadata:
+#   name: security-scanner
+#   labels:
+#     domain: security
+#     subdomain: vulnerability
+#     concerns: quality,compliance
+#
+# spec:
+#   type: worker
+#   taxonomy:
+#     domain: security
+#     subdomain: vulnerability
+#     capability: scan_vulnerabilities
+#     concerns:
+#       - quality
+#       - compliance
+
+# =============================================================================
+# VALIDATION RULES
+# =============================================================================
+validation:
+  rules:
+    - name: valid-domain
+      description: "Domain must be from approved list"
+      severity: error
+
+    - name: valid-subdomain
+      description: "Subdomain must belong to specified domain"
+      severity: error
+
+    - name: concerns-applicable
+      description: "Concerns must be applicable to domain"
+      severity: warning
+
+    - name: type-domain-match
+      description: "Agent type should match typical domains"
+      severity: info
+
+# =============================================================================
+# MIGRATION FROM LEGACY
+# =============================================================================
+migration:
+  deprecated_domains:
+    ci-cd: { domain: infrastructure, subdomain: ci-cd }
+    gitops: { domain: infrastructure, subdomain: gitops }
+    deployment: { domain: infrastructure, subdomain: deployment }
+    configuration: { domain: infrastructure, subdomain: configuration }
+    cost-management: { domain: infrastructure, concerns: [cost] }
+    database: { domain: backend, subdomain: database }
+    performance: { concerns: [performance] }
+    observability: { concerns: [observability] }
+    governance: { concerns: [governance] }
+    architecture: { concerns: [architecture] }

package/spec/v0.3.3/MIGRATION-v0.3.2-to-v0.3.3.md

@@ -0,0 +1,117 @@
+# Migration Guide: OSSA v0.3.2 → v0.3.3
+
+> **Status**: Draft
+> **Last Updated**: 2025-12-31
+
+---
+
+## Overview
+
+OSSA v0.3.3 introduces **Skills Compatibility Extension** for interoperability with Anthropic Skills and AgentSkills.io specifications.
+
+### Key Changes
+
+- ✅ **Backward Compatible**: v0.3.2 manifests validate against v0.3.3 schema
+- ✅ **Skills Extension**: New `extensions.skills` for bidirectional Skills format support
+- ✅ **Progressive Disclosure**: Token-budgeted metadata → instructions → resources pattern
+
+---
+
+## Migration Path
+
+### Option 1: No Changes Required (Recommended for Existing Agents)
+
+**v0.3.2 agents continue to work without modification:**
+
+```yaml
+apiVersion: ossa/v0.3.2
+kind: Agent
+metadata:
+  name: my-agent
+  version: 1.0.0
+# ... rest of manifest unchanged
+```
+
+### Option 2: Add Skills Compatibility
+
+**Enable Skills format export/import:**
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: my-skill-compatible-agent
+  version: 1.0.0
+  description: Agent with Skills compatibility
+spec:
+  # ... existing spec
+extensions:
+  skills:
+    enabled: true
+    platforms:
+      - Claude
+      - Claude Code
+      - Cursor
+    allowedTools:
+      - Read
+      - Write
+      - Bash
+    progressiveDisclosure:
+      metadataTokens: 100
+      instructionsTokens: 5000
+```
+
+---
+
+## New Features in v0.3.3
+
+### Skills Extension
+
+The Skills extension enables OSSA agents to be packaged and distributed as Skills, and allows Skills to be consumed by OSSA-compliant runtimes.
+
+**Key Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | boolean | Enable Skills format export/import |
+| `platforms` | string[] | Compatible platforms (Claude, Cursor, etc.) |
+| `allowedTools` | string[] | Pre-approved tools list |
+| `progressiveDisclosure` | object | Token budgets for disclosure stages |
+| `directories` | object | Skills directory structure mapping |
+
+**CLI Commands:**
+
+```bash
+# Export OSSA manifest to Skills format
+ossa export --format skills --output ./my-skill/
+
+# Import Skills into OSSA
+ossa import --format skills --path ./my-skill/
+```
+
+---
+
+## Schema Changes
+
+### Added Definitions
+
+- `SkillsExtension`: Full Skills compatibility configuration
+
+### Extensions Object
+
+```json
+{
+  "extensions": {
+    "mcp": { "$ref": "#/definitions/MCPExtension" },
+    "skills": { "$ref": "#/definitions/SkillsExtension" }
+  }
+}
+```
+
+---
+
+## References
+
+- [Skills Compatibility Extension](../extensions/skills-compatibility.md)
+- [Anthropic Skills Repository](https://github.com/anthropics/skills)
+- [AgentSkills.io Specification](https://agentskills.io/specification)

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

@@ -0,0 +1,120 @@
+# OSSA v0.3.3 - Unified Agent Schema
+
+## The Rocketship 🚀
+
+This schema unifies OSSA, GitLab Duo, Google A2A, and MCP into a single universal agent platform.
+
+### What Changed
+
+**Before (v0.2.x):**
+```yaml
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+```
+
+**After (v0.3.3):**
+```yaml
+llm:
+  provider: ${LLM_PROVIDER:-anthropic}
+  model: ${LLM_MODEL:-claude-sonnet}
+  profile: ${LLM_PROFILE:-balanced}
+  fallback_models:
+    - provider: ${LLM_FALLBACK_PROVIDER_1:-openai}
+      model: ${LLM_FALLBACK_MODEL_1:-gpt-4o}
+```
+
+### Key Features
+
+1. **Zero Hardcoded Models** - All LLM config is runtime-configurable
+2. **Execution Profiles** - Google A2A compatible (fast/balanced/deep/safe)
+3. **Multi-Runtime Support** - Works with Duo, A2A, OSSA, MCP
+4. **Fallback Models** - Multi-provider resilience
+5. **Structured Functions** - A2A/OpenAI function calling format
+6. **Extensions** - Pluggable external behaviors
+
+### Compatibility Matrix
+
+| Feature | OSSA v0.2.x | Duo | A2A | v0.3.3 |
+|---------|-------------|-----|-----|--------|
+| Runtime-configurable models | ❌ | ❌ | ✅ | ✅ |
+| Execution profiles | ❌ | ❌ | ✅ | ✅ |
+| Multi-provider fallback | partial | ❌ | ✅ | ✅ |
+| Structured functions | ❌ | partial | ✅ | ✅ |
+| Extensions | partial | partial | ✅ | ✅ |
+
+### Migration
+
+```bash
+# Auto-migrate all agents
+./scripts/migrate-to-unified-llm.sh
+
+# Generate new agent
+./scripts/generate-agent.sh my-agent worker
+
+# Validate
+ossa validate examples/
+```
+
+### Environment Variables
+
+```bash
+# Primary LLM
+export LLM_PROVIDER=anthropic
+export LLM_MODEL=claude-sonnet-4
+export LLM_PROFILE=balanced
+
+# Fallbacks
+export LLM_FALLBACK_PROVIDER_1=openai
+export LLM_FALLBACK_MODEL_1=gpt-4o
+
+# Runtime
+export AGENT_RUNTIME=unified
+export AGENT_SCHEDULING=fair
+export AGENT_PRIORITY=normal
+```
+
+### Execution Profiles
+
+- **fast** - Quick responses (4K tokens, temp=0.0)
+- **balanced** - General ops (16K tokens, temp=0.1)
+- **deep** - Analysis (32K tokens, temp=0.2, reasoning enabled)
+- **safe** - Compliance (temp=0.0, validation required)
+
+### CI Enforcement
+
+Add to `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - local: .gitlab/ci/validate-no-hardcoded-models.yml
+```
+
+This blocks any MR with hardcoded model names.
+
+### Example Agent
+
+See: `examples/unified/security-scanner.ossa.yaml`
+
+### Schema Files
+
+- `schemas/unified-llm.yaml` - LLM configuration
+- `schemas/runtime.yaml` - Runtime declaration
+- `schemas/capabilities.yaml` - Capability definitions
+- `schemas/functions.yaml` - Function declarations
+- `schemas/agent-unified.yaml` - Complete agent schema
+
+### Why This Matters
+
+1. **No More Breaking Changes** - Model updates don't require code changes
+2. **Multi-Provider** - Switch between Anthropic/OpenAI/Google/Groq instantly
+3. **Future-Proof** - New runtimes (A2A, Duo) work without modification
+4. **Cost Optimization** - Use cheap models for triage, expensive for analysis
+5. **Compliance** - Audit trail of which models were used when
+
+### Next Steps
+
+1. Run migration: `./scripts/migrate-to-unified-llm.sh`
+2. Update CI: Add validation rule
+3. Test: `ossa validate examples/`
+4. Deploy: Agents auto-detect runtime