Skip to content

Workflows

SecondBrain workflow support lives under sb workflow and the brain/workflows/ package.

Purpose

  • manage committed and overlay workflow specs
  • lint and run workflows reproducibly
  • schedule follow-up tasks from the workflow-facing CLI

Who It Is For

  • operators running repeatable local workflows
  • contributors adding or debugging workflow specs
  • automation authors who need bounded, auditable execution

Where Workflow Specs Live

Current defaults come from the workflow package:

  • committed workflows: ops/workflows
  • overlay workflows: ~/.secondbrain/workflows

Overlay specs win by workflow id when both paths define the same workflow.

Core Commands

sb workflow list
sb workflow show <workflow_id>
sb workflow lint
sb workflow run <workflow_id> --input key=value
sb workflow run <workflow_id> --input-json ./inputs.json
sb workflow enable <workflow_id>
sb workflow disable <workflow_id>
sb workflow schedule "Follow up on release checklist"
sb workflow tasks
sb workflow automations list
sb workflow automations create "Morning Review" --prompt "Review open loops" --schedule "cron:0 9 * * 1-5"

Use sb workflow --help and sb workflow <subcommand> --help for the exact live flags.

Typical Flow

Discover and inspect

sb workflow list
sb workflow show <workflow_id>

Validate before execution

sb workflow lint

Run with explicit inputs

sb workflow run <workflow_id> --input query="tool usage patterns"

Temporarily change registry state

sb workflow disable <workflow_id>
sb workflow enable <workflow_id>

Scheduling

The workflow CLI also exposes scheduled-task helpers:

sb workflow schedule "Review open loops" --priority high
sb workflow tasks

This is adjacent to, but separate from, registry-backed sb automations runs for integrations.

Workflow-native recurring automations live under sb workflow automations:

sb workflow automations create "Morning Review" \
  --prompt "Review open loops and stale commitments" \
  --schedule "cron:0 9 * * 1-5"
sb workflow automations list
sb workflow automations run --due-only
sb workflow automations pause <automation_id>
sb workflow automations resume <automation_id>

These automations are local definitions stored under the SecondBrain state directory. They do not replace integration-backed sb automations; instead, they materialize recurring work into the existing scheduled-task surface.

When sb serve is running, due workflow automations are also swept automatically in the background by default. The serve runtime behavior is controlled with environment variables:

  • SB_SERVE_WORKFLOW_AUTOMATIONS_ENABLED=0 disables the background sweep
  • SB_SERVE_WORKFLOW_AUTOMATIONS_RUN_ON_STARTUP=0 skips the initial startup sweep
  • SB_SERVE_WORKFLOW_AUTOMATIONS_INTERVAL_S=60 changes the polling interval in seconds

The serve API also exposes POST /workflow-automations/run-due for explicit bulk execution of the due queue.

Operational Notes

  • Prefer sb workflow lint before adding or changing specs.
  • Prefer explicit --input or --input-json values for reproducible runs.
  • Workflow execution is governed and audited through the shared runtime rather than arbitrary shell execution.
  • Workflow automation schedules use interval:<seconds> or cron:<5-field-crontab> syntax.

Implementation Pointers

Key code paths:

  • brain/workflows/spec.py
  • brain/workflows/registry.py
  • brain/workflows/runner.py
  • brain/cli/workflow.py