@bluefly/openstandardagents 0.2.8 → 0.3.0

package/examples/getting-started/05-workflow-composition.ossa.yaml

@@ -0,0 +1,209 @@
+# =============================================================================
+# OSSA Getting Started: 05 - Workflow Composition
+# =============================================================================
+#
+# Workflows compose multiple Tasks and Agents into executable pipelines.
+# This is OSSA's power feature - orchestrate complex processes declaratively.
+#
+# Workflow vs Agent:
+# - Agent: LLM-powered, can reason and decide
+# - Task: Deterministic, no LLM (batch jobs, transformations)
+# - Workflow: Composes Agents and Tasks with control flow
+#
+# Features:
+# - Triggers: webhook, cron, events
+# - Steps: sequential, parallel, conditional
+# - Error handling: retry, rollback, compensation
+# - Data flow: pass outputs between steps
+#
+# Run:   ossa validate 05-workflow-composition.ossa.yaml
+# =============================================================================
+
+apiVersion: ossa/v0.3.0
+kind: Workflow
+metadata:
+  name: code-review-pipeline
+  version: 1.0.0
+  description: Automated code review pipeline with security scanning
+  labels:
+    difficulty: advanced
+    tutorial: "05"
+    use-case: ci-cd
+
+spec:
+  # Triggers that start the workflow
+  triggers:
+    # Webhook trigger - receives HTTP POST
+    - type: webhook
+      path: /api/review
+      method: POST
+      authentication:
+        type: bearer
+        secret_ref: ${WEBHOOK_SECRET}
+
+    # Event trigger - GitLab merge request events
+    - type: event
+      source: gitlab
+      events:
+        - merge_request.opened
+        - merge_request.updated
+      filter:
+        # Only trigger for specific branches
+        expression: "${{ event.target_branch in ['main', 'develop'] }}"
+
+  # Input schema - validates incoming data
+  inputs:
+    type: object
+    required: [repository_url, branch]
+    properties:
+      repository_url:
+        type: string
+        format: uri
+        description: Git repository URL
+      branch:
+        type: string
+        description: Branch to review
+      pr_number:
+        type: integer
+        description: Pull request number (if applicable)
+
+  # Output schema - what the workflow produces
+  outputs:
+    type: object
+    properties:
+      review_status:
+        type: string
+        enum: [approved, changes_requested, blocked]
+      findings:
+        type: array
+        items:
+          type: object
+      security_score:
+        type: number
+        minimum: 0
+        maximum: 100
+
+  # Workflow steps - the main logic
+  steps:
+    # Step 1: Validate the PR (deterministic Task - no LLM)
+    - id: validate
+      name: Validate PR Structure
+      kind: Task
+      ref: ./tasks/validate-pr.ossa.yaml
+      input:
+        repository: "${{ workflow.input.repository_url }}"
+        branch: "${{ workflow.input.branch }}"
+      # Step outputs are available to subsequent steps
+      output:
+        files_changed: array
+        is_valid: boolean
+
+    # Step 2: Security scan (Agent - uses LLM)
+    # Only runs if PR is valid
+    - id: security-scan
+      name: Security Analysis
+      kind: Agent
+      ref: ./agents/security-scanner.ossa.yaml
+      condition: "${{ steps.validate.output.is_valid == true }}"
+      input:
+        files: "${{ steps.validate.output.files_changed }}"
+        scan_type: full
+      output:
+        vulnerabilities: array
+        security_score: number
+
+    # Step 3: Code review (Agent - uses LLM)
+    # Runs in parallel with security scan
+    - id: code-review
+      name: Code Quality Review
+      kind: Agent
+      ref: ./agents/code-reviewer.ossa.yaml
+      condition: "${{ steps.validate.output.is_valid == true }}"
+      parallel_with: security-scan  # Run simultaneously with security scan
+      input:
+        files: "${{ steps.validate.output.files_changed }}"
+        review_type: comprehensive
+      output:
+        suggestions: array
+        quality_score: number
+
+    # Step 4: Aggregate results (Task - no LLM)
+    # Waits for both security-scan and code-review
+    - id: aggregate
+      name: Aggregate Review Results
+      kind: Task
+      depends_on:
+        - security-scan
+        - code-review
+      ref: ./tasks/aggregate-results.ossa.yaml
+      input:
+        security_findings: "${{ steps.security-scan.output.vulnerabilities }}"
+        security_score: "${{ steps.security-scan.output.security_score }}"
+        code_suggestions: "${{ steps.code-review.output.suggestions }}"
+        quality_score: "${{ steps.code-review.output.quality_score }}"
+      output:
+        final_status: string
+        combined_findings: array
+
+    # Step 5: Post comment to PR (Task - no LLM)
+    - id: post-comment
+      name: Post Review Comment
+      kind: Task
+      ref: ./tasks/post-pr-comment.ossa.yaml
+      input:
+        pr_number: "${{ workflow.input.pr_number }}"
+        status: "${{ steps.aggregate.output.final_status }}"
+        findings: "${{ steps.aggregate.output.combined_findings }}"
+
+    # Conditional step: Block if critical issues
+    - id: block-merge
+      name: Block Merge on Critical Issues
+      kind: Task
+      condition: "${{ steps.aggregate.output.final_status == 'blocked' }}"
+      ref: ./tasks/block-merge.ossa.yaml
+      input:
+        pr_number: "${{ workflow.input.pr_number }}"
+        reason: "Critical security vulnerabilities found"
+
+  # Shared context available to all steps
+  context:
+    variables:
+      organization: "${{ env.GITHUB_ORG }}"
+      default_reviewers:
+        - "@security-team"
+        - "@code-review-team"
+
+  # Error handling configuration
+  error_handling:
+    # What to do when a step fails
+    on_failure: compensation  # Options: fail_fast, continue, compensation, rollback
+
+    # Compensation steps - undo partial work
+    compensation_steps:
+      - id: cleanup
+        name: Cleanup Failed Review
+        kind: Task
+        ref: ./tasks/cleanup-review.ossa.yaml
+        input:
+          pr_number: "${{ workflow.input.pr_number }}"
+
+    # Retry configuration for transient failures
+    retry:
+      max_attempts: 3
+      backoff: exponential
+      initial_delay_seconds: 5
+
+  # Timeouts
+  timeouts:
+    workflow: 30m      # Total workflow timeout
+    step_default: 5m   # Default per-step timeout
+
+  # Observability
+  observability:
+    tracing:
+      enabled: true
+      exporter: otlp
+    metrics:
+      enabled: true
+      custom_labels:
+        workflow: code-review-pipeline

package/examples/getting-started/README.md

@@ -0,0 +1,69 @@
+# OSSA Getting Started Examples
+
+Learn OSSA step-by-step with these progressively complex examples.
+
+## Prerequisites
+
+```bash
+npm install -g @bluefly/ossa-cli
+```
+
+## Examples
+
+| # | File | Concepts | Time |
+|---|------|----------|------|
+| 01 | [minimal-agent](01-minimal-agent.ossa.yaml) | `kind: Agent`, `role`, `llm` | 2 min |
+| 02 | [agent-with-tools](02-agent-with-tools.ossa.yaml) | `tools`, MCP, function | 5 min |
+| 03 | [agent-with-safety](03-agent-with-safety.ossa.yaml) | `safety`, `autonomy`, `observability` | 10 min |
+| 04 | [agent-with-messaging](04-agent-with-messaging.ossa.yaml) | A2A, pub/sub, commands | 10 min |
+| 05 | [workflow-composition](05-workflow-composition.ossa.yaml) | `kind: Workflow`, steps, error handling | 15 min |
+
+## Quick Start
+
+```bash
+# Validate an example
+ossa validate 01-minimal-agent.ossa.yaml
+
+# Run interactively (requires LLM API key)
+export ANTHROPIC_API_KEY=your-key
+ossa run 01-minimal-agent.ossa.yaml --input "Hello, how can you help me?"
+
+# Export to framework
+ossa export 02-agent-with-tools.ossa.yaml --format langchain
+```
+
+## Learning Path
+
+```
+01-minimal → Understand the basics (Agent, role, llm)
+     ↓
+02-tools → Add capabilities (MCP, functions)
+     ↓
+03-safety → Production readiness (guardrails, PII, rate limits)
+     ↓
+04-messaging → Agent-to-agent communication (A2A, pub/sub)
+     ↓
+05-workflow → Orchestration (compose agents + tasks)
+```
+
+## Environment Variables
+
+All examples use environment variables for portability:
+
+```bash
+# Required
+export LLM_PROVIDER=anthropic  # or openai, google, etc.
+export LLM_MODEL=claude-sonnet-4-20250514
+
+# For tools
+export GITHUB_TOKEN=your-github-token
+
+# For observability
+export OTEL_ENDPOINT=http://localhost:4317
+```
+
+## Next Steps
+
+- [Full Examples](../agent-manifests/) - Real-world agent definitions
+- [Framework Adapters](../adapters/) - LangChain, CrewAI, AutoGen
+- [Schema Reference](../../spec/v0.3.0/) - Complete OSSA specification

package/examples/getting-started/hello-world-complete.ossa.yaml

@@ -32,7 +32,7 @@
 #
 # ============================================================================
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 
 metadata:

package/examples/integration-patterns/agent-to-agent-orchestration.ossa.yaml

@@ -36,7 +36,7 @@
 # ----------------------------------------------------------------------------
 # Coordinates the workflow, delegates tasks to worker agents, and aggregates results
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 
 metadata:
@@ -154,7 +154,7 @@ spec:
 # Specialized agent for research tasks
 
 ---
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 
 metadata:
@@ -221,7 +221,7 @@ spec:
 # Specialized agent for data analysis
 
 ---
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 
 metadata:
@@ -282,7 +282,7 @@ spec:
 # Specialized agent for content creation
 
 ---
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 
 metadata:

package/examples/kagent/compliance-validator.ossa.yaml

@@ -2,7 +2,7 @@
 # Compliance Validator Agent
 # Domain: compliance.validation.continuous
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   name: compliance-validator

package/examples/kagent/cost-optimizer.ossa.yaml

@@ -2,7 +2,7 @@
 # Cost Optimizer Agent
 # Domain: infrastructure.cost.optimization
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   name: cost-optimizer

package/examples/kagent/documentation-agent.ossa.yaml

@@ -2,7 +2,7 @@
 # Documentation Agent
 # Domain: documentation.generation.automated
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   name: documentation-agent

package/examples/kagent/k8s-troubleshooter-v1.ossa.yaml

@@ -2,7 +2,7 @@
 # Kubernetes Troubleshooter Agent with KAgent Bridge
 # Fully compatible with kagent.dev/v1alpha2
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 ossaVersion: "1.0"
 
 agent:

package/examples/kagent/k8s-troubleshooter-v1.v0.2.2.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   name: k8s-troubleshooter

package/examples/kagent/k8s-troubleshooter.ossa.yaml

@@ -17,7 +17,7 @@
 # Domain: infrastructure.kubernetes.troubleshooting
 # ============================================================================
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   # Basic agent identification metadata

package/examples/kagent/security-scanner.ossa.yaml

@@ -6,7 +6,7 @@
 # Last Updated: 2025-11-10
 # ============================================================================
 
-apiVersion: ossa/v0.2.8
+apiVersion: ossa/v0.3.0
 kind: Agent
 metadata:
   # Core identity metadata for the security scanning agent

package/examples/langchain/chain-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.8",
+  "apiVersion": "ossa/v0.3.0",
   "kind": "Agent",
   "metadata": {
     "name": "langchain-agent",

package/examples/langflow/workflow-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.8",
+  "apiVersion": "ossa/v0.3.0",
   "kind": "Agent",
   "metadata": {
     "name": "workflow-orchestrator",

package/examples/langgraph/state-machine-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.8",
+  "apiVersion": "ossa/v0.3.0",
   "kind": "Agent",
   "metadata": {
     "name": "state-machine-agent",

package/examples/llamaindex/rag-agent.ossa.json

@@ -1,5 +1,5 @@
 {
-  "apiVersion": "ossa/v0.2.8",
+  "apiVersion": "ossa/v0.3.0",
   "kind": "Agent",
   "metadata": {
     "name": "rag-query-agent",