technickai/openclaw-config/workflow-builder

Workflow Builder 🏗️

The meta-skill for designing and building autonomous OpenClaw workflows. A workflow (steward) is an autonomous agent that runs on a schedule, maintains state, learns over time, and does real work without prompting.

Skills vs Workflows:

• Skill = single-purpose tool (how to use a CLI, API, or pattern)
• Workflow = autonomous agent with state, learning, and scheduling

Part 1: Should You Automate This?

Not everything deserves a workflow. Use this framework to decide.

The Automation Audit

For any candidate task, score these dimensions:

Decision:

• Score ≥ 10 + Time Cost > 2 hrs/month → Build a workflow
• Score 7-9 → Add to heartbeat checklist (batch with other checks)
• Score < 7 → Keep manual or add as a cron one-liner

ROI Calculator

Setup Time (hours) × $50 = Setup Cost
Time Saved (hours/month) × $50 = Monthly Value
Payback = Setup Cost / Monthly Value
 
< 2 months payback → Build it now
2-6 months → Build when you have time
> 6 months → Probably not worth it

Workflow vs Heartbeat vs Cron

Rule of thumb: If it needs rules.md and agent_notes.md, it's a workflow. If it's a 2-line check, add it to HEARTBEAT.md.

Part 2: Workflow Anatomy

Every workflow follows this structure:

workflows/<name>/
├── AGENT.md          # The algorithm (updates with openclaw-config)
├── rules.md          # User preferences (never overwritten by updates)
├── agent_notes.md    # Learned patterns (grows over time, optional for some types)
├── state/            # Continuation state for multi-step work (optional)
│   └── active-work.json
└── logs/             # Execution history (auto-pruned)
    └── YYYY-MM-DD.md

AGENT.md — The Algorithm

This is the workflow's brain. It ships with openclaw-config and can be updated.

Standard sections (adapt to your workflow — not all are required):

---
name: <workflow-name>
version: <semver>
description: <one-line description>
---
 
# <Workflow Name>
 
<One paragraph: what this workflow does and why it exists.>
 
## Prerequisites
 
<What tools/access/labels/setup are needed before first run.>
 
## First Run — Setup Interview
 
<Interactive setup that creates rules.md. Ask preferences, scan existing data, suggest
smart defaults. Always let the user skip/bail early.>
 
## Regular Operation
 
<The main loop: what to read, how to process, when to alert, what to log.>
 
## Housekeeping
 
<Daily/weekly maintenance: log pruning, data cleanup, self-audit.>

rules.md — User Preferences

Created during first-run setup interview. Never overwritten by updates.

Pattern:

# <Workflow> Rules
 
## Account
 
-account: user@example.com
-alert_channel: whatsapp (or: none, telegram, slack)
 
## Preferences
 
-<workflow-specific settings>
 
## VIPs / Exceptions
 
-<people or patterns to handle specially>

agent_notes.md — Learned Patterns

The workflow writes here as it learns. Accumulates over time.

Pattern:

# Agent Notes
 
## Patterns Observed
 
-<sender X always sends receipts on Fridays>
-<task type Y usually takes 2 hours>
 
## Failures & Corrections
 
### YYYY-MM-DD: <brief description>
 
-What happened: <what the workflow did>
-Why it was wrong: <why it was incorrect>
-Correct action: <what should have happened>
-New rule: <guardrail to prevent recurrence>
-Applied to: <where the rule was added, e.g., rules.md VIP section>
 
## Improvement Proposals
 
-<AGENT.md is ambiguous about X — suggest clarifying to Y>
-<Tool Z fails silently when API is down — suggest adding health check>
 
## Optimizations
 
-<batch processing senders A, B, C saves 3 API calls>

logs/ — Execution History

One file per day, auto-pruned after 30 days.

Pattern:

# <Workflow> Log — YYYY-MM-DD
 
## Run: HH:MM
 
### Actions
 
-Processed: N items
-Actions: archived X, deleted Y, alerted on Z
-Errors: none
-Duration: ~Ns
 
### Scorecard
 
| Dimension    | Stars          | Notes                         |
| ------------ | -------------- | ----------------------------- |
| Completeness | ⭐⭐⭐⭐ (4)   | 1 item deferred (API timeout) |
| Accuracy     | ⭐⭐⭐⭐⭐ (5) | All classifications clear     |
| Judgment     | ⭐⭐⭐ (3)     | Unsure about sender X         |
| Overall      | ⭐⭐⭐⭐ (4)   |                               |
 
Confidence: HIGH
 
Source: self | verified (indicate whether cross-context verifier ran)

Definition of Done

Every workflow must declare what "done" looks like for a single run. This is the contract between the workflow and whoever (human or auditor) evaluates it.

Three components:

Completion Criteria

Concrete, checkable conditions that constitute a successful run. Not "process emails" but:

• All unread emails in target labels have been classified
• No email remained in an ambiguous state without escalation
• All actions logged with item IDs

These are binary pass/fail checks. If any fail, the run is incomplete.

Output Validation

Structural checks to run on the output before declaring done:

• Expected output format (log entry, state update, notification sent)
• Required fields present (item counts, action summaries, error list)
• Side effects confirmed (database updated, labels applied, alerts delivered)

These can be checked deterministically — no LLM judgment needed.

Quality Rubric

3-5 scored dimensions specific to this workflow, each on a 1-5 gold star scale:

Example rubric for an email steward:

The rubric goes in AGENT.md. Scores go in the run log. Over time, score trends reveal drift — a workflow averaging 4.5 that drops to 3.2 over a week signals something changed.

Verification Level

Not every workflow needs cross-context verification. The right level depends on two questions: can you undo it? and who sees the output?

                        Only user sees it       Others see it
                        ─────────────────       ─────────────
Reversible              Level A: Log only       Level B: Self-score
Irreversible            Level B: Self-score     Level C: Full verify

Level A — Log only. Just log what you did. No scorecard, no verification. For read-only workflows, reports, and briefings where the output is informational.

Level B — Self-score + circuit breakers. Score each run on the quality rubric. Auto-demote trust level if quality drops. No cross-context verification — the scorecard catches drift over time without the per-run token cost. For workflows whose actions are reversible or only affect the user.

Level C — Full verification. Self-score + cross-context verifier + circuit breakers. The fresh-context reviewer earns its cost because mistakes can't be undone and other people are affected. For workflows that send messages, publish content, or take irreversible actions visible to others.

Declare the level in AGENT.md so both the workflow and auditor know what's expected.

Examples:

Part 3: Design Patterns

Pattern 1: Setup Interview

Every workflow should start with an interactive setup that creates rules.md.

Best practices:

1. Check prerequisites first (API access, labels, etc.)
2. Ask questions one category at a time
3. Offer smart defaults based on scanning existing data
4. Let the user skip or bail early ("looks good, skip to the end")
5. Summarize rules in plain language before saving
6. Always include an escape hatch: alert_channel: none

Pattern 2: Graduated Trust

Trust is earned by performance, not elapsed time. Use run scorecard scores (see Definition of Done) to gate autonomy levels.

Level 1 — Supervised:
  Human reviews all actions before execution.
  Advance → 20 consecutive runs at ⭐⭐⭐⭐ or above
 
Level 2 — Monitored:
  Acts autonomously, human reviews logs daily.
  Advance → 50 consecutive runs at ⭐⭐⭐⭐ or above
  Demote  → 3 runs below ⭐⭐⭐
 
Level 3 — Autonomous:
  Acts and logs, human reviews weekly.
  Advance → 100 consecutive runs at ⭐⭐⭐⭐ or above
  Demote  → 3 runs below ⭐⭐⭐ → back to Level 2
 
Level 4 — Trusted:
  Fully autonomous, quality auditor watches trends.
  Demote  → quality auditor flags degradation → back to Level 3

Store trust state in `rules.md` so the user can see and override it:

## Trust
 
-trust_level: 2
-consecutive_good_runs: 14
-cooldown_remaining: 0

The workflow reads these at the start of each run and updates them at the end:

• Level 1: Present proposed actions, wait for approval before executing
• Level 2-4: Execute, then log actions for review

Starting point: New workflows default to Level 1. But for low-stakes workflows (health checks, notifications, reports), the user should promote to Level 2 during setup to avoid unnecessary babysitting. The setup interview should offer this choice: "Should I run independently and you review the logs, or would you prefer to approve each action first?"