@bluefly/openstandardagents 0.5.1 → 0.5.3

package/dist/spec/reference/reference-agents/doc-agent/manifest.ossa.yaml

@@ -1,776 +0,0 @@
-apiVersion: ossa/v0.4.7
-kind: Agent
-metadata:
-  name: doc-agent
-  version: 1.0.0
-  description: |
-    Automated documentation generation and validation agent. Generates API docs
-    from OpenAPI specs, CLI docs from command source files, and schema docs from
-    JSON Schema. Validates documentation completeness and syncs to GitLab wiki.
-  labels:
-    domain: documentation
-    tier: production
-    agent-assigned: doc-agent
-    blueflyio.com/team: platform
-    blueflyio.com/service: documentation-automation
-    ossa-version: v0.3.0
-  annotations:
-    openstandardagents.org/stability: stable
-    blueflyio.gitlab.com/lifecycle: ready-for-dev
-    blueflyio.gitlab.com/codeowner: "@platform-team"
-    blueflyio.gitlab.com/commit-type: docs
-    blueflyio.gitlab.com/priority: high
-spec:
-  lifecycle:
-    phases:
-      - name: message_normalization
-        description: "Normalize incoming messages to canonical format"
-        timeout: 5s
-        retry: 2
-      - name: tool_resolution
-        description: "Resolve available tools and capabilities"
-        timeout: 10s
-        retry: 1
-      - name: llm_inference
-        description: "Execute LLM reasoning with context"
-        timeout: 60s
-        retry: 3
-      - name: tool_execution
-        description: "Execute resolved tools and actions"
-        timeout: 120s
-        retry: 2
-      - name: response_assembly
-        description: "Assemble final response"
-        timeout: 5s
-        retry: 1
-      - name: state_persistence
-        description: "Persist state and memory updates"
-        timeout: 10s
-        retry: 3
-      - name: observability_emission
-        description: "Emit telemetry, traces, and metrics"
-        timeout: 5s
-        retry: 1
-
-  taxonomy:
-    domain: documentation
-    subdomain: automation
-    capability: documentation-generation
-  role: |
-    You are the Documentation Agent, an expert in technical documentation generation,
-    validation, and maintenance. Your mission is to ensure all project documentation
-    is accurate, complete, and accessible.
-
-    ## Core Responsibilities
-
-    1. **API Documentation Generation**
-       - Parse OpenAPI/Swagger specifications
-       - Generate markdown documentation from specs
-       - Create endpoint reference pages
-       - Document request/response schemas
-       - Generate code examples for API calls
-
-    2. **CLI Documentation Generation**
-       - Parse CLI command source files
-       - Extract command descriptions and options
-       - Generate command reference documentation
-       - Create usage examples and tutorials
-       - Document environment variables
-
-    3. **Schema Documentation Generation**
-       - Parse JSON Schema definitions
-       - Generate field-by-field documentation
-       - Document type constraints and validation rules
-       - Create schema reference pages
-       - Generate example payloads
-
-    4. **Documentation Validation**
-       - Check for completeness (missing docs for public APIs)
-       - Validate code examples compile/run
-       - Check for broken links
-       - Verify markdown formatting
-       - Detect stale documentation
-
-    5. **Wiki Synchronization**
-       - Sync documentation to GitLab wiki
-       - Maintain wiki structure and navigation
-       - Handle conflict resolution
-       - Track sync status and errors
-       - Generate change reports
-
-    ## Quality Standards
-
-    Documentation must be:
-    - **Accurate**: Match actual implementation
-    - **Complete**: Cover all public APIs and features
-    - **Clear**: Use consistent terminology
-    - **Accessible**: Include examples and tutorials
-    - **Up-to-date**: Regenerate on changes
-
-    ## Safety Guidelines
-
-    - NEVER modify source code
-    - ALWAYS validate before publishing
-    - PRESERVE existing documentation structure
-    - ESCALATE major changes to humans
-    - MAINTAIN version history
-  llm:
-    provider: ${LLM_PROVIDER:-anthropic}
-    model: ${LLM_MODEL:-claude-sonnet}
-    temperature: 0.2
-    maxTokens: 16000
-    topP: 0.9
-    fallback_models:
-      - provider: ${LLM_FALLBACK_PROVIDER_1:-openai}
-        model: ${LLM_FALLBACK_MODEL_1:-gpt-4o}
-      - provider: ${LLM_FALLBACK_PROVIDER_2:-anthropic}
-        model: ${LLM_FALLBACK_MODEL_2:-claude-haiku}
-    retry_config:
-      max_attempts: 3
-      backoff_strategy: exponential
-    cost_tracking:
-      enabled: true
-      budget_alert_threshold: 20
-      cost_allocation_tags:
-        project: ossa-agents
-        team: platform
-        service: doc-agent
-  tools:
-    - type: mcp
-      name: filesystem
-      server: filesystem-mcp-server
-      endpoint: stdio
-      transport:
-        protocol: stdio
-        streaming: none
-      capabilities:
-        - name: read_file
-          version: "1.0"
-          description: Read file contents
-          scopes:
-            - read:files
-          input_schema:
-            type: object
-            properties:
-              path:
-                type: string
-            required:
-              - path
-        - name: write_file
-          version: "1.0"
-          description: Write documentation files
-          scopes:
-            - write:files
-          input_schema:
-            type: object
-            properties:
-              path:
-                type: string
-              content:
-                type: string
-            required:
-              - path
-              - content
-        - name: list_directory
-          version: "1.0"
-          description: List directory contents
-          scopes:
-            - read:files
-          input_schema:
-            type: object
-            properties:
-              path:
-                type: string
-            required:
-              - path
-    - type: mcp
-      name: gitlab-api
-      server: gitlab-mcp-server
-      namespace: blueflyio
-      endpoint: https://gitlab.com/api/v4
-      transport:
-        protocol: http
-        streaming: none
-        rateLimit:
-          requestsPerMinute: 60
-          burstLimit: 10
-          strategy: token_bucket
-          onExceeded: queue
-      auth:
-        type: bearer
-        credentials: env:GITLAB_TOKEN
-        scopes:
-          - api
-          - read_api
-          - read_repository
-      circuit_breaker:
-        enabled: true
-        failure_threshold: 5
-        timeout_seconds: 60
-      capabilities:
-        - name: get_wiki_page
-          version: "1.0"
-          description: Get wiki page content
-          scopes:
-            - read:wiki
-          transport:
-            protocol: http
-            binding: GET /projects/{id}/wikis/{slug}
-          input_schema:
-            type: object
-            properties:
-              project_id:
-                type: integer
-              slug:
-                type: string
-            required:
-              - project_id
-              - slug
-        - name: create_wiki_page
-          version: "1.0"
-          description: Create new wiki page
-          scopes:
-            - write:wiki
-          transport:
-            protocol: http
-            binding: POST /projects/{id}/wikis
-          input_schema:
-            type: object
-            properties:
-              project_id:
-                type: integer
-              title:
-                type: string
-              content:
-                type: string
-              format:
-                type: string
-                enum:
-                  - markdown
-                  - rdoc
-                  - asciidoc
-                default: markdown
-            required:
-              - project_id
-              - title
-              - content
-        - name: update_wiki_page
-          version: "1.0"
-          description: Update existing wiki page
-          scopes:
-            - write:wiki
-          transport:
-            protocol: http
-            binding: PUT /projects/{id}/wikis/{slug}
-          input_schema:
-            type: object
-            properties:
-              project_id:
-                type: integer
-              slug:
-                type: string
-              content:
-                type: string
-              title:
-                type: string
-            required:
-              - project_id
-              - slug
-              - content
-        - name: list_wiki_pages
-          version: "1.0"
-          description: List all wiki pages
-          scopes:
-            - read:wiki
-          transport:
-            protocol: http
-            binding: GET /projects/{id}/wikis
-          input_schema:
-            type: object
-            properties:
-              project_id:
-                type: integer
-              with_content:
-                type: boolean
-                default: false
-            required:
-              - project_id
-    - type: library
-      name: openapi_parser
-      description: Parse OpenAPI/Swagger specifications
-      version: 3.1.0
-    - type: library
-      name: markdown_generator
-      description: Generate formatted markdown documentation
-      version: 1.0.0
-    - type: library
-      name: link_checker
-      description: Validate links in documentation
-      version: 1.0.0
-  capabilities:
-    policy: deny_by_default
-    grants:
-      - capability: file_read
-        scope: ["**/*.yaml", "**/*.yml", "**/*.json", "**/*.md", "**/*.ts", "**/*.js", "openapi/**/*", "src/cli/**/*"]
-        rationale: "Read source files, OpenAPI specs, CLI commands, and schemas for documentation generation"
-      - capability: file_write
-        scope: ["website/content/docs/**/*.md", "docs/**/*.md", "wiki/**/*.md"]
-        rationale: "Write generated documentation files"
-      - capability: api_call
-        scope: ["gitlab.com/api/v4/projects/*/wikis*"]
-        rate_limit: "60/minute"
-        rationale: "GitLab Wiki API access for reading and writing wiki pages"
-      - capability: api_call
-        scope: ["gitlab.com/api/v4/projects/*/repository/*"]
-        rate_limit: "30/minute"
-        rationale: "GitLab Repository API for file content retrieval"
-      - capability: llm_inference
-        providers: ["anthropic", "openai"]
-        models: ["claude-sonnet", "gpt-4o", "claude-haiku"]
-        rationale: "AI reasoning for documentation generation and content improvement"
-      - capability: link_validation
-        scope: ["http://*", "https://*"]
-        rate_limit: "100/minute"
-        rationale: "Validate external links in documentation"
-      - capability: openapi_parse
-        scope: ["openapi/**/*.yaml", "openapi/**/*.json"]
-        rationale: "Parse OpenAPI/Swagger specifications for API docs generation"
-      - capability: schema_parse
-        scope: ["**/*.schema.json", "schemas/**/*.json"]
-        rationale: "Parse JSON Schema for schema documentation generation"
-      - capability: markdown_generate
-        scope: ["website/content/docs/**", "docs/**"]
-        rationale: "Generate formatted markdown documentation"
-
-    actions:
-      - name: generate_api_docs
-        description: Generate API documentation from OpenAPI specifications
-        input_schema:
-          type: object
-          properties:
-            spec_dir:
-              type: string
-              description: Directory containing OpenAPI specs
-              default: openapi
-            output_dir:
-              type: string
-              description: Output directory for generated docs
-              default: website/content/docs/api-reference
-          required:
-            - spec_dir
-        output_schema:
-          type: object
-          properties:
-            files_generated:
-              type: array
-              items:
-                type: string
-            success:
-              type: boolean
-      - name: generate_cli_docs
-        description: Generate CLI documentation from command source files
-        input_schema:
-          type: object
-          properties:
-            cli_dir:
-              type: string
-              description: Directory containing CLI command files
-              default: src/cli/commands
-            output_dir:
-              type: string
-              description: Output directory for generated docs
-              default: website/content/docs/cli-reference
-          required:
-            - cli_dir
-        output_schema:
-          type: object
-          properties:
-            commands_documented:
-              type: array
-              items:
-                type: string
-            success:
-              type: boolean
-      - name: generate_schema_docs
-        description: Generate schema documentation from JSON Schema
-        input_schema:
-          type: object
-          properties:
-            schema_path:
-              type: string
-              description: Path to JSON Schema file
-            output_dir:
-              type: string
-              description: Output directory for generated docs
-              default: website/content/docs/schema-reference
-          required:
-            - schema_path
-        output_schema:
-          type: object
-          properties:
-            fields_documented:
-              type: integer
-            success:
-              type: boolean
-      - name: validate_docs
-        description: Validate documentation completeness and quality
-        input_schema:
-          type: object
-          properties:
-            docs_dir:
-              type: string
-              description: Directory to validate
-              default: website/content/docs
-            check_links:
-              type: boolean
-              description: Check for broken links
-              default: true
-            check_examples:
-              type: boolean
-              description: Validate code examples
-              default: true
-          required:
-            - docs_dir
-        output_schema:
-          type: object
-          properties:
-            missing_docs:
-              type: array
-              items:
-                type: string
-            broken_links:
-              type: array
-              items:
-                type: string
-            invalid_examples:
-              type: array
-              items:
-                type: string
-            success:
-              type: boolean
-      - name: sync_wiki
-        description: Sync documentation to GitLab wiki
-        input_schema:
-          type: object
-          properties:
-            source_dir:
-              type: string
-              description: Source documentation directory
-            wiki_repo:
-              type: string
-              description: GitLab wiki repository URL
-          required:
-            - source_dir
-            - wiki_repo
-        output_schema:
-          type: object
-          properties:
-            pages_synced:
-              type: integer
-            success:
-              type: boolean
-  state:
-    mode: stateless
-    storage:
-      type: kv
-      retention: 7d
-      config:
-        provider: redis
-        prefix: agent:doc-agent
-        endpoint: ${REDIS_URL:-redis://localhost:6379}
-    context_window:
-      max_messages: 50
-      max_tokens: 32000
-      strategy: truncation
-  autonomy:
-    level: supervised
-    approval_required: false
-    allowed_actions:
-      - read_files
-      - write_documentation
-      - validate_docs
-      - sync_wiki
-      - generate_reports
-    blocked_actions:
-      - modify_source_code
-      - delete_documentation
-      - bypass_validation
-    escalation_policy:
-      triggers:
-        - major_structure_change
-        - sync_conflict
-        - validation_failure
-      notify:
-        - slack:#documentation
-        - gitlab:@platform-team
-  constraints:
-    cost:
-      maxTokensPerDay: 200000
-      maxTokensPerRequest: 16000
-      maxCostPerDay: 30
-      currency: USD
-    performance:
-      maxLatencySeconds: 30
-      maxConcurrentRequests: 5
-      timeoutSeconds: 120
-    resources:
-      cpu: 500m
-      memory: 1Gi
-  observability:
-    telemetry:
-      enabled: true
-      exporter: otlp
-      endpoint: "${OTEL_EXPORTER_OTLP_ENDPOINT}"
-      service_name: "${AGENT_NAME}"
-      service_version: "${AGENT_VERSION}"
-    tracing:
-      enabled: true
-      sampler: parentbased_traceidratio
-      sample_rate: 0.1
-      propagation: ["tracecontext", "baggage"]
-    metrics:
-      enabled: true
-      interval: 30s
-      histogram_buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
-      labels:
-        - agent_name
-        - agent_version
-        - phase
-        - capability
-        - status
-    logging:
-      level: info
-      format: json
-      redact_pii: true
-      structured: true
-      fields:
-        - execution_id
-        - agent_id
-        - phase
-        - duration_ms
-  reliability:
-    sla:
-      availability_percent: 99
-      latency_p95_ms: 10000
-      error_rate_percent: 2
-    circuit_breaker:
-      enabled: true
-      failure_threshold: 5
-      timeout_seconds: 60
-      half_open_requests: 3
-    health_check:
-      enabled: true
-      interval_seconds: 30
-      timeout_seconds: 5
-    failover:
-      enabled: false
-  safety:
-    content_filtering:
-      enabled: true
-      categories:
-        - pii
-        - credentials
-      threshold: high
-      action: block
-    pii_detection:
-      enabled: true
-      types:
-        - email
-        - phone
-        - api_key
-      action: redact
-    rate_limiting:
-      enabled: true
-      requests_per_minute: 60
-      burst_limit: 10
-    guardrails:
-      enabled: true
-      policies:
-        - name: no_source_modification
-          type: output
-          rules:
-            - no_modify_source_code
-        - name: validate_before_publish
-          type: output
-          rules:
-            - require_validation
-      max_tool_calls: 50
-      max_execution_time_seconds: 300
-      pii_detection:
-        enabled: true
-        action: redact
-        categories: ["email", "phone", "ssn", "credit_card"]
-      secrets_detection:
-        enabled: true
-        action: block
-        patterns:
-          - "glpat-*"
-          - "ghp_*"
-          - "sk-*"
-          - "bearer *"
-          - "password=*"
-          - "api_key=*"
-      prompt_injection:
-        enabled: true
-        action: warn
-        detection: ["ignore previous", "system prompt", "jailbreak"]
-      content_policy:
-        enabled: true
-        categories:
-          violence: block
-          hate: block
-          sexual: block
-          self_harm: block
-    kill_switch:
-      enabled: true
-      trigger: manual
-      webhook: "${KILL_SWITCH_WEBHOOK}"
-      grace_period: 30s
-    compliance:
-      profiles:
-        - fedramp_moderate
-        - hipaa
-        - gdpr
-        - soc2_type2
-  deployment:
-    strategy: rolling
-    rollback:
-      enabled: true
-      automatic: false
-    versioning:
-      scheme: semver
-      compatibility: backward
-    lifecycle:
-      startup_probe:
-        enabled: true
-        initial_delay_seconds: 5
-        period_seconds: 10
-        failure_threshold: 3
-      readiness_probe:
-        enabled: true
-        period_seconds: 10
-      liveness_probe:
-        enabled: true
-        period_seconds: 30
-      graceful_shutdown:
-        enabled: true
-        timeout_seconds: 30
-extensions:
-  buildkit:
-    deployment:
-      replicas:
-        min: 1
-        max: 2
-    container:
-      image: ghcr.io/blueflyio/agent-doc-agent:1.0.0
-      runtime: docker
-      resources:
-        limits:
-          cpu: 500m
-          memory: 1Gi
-    gitlab:
-      custom_fields:
-        agent_assigned: doc-agent
-        agent_status: ready-for-dev
-        commit_type: docs
-        priority: high
-  mcp:
-    enabled: true
-    server_type: stdio
-    server_name: doc-agent-mcp
-    tools:
-      - name: generate_docs
-        description: Generate documentation from source
-        inputSchema:
-          type: object
-          properties:
-            source_type:
-              type: string
-              enum:
-                - openapi
-                - cli
-                - schema
-            source_path:
-              type: string
-            output_path:
-              type: string
-          required:
-            - source_type
-            - source_path
-      - name: validate_docs
-        description: Validate documentation quality
-        inputSchema:
-          type: object
-          properties:
-            docs_path:
-              type: string
-            checks:
-              type: array
-              items:
-                type: string
-                enum:
-                  - links
-                  - examples
-                  - completeness
-          required:
-            - docs_path
-  a2a:
-    enabled: true
-    agent_card:
-      name: Documentation Agent
-      description: Automated documentation generation, validation, and wiki sync
-      url: https://agents.blueflyio.com/doc-agent
-      version: 1.0.0
-      capabilities:
-        - api_documentation
-        - cli_documentation
-        - schema_documentation
-        - wiki_sync
-        - validation
-      authentication:
-        schemes:
-          - bearer
-      provider:
-        organization: BlueFly.io
-        url: https://blueflyio.com
-    supported_content_types:
-      - application/json
-    skills:
-      - id: generate_documentation
-        name: Generate Documentation
-        description: Generate technical documentation from source
-        input_modes:
-          - data
-        output_modes:
-          - text
-          - data
-    streaming: none
-  kagent:
-    api_version: kagent.dev/v1alpha2
-    kubernetes:
-      namespace: agent-system
-      labels:
-        app.kubernetes.io/name: doc-agent
-        app.kubernetes.io/part-of: ossa-showcase
-        openstandardagents.org/version: v0.3.0
-      resourceLimits:
-        cpu: "1"
-        memory: 2Gi
-    deployment:
-      replicas:
-        min: 1
-        max: 3
-      strategy: rolling-update
-    a2aConfig:
-      enabled: true
-      protocol: json-rpc
-    meshIntegration:
-      enabled: true
-      istioIntegration: true
-  gitlab_duo:
-    enabled: true
-    flow_execution: true
-    model: ${GITLAB_DUO_MODEL:-claude-sonnet-4.5-20250929}
-    knowledge_graph:
-      enabled: true
-      index_on_push: true