diff --git a/docs/automation/taskflow.md b/docs/automation/taskflow.md index b0a93592b98..eaf55b0a630 100644 --- a/docs/automation/taskflow.md +++ b/docs/automation/taskflow.md @@ -20,6 +20,78 @@ Use Task Flow when work spans multiple sequential or branching steps and you nee | Observe externally created tasks | Task Flow (mirrored) | | One-shot reminder | Cron job | +## Reliable scheduled workflow pattern + +For recurring workflows such as market intelligence briefings, treat the schedule, orchestration, and reliability checks as separate layers: + +1. Use [Scheduled Tasks](/automation/cron-jobs) for timing. +2. Use a persistent cron session when the workflow should build on prior context. +3. Use [Lobster](/tools/lobster) for deterministic steps, approval gates, and resume tokens. +4. Use Task Flow to track the multi-step run across child tasks, waits, retries, and gateway restarts. + +Example cron shape: + +```bash +openclaw cron add \ + --name "Market intelligence brief" \ + --cron "0 7 * * 1-5" \ + --tz "America/New_York" \ + --session session:market-intel \ + --message "Run the market-intel Lobster workflow. Verify source freshness before summarizing." \ + --announce \ + --channel slack \ + --to "channel:C1234567890" +``` + +Use `session:` instead of `isolated` when the recurring workflow needs deliberate history, previous run summaries, or standing context. Use `isolated` when each run should start fresh and all required state is explicit in the workflow. + +Inside the workflow, put reliability checks before the LLM summary step: + +```yaml +name: market-intel-brief +steps: + - id: preflight + command: market-intel check --json + - id: collect + command: market-intel collect --json + stdin: $preflight.json + - id: summarize + command: market-intel summarize --json + stdin: $collect.json + - id: approve + command: market-intel deliver --preview + stdin: $summarize.json + approval: required + - id: deliver + command: market-intel deliver --execute + stdin: $summarize.json + condition: $approve.approved +``` + +Recommended preflight checks: + +- Browser availability and profile choice, for example `openclaw` for managed state or `user` when a signed-in Chrome session is required. See [Browser](/tools/browser). +- API credentials and quota for each source. +- Network reachability for required endpoints. +- Required tools enabled for the agent, such as `lobster`, `browser`, and `llm-task`. +- Failure destination configured for cron so preflight failures are visible. See [Scheduled Tasks](/automation/cron-jobs#delivery-and-output). + +Recommended data provenance fields for every collected item: + +```json +{ + "sourceUrl": "https://example.com/report", + "retrievedAt": "2026-04-24T12:00:00Z", + "asOf": "2026-04-24", + "title": "Example report", + "content": "..." +} +``` + +Have the workflow reject or mark stale items before summarization. The LLM step should receive only structured JSON and should be asked to preserve `sourceUrl`, `retrievedAt`, and `asOf` in its output. Use [LLM Task](/tools/llm-task) when you need a schema-validated model step inside the workflow. + +For reusable team or community workflows, package the CLI, `.lobster` files, and any setup notes as a skill or plugin and publish it through [ClawHub](/tools/clawhub). Keep workflow-specific guardrails in that package unless the plugin API is missing a needed generic capability. + ## Sync modes ### Managed mode