Skip to content
Guida

Workflows

A workflow is a named subfolder inside workflows/ that groups related scripts, event triggers, worker pools, MCP tools, and queue views into a self-contained automation unit. Workflows let you run multiple pipelines within a single workspace without them interfering with each other.

For long-running workflows, Guida can also maintain a durable Workflow Ledger with runs, items, stages, states, events, artifacts, leases, retries, and recovery actions.

Folder Structure

Section titled “Folder Structure”

Workflows live under workflows/ in your workspace. The folder’s existence declares the workflow — no separate manifest needed:

my-workspace/
  scripts/              # Global scripts
  lib/                  # Shared libraries
  views/                # Global queue views
  events.json           # Global triggers
  queues.json           # Global worker pools
  tools.json            # Global MCP tools
  store.db              # Shared document store
  queue.db              # Shared work queues
  workflow-ledger.db    # Shared workflow run/item history
  search-index/         # Shared search index
  workflows/
    job-validation/
      events.json       # Active only when this workflow is selected
      queues.json       # Active only when this workflow is selected
      tools.json        # Active only when this workflow is selected
      views/
        review.json
      scripts/
        enqueue.js
        check.js
    rss-pipeline/
      events.json
      scripts/
        scrape.js

Two-Tier Loading

Section titled “Two-Tier Loading”

Guida loads configuration in two tiers:

  1. Global — root-level events.json, queues.json, tools.json, and views/ are always active regardless of which workflow is selected.
  2. Workflow — the active workflow’s configs are loaded on top of the global layer.

Only one workflow is active at a time. Global configs are never affected by workflow changes.

Switching Workflows

Section titled “Switching Workflows”

Select a workflow from the toolbar dropdown (visible when the workspace has a workflows/ directory). Choose “None” to run with global-only configs.

You can also switch from scripts or MCP:

// From a script
g.workflows.switch("job-validation");

When you switch workflows:

  • The previous workflow’s triggers are deactivated
  • The previous workflow’s worker pools are stopped (in-flight items finish)
  • The new workflow’s triggers and workers are activated
  • Global configs remain unchanged

Creating a Workflow

Section titled “Creating a Workflow”

Right-click in the Workspace pane and select New Workflow. Enter a name, optionally choose a template:

  • Blank — empty workflow folder with scripts/
  • Scraper — event trigger + worker pool + queue view
  • Monitor — URL-match triggers for watching pages
  • Processor — queue-based pipeline with views

Shared Resources

Section titled “Shared Resources”

All workflows in a workspace share the same data layer:

  • Store (store.db) — same document store across all workflows
  • Queues (queue.db) — queues are shared; workflows can process each other’s queue items
  • Workflow Ledger (workflow-ledger.db) — run/item history is shared and scoped by workflow name
  • Search Index — shared full-text index
  • Shared Libraries — use standard import (JS), require() (Lua), or (import ...) (Janet) to share code between scripts. Global libraries in the workspace root lib/ folder are also available.

This means a scraping workflow can enqueue items that a processing workflow picks up — no data copying needed.

Workflow Control Console

Section titled “Workflow Control Console”

The Workflow Control Console is the operator view for large workspaces where many workflow folders, crawler modules, queues, and ledger stages belong to one real-world operation.

Open it from View > Workflow Control Console. It does not replace the Queue Console or Workflow Ledger Console. Instead, it gives the operator one place to answer:

  • What operation is this workspace trying to run?
  • Is the active workflow correct?
  • Is there an entry script, or is this operation only resumable/inspectable?
  • Which queues and worker pools are expected?
  • Which phase, module, or handoff needs attention?
  • Where should I drill in next: queue, ledger, runbook, or script?

The console is evidence-driven. It links to queue and ledger detail when it has a useful queue, stage, state, quick filter, or search term. It avoids pretending that ledger-only state is executable queue work.

workflow-operations.json

Section titled “workflow-operations.json”

Create workflows/workflow-operations.json to describe operator-level operations. Fields are optional unless your operation needs them; a minimal operation can still load without a full runbook.

{
  "version": 1,
  "operations": [
    {
      "id": "careers-full-crawl",
      "title": "Careers full crawl",
      "workflowName": "careers-crawl",
      "summary": "Discover company career pages, fetch postings, and hand them to parse/index workers.",
      "entryScript": "workflows/careers-crawl/scripts/enqueue.js",
      "ledgerRequired": true,
      "expectedQueues": ["careers_fetch", "careers_snapshot_parse"],
      "expectedWorkerPools": ["careers_fetch", "careers_snapshot_parse"],
      "relatedLedgerStages": ["portal_discovery", "fetch", "parse_index"],
      "phases": [
        {
          "id": "fetch",
          "title": "Fetch career pages",
          "stages": ["fetch"],
          "queues": ["careers_fetch"],
          "workers": ["careers_fetch"]
        }
      ],
      "focusAreas": [
        {
          "id": "fetch-backlog",
          "title": "Fetch backlog",
          "stages": ["fetch"],
          "queues": ["careers_fetch"],
          "actions": ["resume-fetch"]
        }
      ],
      "actions": [
        {
          "id": "resume-fetch",
          "title": "Resume fetch workers",
          "kind": "resume-workers",
          "queue": "careers_fetch",
          "targetConsole": "queue"
        }
      ],
      "relatedConsoles": ["workflowLedger", "queueConsole"]
    }
  ]
}

Useful operation fields:

FieldMeaning
workflowNameWorkflow that must be active for direct starts
entryScriptOptional start script; omit it for inspect/resume/recovery-only operations
summary, help, prerequisitesRunbook and operator guidance
expectedQueues, expectedWorkerPoolsQueue/worker evidence the console should look for
phasesMain stages of work, usually linked to queues, workers, and ledger stages
focusAreasActionable slices inside an operation, such as backlog, retry-ready work, or a handoff
actionsSupported operator actions such as start, resume workers, open queue, open ledger, or open script
preflightChecksOptional list of built-in preflight rows to display; omit it to show the default set

Operations without an entryScript are valid. The console treats them as inspect/resume/recovery surfaces and does not generate a Start action unless a manifest explicitly defines one, in which case it is disabled with a reason.

Runbook and preflight

Section titled “Runbook and preflight”

Runbook fields explain purpose, when to run, what the operation does, inputs, expected outcome, warnings, and troubleshooting. They are optional, but detailed descriptions are helpful when a workspace has many specialized crawlers and queues.

Preflight rows show whether the workspace is open, the manifest loaded, the workflow is known, the active workflow matches, the entry script exists, the ledger is available, queues exist, worker pools are known, and ledger attention is present.

Preflight is guidance plus safety. Hiding a row with preflightChecks changes the displayed tab, not the hard safety rules around starting a script under the wrong workflow.

Phases, focus areas, and handoffs

Section titled “Phases, focus areas, and handoffs”

Phases model the main operation steps. Focus areas model actionable slices inside those steps: fetch backlog, retry-ready work, dead letters, parse/index backlog, or a handoff that needs inspection.

Handoffs describe transitions between stages, such as fetch to parse_index. The console compares upstream and downstream ledger counts so the operator can see whether work has stopped between phases.

Use focus areas for repair and resume work instead of creating fake top-level operations. This keeps the left side of the console focused on real operations while still surfacing the work that needs attention.

workflow-map.json

Section titled “workflow-map.json”

Use workflows/workflow-map.json when a workspace contains many workflow folders but only a few operator-level systems. The map groups workflows into systems, pipelines, module groups, stages, queues, workers, operations, and handoffs.

{
  "version": 1,
  "systems": [
    {
      "id": "careers",
      "title": "Careers Crawl",
      "pipelines": [
        {
          "id": "careers-crawl",
          "title": "Careers Crawl Pipeline",
          "workflowName": "careers-crawl",
          "operations": ["careers-full-crawl"],
          "ledgerWorkflowName": "careers-crawl",
          "stages": ["portal_discovery", "fetch", "parse_index"],
          "queues": ["careers_fetch", "careers_snapshot_parse"],
          "workers": ["careers_fetch", "careers_snapshot_parse"],
          "modules": ["career-crawlers"],
          "handoffs": [
            {
              "from": "fetch",
              "to": "parse_index",
              "viaQueue": "careers_snapshot_parse"
            }
          ]
        }
      ],
      "moduleGroups": [
        {
          "id": "career-crawlers",
          "title": "Specialized career crawlers",
          "role": "adapter",
          "workflowNamePatterns": ["careers-*"],
          "excludeWorkflowNames": ["careers-crawl"]
        }
      ]
    }
  ]
}

Module progress is computed from ledger aggregates for the selected run, not from the visible item page. Modules with no ledger evidence are shown as not attempted so the operator can decide whether they were intentionally skipped, not yet queued, or missing from the run.

Scripting API

Section titled “Scripting API”
// Check what's active
const active = g.workflows.getActive();
if (active) g.log("Current workflow: " + active.name);


// List all workflows
const workflows = g.workflows.list();
for (const w of workflows) {
  g.log(w.name + " — " + w.scriptCount + " scripts" +
    (w.hasEvents ? ", has triggers" : ""));
}


// Switch (fire-and-forget)
g.workflows.switch("rss-pipeline");

See the API Reference for full method signatures.

Next Steps

Section titled “Next Steps”