@bluefly/openstandardagents 0.3.3 → 0.3.6

package/spec/v0.3.6/taxonomy.yaml

@@ -0,0 +1,506 @@
+# =============================================================================
+# 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.6
+kind: TaxonomySpec
+version: "3.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] }
+
+# =============================================================================
+# AGENT MATURITY LEVELS
+# Classification of agent readiness and stability
+# =============================================================================
+maturity_levels:
+  prototype:
+    description: "Early development, experimental, not production-ready"
+    stability: low
+    testing_required: minimal
+    documentation_required: basic
+    use_cases: ["proof-of-concept", "experimentation", "learning"]
+
+  beta:
+    description: "Feature-complete, undergoing testing, near production-ready"
+    stability: medium
+    testing_required: comprehensive
+    documentation_required: complete
+    use_cases: ["early-adopter testing", "staging environments"]
+
+  stable:
+    description: "Production-ready, well-tested, documented, maintained"
+    stability: high
+    testing_required: extensive
+    documentation_required: comprehensive
+    use_cases: ["production workloads", "enterprise adoption"]
+
+  production:
+    description: "Enterprise-grade, fully tested, documented, supported, SLA-backed"
+    stability: very_high
+    testing_required: exhaustive
+    documentation_required: enterprise-grade
+    use_cases: ["mission-critical systems", "enterprise production"]
+
+# =============================================================================
+# DEPLOYMENT PATTERNS
+# How agents are deployed and executed
+# =============================================================================
+deployment_patterns:
+  serverless:
+    description: "Function-as-a-Service, event-driven, auto-scaling"
+    examples: ["AWS Lambda", "Google Cloud Functions", "Azure Functions"]
+    characteristics: ["stateless", "ephemeral", "cost-efficient"]
+    use_cases: ["event processing", "API endpoints", "scheduled tasks"]
+
+  container:
+    description: "Containerized deployment, long-running processes"
+    examples: ["Docker", "Podman", "containerd"]
+    characteristics: ["stateful", "persistent", "resource-controlled"]
+    use_cases: ["microservices", "background workers", "API servers"]
+
+  edge:
+    description: "Edge computing, low latency, distributed"
+    examples: ["Cloudflare Workers", "AWS Lambda@Edge", "Akamai Edge"]
+    characteristics: ["low-latency", "distributed", "lightweight"]
+    use_cases: ["real-time processing", "CDN integration", "IoT"]
+
+  hybrid:
+    description: "Combination of multiple deployment patterns"
+    examples: ["serverless + container", "edge + cloud"]
+    characteristics: ["flexible", "optimized", "complex"]
+    use_cases: ["multi-tier architectures", "optimized cost/performance"]
+
+# =============================================================================
+# INTEGRATION PATTERNS
+# How agents integrate with external systems
+# =============================================================================
+integration_patterns:
+  api-first:
+    description: "REST/GraphQL APIs, HTTP-based communication"
+    protocols: ["REST", "GraphQL", "gRPC"]
+    characteristics: ["synchronous", "request-response", "stateless"]
+    use_cases: ["web services", "microservices", "API integration"]
+
+  event-driven:
+    description: "Event streams, message queues, pub/sub"
+    protocols: ["CloudEvents", "NATS", "Kafka", "RabbitMQ"]
+    characteristics: ["asynchronous", "decoupled", "scalable"]
+    use_cases: ["event processing", "workflow orchestration", "real-time systems"]
+
+  batch:
+    description: "Scheduled jobs, bulk processing, ETL"
+    protocols: ["Cron", "Scheduled Tasks", "ETL Pipelines"]
+    characteristics: ["scheduled", "bulk", "resource-intensive"]
+    use_cases: ["data processing", "reporting", "migration"]
+
+  streaming:
+    description: "Real-time data streams, continuous processing"
+    protocols: ["WebSocket", "Server-Sent Events", "gRPC Streaming"]
+    characteristics: ["real-time", "continuous", "low-latency"]
+    use_cases: ["live updates", "real-time analytics", "chat systems"]
+
+# =============================================================================
+# COST PROFILES
+# Expected cost characteristics of agent execution
+# =============================================================================
+cost_profiles:
+  low:
+    description: "Minimal cost, infrequent execution, simple operations"
+    estimated_monthly_cost: "< $10"
+    characteristics: ["infrequent", "simple", "low-resource"]
+    use_cases: ["personal projects", "prototypes", "low-volume"]
+
+  medium:
+    description: "Moderate cost, regular execution, standard operations"
+    estimated_monthly_cost: "$10 - $100"
+    characteristics: ["regular", "standard", "moderate-resource"]
+    use_cases: ["small teams", "development", "moderate-volume"]
+
+  high:
+    description: "Significant cost, frequent execution, complex operations"
+    estimated_monthly_cost: "$100 - $1000"
+    characteristics: ["frequent", "complex", "high-resource"]
+    use_cases: ["production systems", "enterprise", "high-volume"]
+
+  enterprise:
+    description: "Enterprise-scale cost, continuous execution, mission-critical"
+    estimated_monthly_cost: "> $1000"
+    characteristics: ["continuous", "mission-critical", "enterprise-resource"]
+    use_cases: ["large enterprises", "mission-critical", "high-scale"]
+
+# =============================================================================
+# PERFORMANCE TIERS
+# Expected performance characteristics
+# =============================================================================
+performance_tiers:
+  real-time:
+    description: "Sub-second response, immediate processing"
+    latency_requirement: "< 1 second"
+    throughput: "high"
+    use_cases: ["user interactions", "live systems", "interactive agents"]
+
+  near-real-time:
+    description: "Fast response, seconds to minutes"
+    latency_requirement: "1 second - 5 minutes"
+    throughput: "medium-high"
+    use_cases: ["background processing", "notifications", "updates"]
+
+  batch:
+    description: "Scheduled processing, minutes to hours"
+    latency_requirement: "5 minutes - 24 hours"
+    throughput: "medium"
+    use_cases: ["reporting", "analytics", "ETL", "scheduled tasks"]

package/src/dev-cli/README.md

@@ -0,0 +1,53 @@
+# OSSA Developer CLI
+
+**Production tool in `src/`** - Separate from npm package, only for developers working on OSSA itself.
+
+## Purpose
+
+- **Version Management**: One command to release (`ossa-dev version:release`)
+- **Validation**: Validate version consistency (`ossa-dev version:validate`)
+- **Audit**: Find all hardcoded versions (`ossa-dev version:audit`)
+- **Spec Generation**: Generate spec in CI (`ossa-dev spec:generate`)
+
+## Architecture
+
+- **OpenAPI-First**: `openapi/dev-cli.openapi.yml` defines all commands
+- **Zod Validation**: All inputs/outputs validated with Zod schemas
+- **DRY**: Single source of truth (`.version.json`)
+- **SOLID**: Each command is a separate service
+
+## Commands
+
+```bash
+# Version Management
+ossa-dev version:release [patch|minor|major]  # One command to release
+ossa-dev version:validate                     # Validate consistency
+ossa-dev version:audit                        # Find hardcoded versions
+ossa-dev version:sync                         # Sync 0.3.4 placeholders
+ossa-dev version:replace <old> <new>         # Replace version in files
+
+# Spec Generation (for CI)
+ossa-dev spec:generate                        # Generate spec from source
+ossa-dev spec:validate                        # Validate generated spec
+
+# Workflow Help
+ossa-dev workflow:release                     # Show release workflow
+ossa-dev workflow:validate                    # Show validation workflow
+```
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Link locally
+npm link
+
+# Use
+ossa-dev version:release patch
+```
+
+## CI Integration
+
+The CI uses `ossa-dev spec:generate` to generate the spec from source, preventing local AI bots from breaking it.

package/src/dev-cli/src/index.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env tsx
+
+/**
+ * OSSA Developer CLI
+ *
+ * Separate from npm package - Only for developers working on OSSA itself.
+ *
+ * Architecture:
+ * - OpenAPI-First: openapi/dev-cli.openapi.yml defines all commands
+ * - Zod Validation: All inputs/outputs validated with Zod schemas
+ * - DRY: Single source of truth (.version.json)
+ * - SOLID: Each command is a separate service
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { versionCommand } from './commands/version.command.js';
+import { specCommand } from './commands/spec.command.js';
+import { workflowCommand } from './commands/workflow.command.js';
+import { releaseCommand } from './commands/release.command.js';
+import { v035Command } from './commands/v035.command.js';
+import { migrateCommand } from './commands/migrate.command.js';
+import { createEnvCleanupCommand } from './commands/env-cleanup.command.js';
+
+const program = new Command();
+
+program
+  .name('ossa-dev')
+  .description('OSSA Developer CLI - Version management and spec generation')
+  .version('1.0.0');
+
+// Add command groups
+program.addCommand(versionCommand);
+program.addCommand(specCommand);
+program.addCommand(workflowCommand);
+program.addCommand(releaseCommand);
+program.addCommand(v035Command);
+program.addCommand(migrateCommand);
+program.addCommand(createEnvCleanupCommand()); // TODO: Move to buildkit
+
+// Error handling
+program.configureOutput({
+  writeErr: (str) => process.stderr.write(chalk.red(str)),
+});
+
+// Parse arguments
+program.parse();

package/templates/agent-types/analyzer/cost-analyzer.yaml

@@ -0,0 +1,38 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: cost-analyzer
+  version: 1.0.0
+  description: Cost analysis agent that tracks infrastructure costs, identifies optimization opportunities, and generates cost reports
+  labels:
+    ossa.ai/type: analyzer
+    ossa.ai/domain: infrastructure
+spec:
+  role: Cost Analysis Agent
+  system_message: |
+    You are a cost analysis agent that tracks infrastructure spending, analyzes 
+    cost trends, identifies optimization opportunities, and generates detailed 
+    cost reports with recommendations.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.1
+  tools:
+    - name: get_cost_data
+      description: Retrieve infrastructure cost data
+      parameters:
+        type: object
+        properties:
+          period:
+            type: string
+          service:
+            type: string
+  taxonomy:
+    domain: infrastructure
+    subdomain: cost
+    capability: cost_analysis
+    concerns: [cost, performance]
+    maturity: stable
+    deployment_pattern: serverless
+    integration_pattern: api-first
+    cost_profile: low
+    performance_tier: batch

package/templates/agent-types/analyzer/performance-profiler.yaml

@@ -0,0 +1,38 @@
+apiVersion: ossa/v0.3.6
+metadata:
+  name: performance-profiler
+  version: 1.0.0
+  description: Performance profiling agent that analyzes application performance, identifies bottlenecks, and recommends optimizations
+  labels:
+    ossa.ai/type: analyzer
+    ossa.ai/domain: development
+spec:
+  role: Performance Profiling Agent
+  system_message: |
+    You are a performance profiling agent that analyzes application performance 
+    metrics, identifies bottlenecks, profiles code execution, and provides 
+    actionable optimization recommendations.
+  llm_config:
+    provider: openai
+    model: gpt-4
+    temperature: 0.2
+  tools:
+    - name: profile_application
+      description: Profile application performance
+      parameters:
+        type: object
+        properties:
+          application:
+            type: string
+          duration:
+            type: integer
+  taxonomy:
+    domain: development
+    subdomain: performance
+    capability: profiling
+    concerns: [performance, quality]
+    maturity: beta
+    deployment_pattern: container
+    integration_pattern: api-first
+    cost_profile: medium
+    performance_tier: near-real-time