@bluefly/openstandardagents 0.3.3 → 0.3.6

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

@@ -0,0 +1,776 @@
+apiVersion: ossa/v0.3.5
+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