Extensibility & Plugin System

Extension mechanisms, plugin architecture, and customization patterns

Extensibility & Plugin System

OSpec provides multiple extension mechanisms to customize agent behavior, add new outcome types, integrate with external tools, and adapt to organization-specific requirements.

Extension Architecture

Core Extension Points

OSpec Core
├── Outcome Type Plugins      # New project types
├── Stack Plugins            # Technology stacks  
├── Agent Plugins            # Custom agent roles
├── Guardrail Plugins        # Security/quality rules
├── Integration Plugins      # External tool connectors
├── Template Plugins         # Code generation templates
└── Workflow Plugins         # Custom automation flows

Plugin Discovery & Loading

# Plugin registry configuration
plugins:
  registry: "https://registry.ospec.dev"
  local_paths: 
    - "./plugins"
    - "~/.ospec/plugins"
  
  enabled:
    - "@ospec/aws-stack"
    - "@ospec/kubernetes-deploy"
    - "@company/internal-patterns"
    - "./plugins/custom-guardrails"
  
  config:
    "@ospec/aws-stack":
      region: "us-east-1"
      profile: "development"

Outcome Type Plugins

Custom Outcome Types

Add support for new project types beyond the built-in ones:

# Plugin: @company/microservice-outcome
plugin_type: "outcome_type"
name: "microservice"
version: "1.0.0"

schema:
  properties:
    service_mesh:
      type: string
      enum: ["istio", "linkerd", "consul-connect"]
    database_per_service:
      type: boolean
      default: true
    event_bus:
      type: string
      enum: ["kafka", "rabbitmq", "redis-streams"]

acceptance_defaults:
  http_endpoints:
    - path: "/health"
      status: 200
    - path: "/metrics" 
      status: 200
  
  performance:
    response_time_ms: 100
    throughput_rps: 1000
    availability: 0.999

stack_defaults:
  framework: "Spring Boot"
  database: "PostgreSQL"
  cache: "Redis"
  monitoring: "Micrometer + Prometheus"
  deploy: "Kubernetes"

templates:
  - name: "service-template"
    path: "./templates/microservice"
    variables:
      - "service_name"
      - "database_name"
      - "port"

Usage in OSpec

ospec_version: "1.0.0"
outcome_type: "microservice"  # Custom type from plugin

# Plugin-specific configuration
service_mesh: "istio"
database_per_service: true
event_bus: "kafka"

# Inherits defaults from plugin but can override
acceptance:
  http_endpoints:
    - path: "/api/orders"
      status: 200
  performance:
    response_time_ms: 50  # Stricter than default

Stack Plugins

Technology Stack Extensions

Pre-configured, validated technology combinations:

# Plugin: @ospec/nextjs-supabase-stack
plugin_type: "stack"
name: "nextjs-supabase"
version: "1.2.0"

description: "Next.js with Supabase backend and Vercel deployment"

components:
  frontend:
    framework: "Next.js"
    version: "14.x"
    features: ["app-router", "server-components"]
  
  backend:
    service: "Supabase"
    features: ["auth", "database", "storage", "edge-functions"]
  
  styling:
    framework: "TailwindCSS"
    version: "3.x"
  
  deployment:
    platform: "Vercel"
    features: ["edge-functions", "analytics"]

dependencies:
  required:
    - "next@^14.0.0"
    - "@supabase/supabase-js@^2.0.0"
    - "tailwindcss@^3.0.0"
  
  optional:
    - "@supabase/auth-helpers-nextjs"
    - "@vercel/analytics"

configuration:
  files:
    - source: "templates/next.config.js"
      target: "next.config.js"
    - source: "templates/supabase.config.ts"
      target: "lib/supabase.ts"
    - source: "templates/tailwind.config.js"
      target: "tailwind.config.js"

guardrails:
  tests_required: true
  min_test_coverage: 0.8
  security_scan: true
  
secrets_template:
  provider: "vercel://env"
  required:
    - "SUPABASE_URL"
    - "SUPABASE_ANON_KEY"
  optional:
    - "SUPABASE_SERVICE_KEY"

validation:
  compatibility:
    node_version: ">=18.0.0"
    supported_os: ["linux", "macos", "windows"]
  
  health_checks:
    - name: "supabase_connection"
      command: "npm run test:db-connection"
    - name: "build_success"
      command: "npm run build"

Stack Selection Logic

Agents can use sophisticated logic to choose the best stack:

# Plugin: @ospec/smart-stack-selector
plugin_type: "stack_selector"

selection_rules:
  - conditions:
      outcome_type: "web-app"
      requirements:
        authentication: true
        real_time: true
      team_experience: ["React", "Node.js"]
    recommended_stack: "nextjs-supabase"
    confidence: 0.9
  
  - conditions:
      outcome_type: "api"
      performance:
        throughput_rps: ">10000"
      scalability: "horizontal"
    recommended_stack: "rust-axum-postgres"
    confidence: 0.85

  - conditions:
      outcome_type: "cli"
      target_platforms: ["linux", "macos", "windows"]
      binary_size: "small"
    recommended_stack: "rust-clap"
    confidence: 0.95

Agent Plugins

Custom Agent Roles

Extend the built-in agent roles or create specialized ones:

# Plugin: @company/security-reviewer-agent
plugin_type: "agent"
role: "security_reviewer"
version: "1.0.0"

extends: "reviewer"  # Inherit from built-in reviewer

capabilities:
  - "sast_analysis"
  - "dast_scanning"
  - "threat_modeling"
  - "compliance_checking"
  - "penetration_testing"

specializations:
  - "web_application_security"
  - "api_security"
  - "cloud_security"
  - "container_security"

configuration:
  tools:
    sast: "semgrep"
    dast: "owasp-zap"
    secrets: "truffhog"
    dependencies: "snyk"
  
  thresholds:
    max_critical_vulnerabilities: 0
    max_high_vulnerabilities: 2
    max_secrets_exposed: 0

workflows:
  review_process:
    - step: "static_analysis"
      tools: ["semgrep", "bandit"]
      fail_on_critical: true
    
    - step: "dependency_scan"
      tools: ["snyk"]
      severity_threshold: "high"
    
    - step: "secret_scan"
      tools: ["truffhog"]
      fail_on_secrets: true
    
    - step: "manual_review"
      required_for: ["auth_changes", "payment_flow"]
      reviewers: 2
      
    - step: "approval"
      conditions:
        - all_scans_pass: true
        - manual_review_approved: true

prompts:
  system: "prompts/security_reviewer_system.md"
  review: "prompts/security_review.md"
  threat_model: "prompts/threat_modeling.md"

Agent Communication Protocols

Define how custom agents interact with the system:

# Agent communication interface
communication:
  input_formats:
    - "ospec_yaml"
    - "task_plan"
    - "code_artifact"
    - "security_report"
  
  output_formats:
    - "review_result"
    - "security_findings"
    - "approval_decision"
    - "remediation_plan"
  
  events:
    subscribes:
      - "code_generated"
      - "tests_completed" 
      - "deployment_requested"
    
    publishes:
      - "security_review_completed"
      - "vulnerabilities_found"
      - "approval_granted"

Guardrail Plugins

Custom Security Rules

Organization-specific security requirements:

# Plugin: @company/compliance-guardrails
plugin_type: "guardrails"
name: "company_compliance"
version: "1.0.0"

rules:
  - id: "data_classification"
    description: "Ensure data classification headers are present"
    type: "code_analysis"
    pattern: "class.*Model.*:"
    requires: "# @data-classification:"
    severity: "error"
  
  - id: "approved_databases"
    description: "Only approved databases allowed"
    type: "dependency_check"
    allowed_packages:
      - "psycopg2"  # PostgreSQL
      - "redis"     # Redis
    blocked_packages:
      - "mysql-connector-python"  # MySQL not approved
    severity: "error"
  
  - id: "encryption_required"
    description: "Sensitive data must be encrypted"
    type: "code_analysis"
    triggers:
      - pattern: "password|credit_card|ssn|api_key"
        requires: "encrypt|hash|cipher"
        context: "assignment"
    severity: "critical"

configuration:
  environments:
    development:
      enforcement_level: "warn"
    staging:
      enforcement_level: "error"
    production:
      enforcement_level: "block"

integration:
  ci_cd:
    - "github_actions"
    - "gitlab_ci"
    - "jenkins"
  
  ide:
    - "vscode"
    - "intellij"
    - "vim"

Quality Metrics Plugins

Custom quality measurements:

# Plugin: @company/quality-metrics
plugin_type: "guardrails"
name: "quality_metrics"

metrics:
  - name: "api_documentation_coverage"
    description: "Percentage of API endpoints with documentation"
    type: "documentation"
    target: 1.0
    threshold: 0.9
    
  - name: "error_handling_coverage"
    description: "Percentage of functions with proper error handling"
    type: "code_analysis"
    pattern: "def\\s+\\w+.*:"
    requires: "try:|raise|except:"
    target: 0.95
    threshold: 0.8
  
  - name: "performance_budget"
    description: "Bundle size under limits"
    type: "build_analysis"
    limits:
      javascript: "250KB"
      css: "50KB"
      images: "1MB"
    threshold: 0.9

Integration Plugins

External Tool Connectors

Connect OSpec with existing tools and workflows:

# Plugin: @ospec/jira-integration
plugin_type: "integration"
name: "jira_connector"
version: "1.0.0"

description: "Sync OSpec tasks with Jira issues"

configuration:
  connection:
    url: "${JIRA_URL}"
    username: "${JIRA_USERNAME}"
    api_token: "${JIRA_API_TOKEN}"
    project_key: "${JIRA_PROJECT_KEY}"

features:
  - "task_sync"
  - "progress_tracking"
  - "issue_linking"
  - "status_updates"

workflows:
  task_created:
    - create_jira_issue:
        issue_type: "Task"
        priority: "${task.priority}"
        description: "${task.description}"
        labels: ["ospec", "${ospec.id}"]
  
  task_completed:
    - update_jira_issue:
        status: "Done"
        resolution: "Done"
        comment: "Completed by OSpec agent"
  
  spec_deployed:
    - create_jira_issue:
        issue_type: "Deployment"
        summary: "Deployed ${ospec.name} v${ospec.version}"
        description: "Automated deployment via OSpec"

mapping:
  task_priorities:
    critical: "Highest"
    high: "High"
    medium: "Medium"
    low: "Low"
  
  task_types:
    setup: "Task"
    feature: "Story"
    bug: "Bug"
    security: "Security"

Monitoring Integration

Connect with observability platforms:

# Plugin: @ospec/datadog-monitoring
plugin_type: "integration"
name: "datadog_monitoring"

configuration:
  api_key: "${DATADOG_API_KEY}"
  app_key: "${DATADOG_APP_KEY}"
  site: "datadoghq.com"

monitoring:
  metrics:
    - name: "ospec.tasks.completed"
      type: "counter"
      tags: ["project", "agent_type"]
    
    - name: "ospec.build.duration"
      type: "histogram"
      tags: ["outcome_type", "stack"]
    
    - name: "ospec.tests.coverage"
      type: "gauge"
      tags: ["project", "test_type"]

  events:
    - trigger: "spec_created"
      title: "OSpec Created"
      text: "New OSpec ${ospec.name} created"
      tags: ["ospec", "creation"]
    
    - trigger: "deployment_successful"
      title: "Deployment Successful"
      text: "Successfully deployed ${ospec.name}"
      tags: ["ospec", "deployment", "success"]
    
    - trigger: "security_issue_found"
      title: "Security Issue Detected"
      text: "Security issue found in ${ospec.name}"
      tags: ["ospec", "security", "alert"]
      alert_type: "error"

dashboards:
  - name: "OSpec Overview"
    widgets:
      - type: "timeseries"
        metric: "ospec.tasks.completed"
        title: "Tasks Completed Over Time"
      - type: "query_value"
        metric: "avg:ospec.tests.coverage"
        title: "Average Test Coverage"

Template Plugins

Code Generation Templates

Customize how agents generate code:

# Plugin: @company/enterprise-templates
plugin_type: "templates"
name: "enterprise_patterns"
version: "1.0.0"

templates:
  api_controller:
    path: "templates/api/controller.ts.hbs"
    description: "Enterprise API controller with logging and validation"
    variables:
      - name: "controller_name"
        type: "string"
        required: true
      - name: "entity_name"  
        type: "string"
        required: true
      - name: "auth_required"
        type: "boolean"
        default: true
    
    context_providers:
      - "validation_schema"
      - "logging_config"
      - "auth_middleware"

  database_model:
    path: "templates/db/model.py.hbs"
    description: "Database model with audit fields and soft delete"
    variables:
      - name: "model_name"
        type: "string"
        required: true
      - name: "table_name"
        type: "string"
        required: true
      - name: "fields"
        type: "array"
        required: true
    
    post_processors:
      - "format_python"
      - "validate_model"
      - "generate_migrations"

patterns:
  - name: "service_layer"
    description: "Service layer with dependency injection"
    files:
      - template: "api_controller"
        output: "src/controllers/{{snake_case entity_name}}_controller.ts"
      - template: "service_class"
        output: "src/services/{{snake_case entity_name}}_service.ts"
      - template: "repository_interface"
        output: "src/repositories/{{snake_case entity_name}}_repository.ts"

configuration:
  template_engine: "handlebars"
  formatters:
    - "prettier"
    - "eslint --fix"
  
  helpers:
    - "case_converters"
    - "date_formatters"
    - "validation_helpers"

Template Context Providers

Inject dynamic context into templates:

# Context provider for database schemas
context_providers:
  database_schema:
    provider: "@company/schema-provider"
    configuration:
      connection: "${DATABASE_URL}"
      schema: "public"
    
    provides:
      - "table_definitions"
      - "relationship_mappings"
      - "constraint_information"
  
  api_documentation:
    provider: "@ospec/openapi-provider"
    configuration:
      spec_path: "./api/openapi.yaml"
    
    provides:
      - "endpoint_definitions"
      - "schema_definitions"
      - "authentication_schemes"

Workflow Plugins

Custom Automation Flows

Define organization-specific workflows:

# Plugin: @company/deployment-workflow
plugin_type: "workflow"
name: "enterprise_deployment"
version: "1.0.0"

workflow:
  name: "secure_deployment"
  description: "Enterprise deployment with approvals and rollback"
  
  triggers:
    - event: "implementation_completed"
      conditions:
        - all_tests_pass: true
        - security_scan_clean: true
        - coverage_threshold_met: true

  stages:
    - name: "pre_deployment_validation"
      type: "parallel"
      jobs:
        - name: "security_review"
          agent: "security_reviewer"
          timeout_minutes: 30
        
        - name: "performance_testing"
          agent: "performance_tester"
          timeout_minutes: 60
        
        - name: "compliance_check"
          agent: "compliance_checker"
          timeout_minutes: 15
    
    - name: "staging_deployment"
      type: "sequential"
      depends_on: ["pre_deployment_validation"]
      jobs:
        - name: "deploy_to_staging"
          agent: "deployment_agent"
          environment: "staging"
        
        - name: "smoke_tests"
          agent: "test_agent"
          test_suite: "smoke"
        
        - name: "integration_tests"
          agent: "test_agent"
          test_suite: "integration"
    
    - name: "approval_gate"
      type: "approval"
      depends_on: ["staging_deployment"]
      approvers:
        - role: "tech_lead"
        - role: "product_owner"
      timeout_hours: 24
    
    - name: "production_deployment"
      type: "sequential"
      depends_on: ["approval_gate"]
      jobs:
        - name: "backup_database"
          agent: "backup_agent"
        
        - name: "deploy_to_production"
          agent: "deployment_agent"
          environment: "production"
          strategy: "blue_green"
        
        - name: "health_check"
          agent: "monitoring_agent"
          checks: ["http_health", "database_connectivity", "external_services"]
        
        - name: "enable_monitoring"
          agent: "monitoring_agent"
          dashboards: ["application", "infrastructure", "business_metrics"]

  rollback:
    triggers:
      - health_check_failed: true
      - error_rate_high: true
      - manual_trigger: true
    
    procedure:
      - name: "stop_traffic"
        agent: "load_balancer_agent"
      - name: "restore_previous_version"
        agent: "deployment_agent"
      - name: "verify_rollback"
        agent: "monitoring_agent"
      - name: "notify_stakeholders"
        agent: "notification_agent"

Plugin Development

Plugin Structure

Standard structure for OSpec plugins:

my-plugin/
├── plugin.yaml           # Plugin manifest
├── README.md            # Documentation
├── src/                 # Source code
│   ├── index.ts        # Entry point
│   ├── handlers/       # Event handlers
│   └── templates/      # Code templates
├── tests/              # Test suite
├── docs/               # Documentation
└── examples/           # Usage examples

Plugin Manifest

# plugin.yaml
ospec_version: "1.0.0"
plugin_type: "outcome_type"
name: "my-custom-outcome"
version: "1.0.0"
description: "Custom outcome type for my organization"

author:
  name: "Development Team"
  email: "dev-team@company.com"

repository: "https://github.com/company/ospec-custom-outcome"
homepage: "https://docs.company.com/ospec-plugins/custom-outcome"

keywords:
  - "custom"
  - "enterprise"
  - "microservice"

dependencies:
  ospec_core: "^1.0.0"
  
dev_dependencies:
  "@types/node": "^18.0.0"
  "typescript": "^5.0.0"
  "jest": "^29.0.0"

engines:
  node: ">=18.0.0"
  ospec: ">=1.0.0"

files:
  - "dist/**"
  - "templates/**"
  - "schemas/**"
  - "README.md"

entry_points:
  main: "dist/index.js"
  types: "dist/index.d.ts"

configuration_schema: "schemas/config.schema.json"

Plugin API

TypeScript interface for plugin development:

// OSpec Plugin API
export interface OSpecPlugin {
  readonly name: string;
  readonly version: string;
  readonly type: PluginType;
  
  initialize(context: PluginContext): Promise<void>;
  configure(config: PluginConfig): Promise<void>;
  activate(): Promise<void>;
  deactivate(): Promise<void>;
}

export interface PluginContext {
  readonly ospecVersion: string;
  readonly runtime: RuntimeEnvironment;
  readonly logger: Logger;
  readonly eventBus: EventBus;
  readonly configManager: ConfigManager;
}

export interface OutcomeTypePlugin extends OSpecPlugin {
  validateSpec(spec: OSpecDocument): ValidationResult;
  getDefaultStack(spec: OSpecDocument): StackConfiguration;
  generateAcceptanceCriteria(spec: OSpecDocument): AcceptanceCriteria;
}

export interface StackPlugin extends OSpecPlugin {
  isCompatible(outcomeType: string, requirements: Requirements): boolean;
  getConfiguration(): StackConfiguration;
  generateProject(spec: OSpecDocument, config: ProjectConfig): Promise<GenerationResult>;
}

Plugin Registry

Publishing Plugins

Share plugins with the community:

# Publish to official registry
ospec plugin publish

# Publish to private registry
ospec plugin publish --registry https://registry.company.com

# Publish to npm (for Node.js plugins)
npm publish --registry https://registry.company.com

Plugin Discovery

Find and install plugins:

# Search for plugins
ospec plugin search kubernetes

# Install plugin
ospec plugin install @ospec/kubernetes-stack

# List installed plugins
ospec plugin list

# Update plugins
ospec plugin update

Plugin Security

Ensure plugin security:

registry:
  security:
    signature_verification: true
    allowed_publishers:
      - "@ospec/*"
      - "@company/*"
    
    code_scanning: true
    vulnerability_database: "npm-audit"
    
    sandbox_execution: true
    resource_limits:
      memory_mb: 512
      cpu_percent: 10
      network_access: "restricted"

This comprehensive plugin system allows OSpec to be extended and customized for any organization’s specific needs while maintaining security and compatibility.