Proposal: Adopt Mermaid.js for standardized Hyperautomation & response workflow documentation + community library

[jacob-kraniak]

Hyperautomation Workflow Documentation Standard (Proposed Addition to README.md)

To improve clarity and collaboration on complex response playbooks, we adopt Mermaid.js as the standardized format for documenting workflows — especially Hyperautomation scenarios.

Why Mermaid?

• Native rendering in GitHub (no external tools needed)
• Version-controlled alongside code and metadata
• Easy to read/maintain as automations grow in complexity
• Supports flowcharts, sequence diagrams, and state machines

All new or updated workflows in workflows/community/ should include:

• A Mermaid diagram in the accompanying .md documentation file
• Updated metadata.yaml (with optional hyperautomation fields for now)

Example: Hyperautomation – Automated Threat Intel Enrichment Playbook

flowchart TD
    A[Singularity Alert Trigger] --> B[Workflow Engine Receives Event]
    B --> C{Enrichment Required?}
    C -->|Yes| D[Query External Threat Intel Sources]
    D --> E[Apply Scoring & Tagging Logic]
    E --> F[Update Case / Add Evidence in Singularity]
    F --> G[Notify Analyst if High Severity]
    G --> H[Log Execution for Audit & Improvement]

Loading

Accompanying metadata.yaml (placed next to the workflow file)

metadata_details:
  purpose: "Automated enrichment of suspicious indicators using multiple threat intel sources via Hyperautomation patterns"
  trigger_type: "alert"
  integration_dependency: "Multiple TI feeds, Singularity Case Management"
  expected_actions_per_run: 8
  human_in_the_loop: false
  required_products: ["Singularity Platform"]
  tags: ["enrichment", "hyperautomation", "threat-intel"]
  version: "v1.0"
  documentation: "mermaid"