Workflow

1. Anatomi sebuah workflow

Empat sisi: trigger (kapan), action (apa), env (config + secret), data tables (state lookup). Notifikasi success/failure = explicit action node di graph (tidak ada field notify: terpisah). Plus governance (approve, guard). Engine impl pakai istilah "graph" / "node" / "DAG" — accurate di technical level (lihat §6).

<BaseDir>/workflows/support-triage/
├─ workflow.yaml           # graph + triggers + env schema
├─ env.yaml                # values (UI-managed, secret encrypted)
├─ README.md
├─ nodes/                # per-node assets (opsional)
│  ├─ classify-intent.md   # prompt buat classify node
│  ├─ format-answer.md     # prompt buat agent node
│  └─ enrich-user.sql      # query buat db_query node
├─ __tests__/            # fixture per node
│  └─ classify-intent.json
└─ runs/                 # state per run (auto-managed)
   └─ 01938...uuid/
      ├─ state.json        # snapshot
      ├─ events.jsonl      # append-only log
      └─ nodes/          # output cache per node

# Schema + data live in Postgres, managed via UI tab:
TABLE wick_data_tables
  WHERE slug = 'processed-events'
  # columns: slug, name, schema JSONB,
  #          access JSONB, retention JSONB, ...

TABLE wick_data_table_rows
  WHERE table_slug = 'processed-events'
  # composite PK (table_slug, pk)
  # data JSONB validated app-layer

3. Canvas editor — live demo

Drag node dari palette, sambungin edge, klik node buat edit. Drawflow (vanilla JS, ~28KB) cocok dengan stack wick (templ + tailwind + vanilla JS).

id: 0193e2b4-6c20-7a5f-...
name: Slack Support Triage
enabled: true

triggers:
  - id: trigger-channel-slack
    type: channel
    entry_node: classify-intent
    channel: slack
    target: "#support"
    match:
      mention_bot: true

graph:
  # entry/edges populated by canvas; graph.entry is a legacy
  # fallback only for hand-edited YAML without per-trigger entry_node.
  nodes:
    - id: classify-intent
      type: classify
      preset: classifier-cheap
      prompt: |
        Klasifikasi pesan support berikut.
        Pesan: {{.Event.Payload.text}}
        Jawab: bug | question | feature | other
      cases:
        bug: handle-bug
        question: handle-question
        feature_request: handle-feature
        default: silent-end

    - id: handle-bug
      type: skill
      skill: create-linear-ticket
      args:
        title: "{{.Event.Payload.text | truncate 80}}"
        project: SUPPORT
      next: reply-link

↑ Live Drawflow demo. Drag node, drag dari satu output ke input lain. (Read-only di mockup ini — production version full editable.)

5. Reliable AI classification

LLM ga deterministik — output bisa "Bug.", "I think this is bug", atau "bug_report". Wick handle lewat 6 lapis defense. Default sudah agresif (layer 1-3 active), sisanya opt-in.

{
  "name": "classify_response",
  "input_schema": {
    "type": "object",
    "properties": {
      "verdict": {
        "type": "string",
        "enum": ["bug", "question",
                 "feature_request", "other"]
      },
      "confidence": {"type": "number"},
      "reasoning": {"type": "string"}
    },
    "required": ["verdict"]
  }
}

examples:
  - input: "ada bug di chat widget"
    output: bug
  - input: "gimana cara connect?"
    output: question
  - input: "tolong tambahin dark mode"
    output: feature_request

5.1 Structured output via CLI (bukan API SDK)

Wick agent jalan via subprocess internal/agents/provider/ — claude, codex, gemini adalah CLI binary, bukan API SDK call. Beda penting buat reliability strategy.

type Provider interface {
  Name() string
  // ... existing agent methods

  // New for classify-style nodes:
  StructuredCall(ctx, prompt, schema, opts)
    (StructuredResult, error)
}

type StructuredResult struct {
  Raw    string          // stdout CLI
  Parsed map[string]any  // JSON-parsed
  OK     bool            // parse + validate
  Error  string
  Usage  Usage                // tokens, cost
}

5.2 Result inspection — "AI bilang apa, kenapa?"

User butuh tau alasan AI mutusin verdict tertentu. confidence + reasoning wajib di-surface di UI run timeline + audit page.

{
  "verdict": "bug",
  "confidence": 0.92,
  "reasoning": "mentions production error
                 and widget breakage"
}

5.3 Cost cap — defense terhadap channel spam

Classify call = subprocess CLI + LLM tokens. Channel-rame workflow bisa nuclear cost. Three-layer defense:

# workflow.yaml — apply cost cap
env:
  - name: MAX_DAILY_CLASSIFY_TOKENS
    widget: number
    default: 100000      # cap budget for spam protection

graph:
  nodes:
    - id: classify-intent
      type: classify
      cache_ttl_sec: 3600           # reuse classification 1h
      prompt: |
        ...
      cases:
        ...
        default: silent-end     # fires kalau budget exceeded

5.4 Skill discovery per provider

Skill = capability bundle spesifik per provider (Claude Code skill, Codex skill, Gemini skill). Wick query provider buat list, AI/UI tampilin sebagai checklist di agent node Inspector.

type Provider interface {
  Name() string
  Capabilities() Capabilities
  StructuredCall(...) (...)

  // NEW: skill catalog discovery
  ListSkills(ctx) ([]Skill, error)
}

type Skill struct {
  Name        string     // "weekly-sync"
  Description string
  InputSchema map[string]any
  Source      string     // builtin | bundle
}

5.5 Session management — CLI subprocess reuse

CLI spawn ~500ms-1s overhead. Workflow dgn 5 agent node = 5× spawn kalau setiap node fresh. Field session: per node control behavior.

- id: classify-intent
  type: classify
  session: new           # default, classify independent

- id: deep-analysis
  type: agent
  session: root          # share context dgn root nodes lain
  ...

- id: ongoing-monitor
  type: agent
  session: persistent    # context bawa dari run sebelumnya
  ...

7. Channel registry — generic interface

Channel (slack/telegram/rest/whatsapp/email) bukan hardcoded di workflow. Workflow konsumsi lewat registry self-describing — channel daftarin trigger spec + action spec, workflow auto-discover.

type Channel interface {
  Name() string
  IsConfigured() bool

  // Inbound: trigger schema
  TriggerSpecs() []TriggerSpec

  // Outbound: invoked via workflow node type: channel
  Actions() []ActionSpec
  Send(ctx, action, args) (any, error)

  // Event push to router
  Subscribe(handler EventHandler)
}

triggers:
  - type: channel
    channel: slack
    event: message
    match_enabled: true   # gate; false = dump-all
    match:
      mode: whitelist
      channel_id: '[{"id":"C123","name":"general"}]'
      text_contains: "support"

- id: reply-with-link
  type: channel            # same module as trigger
  channel: slack
  op: reply_thread     # one of channel.Actions()
  args:
    channel: "{{.Event.Payload.channel_id}}"
    thread:  "{{.Event.Payload.thread}}"
    text: "Tracked: {{.Node.ticket.url}}"

9. Data Tables — cross-workflow data store

Workflow butuh state lookup beyond single run: "udah handle event ini?", "user opt-out?", "cache enrichment yang masih fresh?". Data Tables = standalone tool (internal/tools/data-tables/), schema-aware, MCP-discoverable, UI table view built-in (n8n-style). Sejajar Workflows / Workspaces / Presets / Providers / Channels.

TABLE wick_data_tables (
  slug          TEXT PRIMARY KEY,
  name          TEXT NOT NULL,
  description   TEXT,
  schema        JSONB NOT NULL,   # columns + indexes
  access        JSONB NOT NULL,   # allowlist + flags
  retention     JSONB,            # ttl_days, by_column
  created_by    TEXT,
  created_at    TIMESTAMPTZ,
  updated_at    TIMESTAMPTZ
);

# Optional audit (opt-in via access.audit_changes):
TABLE wick_data_table_audit (
  id, table_slug, op, actor, diff, at
);

wick database (existing, same as
configs / jobs / sessions / connectors)

TABLE wick_data_table_rows (
  table_slug    TEXT NOT NULL,
  pk            TEXT NOT NULL,
  data          JSONB NOT NULL,
  created_at    TIMESTAMPTZ DEFAULT now(),
  updated_at    TIMESTAMPTZ DEFAULT now(),
  PRIMARY KEY (table_slug, pk)
);

-- Partial functional index per table:
CREATE INDEX idx_events_status
  ON wick_data_table_rows ((data->>'status'))
  WHERE table_slug = 'events';

Schema migration

# wick_data_tables.schema (JSONB)
{
  "columns": [
    { "name": "event_id", "type": "string",
      "primary_key": true },
    { "name": "status", "type": "enum",
      "options": ["received", "done"] },
    { "name": "priority", "type": "enum",
      "options": ["low", "med", "high"] }
  ],
  "strictness": "strict"
}

# Audit row (opt-in):
INSERT INTO wick_data_table_audit
  (op, actor, diff, ...) VALUES ('schema_change', ...);

UI Audit log (opt-in)

# wick_data_tables row
slug: processed-events
name: "Processed channel events"

schema:
  columns:
    - { name: event_id, type: string,
        primary_key: true }
    - { name: workflow_slug, type: string,
        indexed: true }
    - { name: handled_at, type: timestamp,
        indexed: true }
    - { name: result, type: json }
  indexes:
    - [workflow_slug, handled_at]
  strictness: strict

retention:
  ttl_days: 90
  by_column: handled_at

access:
  workflows: [support-triage]
  ui_editable: true
  mcp_writable: true
  audit_changes: false

data_tables:
  - name: events            # alias
    ref: events
    mode: read_write

graph:
  entry: check-handled
  nodes:
    - id: check-handled
      type: datatable_exists
      table: events
      where:
        id: "{{.Event.Payload.event_id}}"
        is_processed: true
      cases:
        "true": end           # already done
        "false": process

    - id: process
      ...
      next: mark-done

    - id: mark-done
      type: datatable_upsert
      table: events
      key: [id]
      row:
        id: "{{.Event.Payload.event_id}}"
        status: done
        is_processed: true
        handled_at: "{{.Run.StartedAt}}"

UI Data Tables tab — 3-panel

where workflow_slug = 'support-triage'
order_by handled_at desc
limit 100

Akses lewat expose function only — no raw SQL

Data table di wick's DB tapi ga di-query bebas via db_query. Akses cuma lewat datatable_* node types, MCP ops, UI Data Tables tab, atau Service interface internal Go.

datatable_list()
datatable_get(slug)
datatable_create(slug, schema)
datatable_update_schema(slug, patch)
datatable_drop(slug)
datatable_infer_schema(slug)
datatable_export(slug, format)
datatable_import(bundle, on_conflict)

datatable_query(slug, where, ...)
datatable_insert(slug, row)
datatable_upsert(slug, row)
datatable_delete(slug, where)
datatable_count(slug, where)

type Service interface {
  List() ([]Table, error)
  Get(slug string) (Table, error)
  Create(t Table) error
  UpdateSchema(slug, patch SchemaPatch) error
  Drop(slug string) error

  Query(slug, q Query) (QueryResult, error)
  Insert(slug, row map[string]any) (any, error)
  Upsert(slug, key []string, row ...) (UpsertResult, error)
  Delete(slug, where Where) (int64, error)
  Count(slug, where Where) (int64, error)
}

Sharing antar workflow — first-class

Share data table = use case utama (dedup events, cross-workflow state, shared lookup). Safety dari explicit contract.

# wick_data_tables.schema
{
  "strictness": "strict",         # layer 1
  "columns": [
    { "name": "id", "type": "string",
      "primary_key": true },
    { "name": "source", "type": "enum", ... },
    { "name": "status", "type": "enum", ... }
  ]
}

# wick_data_tables.access
{
  "workflows": [             # layer 2: allowlist
    "webhook-handler",
    "calendar-poller",
    "slack-monitor"
  ],
  "read_only_workflows": ["audit-monthly"],
  "row_filter": "none"          # layer 3: by_creator opt-in
}

data_tables:
  - name: events            # alias
    ref: events
    mode: read_write

Strictness modes

Migration safety — preview, dry-run, atomic, rollback

Schema change yg sentuh existing rows = formal flow dgn manual user trigger di tiap step. Never auto-magic.

CSV upload (n8n parity)

Adoption + export/import flows

Engine detect orphan rows
  ↓
UI list page: "Orphan table" badge + row count
  ↓
Klik → adoption modal:
  ├─ [Adopt] → sample N rows, infer schema dari
  │            JSONB keys. User review + edit + save.
  └─ [Drop] → DELETE rows (typed confirmation)

events.tar.gz
├─ schema.json          # schema + access + retention
└─ rows.jsonl           # ordered by pk

wick datatable import events.tar.gz \
  --on-conflict abort
  # abort | overwrite | skip | merge

12. AI bikin workflow — local vs remote

Workflow editing dirancang biar AI dari mana saja bisa bikin/edit, ga peduli punya file tool atau tidak. MCP server di /mcp (HTTP + bearer) = single source of truth.

Tier 1 — Introspection (read-only)

workflow_workspace()
  → entry point, base_dir, schemas
workflow_node_types()
  → [{type, schema, example, when_to_use}]
workflow_trigger_types()
  → trigger schema catalog
workflow_channels()
  → channel registry self-describe
workflow_connectors()
  → connector modules + rows + ops
workflow_skills()
  → local Claude Code skill bundles only

workflow_list(filter)
  → [{slug, id, name, enabled, approved}]
workflow_get(slug)
  → full workflow definition
workflow_list_files(slug)
  → [{path, size, modified}]
workflow_read_file(slug, path)
  → content (replace Read tool for remote AI)

Tier 2 — Write (state-mutating)

workflow_create(slug, template?)
workflow_write_file(slug, path, content)
workflow_delete_file(slug, path)
workflow_delete(slug)

workflow_add_node(slug, node)
workflow_update_node(slug, id, patch)
workflow_delete_node(slug, id)
workflow_connect(slug, from, to, case?)
workflow_disconnect(slug, from, to)
workflow_move_node(slug, id, x, y)
workflow_set_triggers(slug, triggers[])
workflow_toggle(slug, enabled)

Tier 3 — Action (validate, simulate, test, run, approve)

workflow_validate(slug)
workflow_simulate(slug, event)
workflow_test(slug)
workflow_run_now(slug, event?)

workflow_get_runs(slug, limit)
workflow_get_run(slug, run_id)
workflow_request_review(slug, msg)
workflow_capture_fixture(slug, run_id, node)

Pattern per environment

HTTP MCP transport — setup buat remote AI

POST https://wick.your-host.com/mcp
Authorization: Bearer wick_token_...
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "workflow_add_node",
    "arguments": {
      "slug": "support-triage",
      "node": {...}
    }
  },
  "id": 1
}

mcpServers:
  wick:
    url: https://wick.host.com/mcp
    headers:
      Authorization: Bearer wick_token_...

Token scoping per use case

Scope di-assign saat token issuance. Default AI assistant = write-without-enable + wajib panggil workflow_request_review. Admin approve via UI (lihat §13 AI guard).

14. Security model

Workflow boleh exec arbitrary code dan call external — surface area besar. Multi-layer defense.