mirror of
https://github.com/dtzp555-max/openclaw-agent-workflow.git
synced 2026-07-19 09:46:03 +00:00
108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
# OpenClaw Agent Workflow Skill
|
|
|
|
A lightweight task-tracking protocol for OpenClaw agents handling multi-step work. Eliminates silent failures and opaque state by requiring structured status reports at every transition.
|
|
|
|
---
|
|
|
|
## Workflow States
|
|
|
|
| State | Meaning |
|
|
|-------|---------|
|
|
| `planned` | Task accepted by main agent, not yet dispatched |
|
|
| `dispatching` | Main agent has sent task to worker; awaiting `accepted` confirmation |
|
|
| `in_progress` | Worker confirmed receipt AND has begun work (evidence required) |
|
|
| `blocked` | Worker cannot proceed; main agent must intervene |
|
|
| `reviewing` | Worker reports done; main agent is verifying output |
|
|
| `done` | Main agent has verified output and reported to user |
|
|
|
|
---
|
|
|
|
## Evidence Rules
|
|
|
|
State upgrades MUST be backed by evidence. Spawning alone does not count.
|
|
|
|
| Transition | Required Evidence |
|
|
|------------|-------------------|
|
|
| `dispatching` → `in_progress` | Worker sends `accepted` report with first action taken |
|
|
| `in_progress` → `reviewing` | Worker sends `done` report with concrete output (file path, result, diff, etc.) |
|
|
| `reviewing` → `done` | Main agent has read/verified the output artifact |
|
|
| `*` → `blocked` | Worker sends `blocked` report with specific blocker description |
|
|
|
|
**Rule:** Never write "task is in_progress" in a user-facing update unless the worker has sent an `accepted` report.
|
|
|
|
---
|
|
|
|
## Timeout Rules
|
|
|
|
- **Launch timeout:** If a worker does not send an `accepted` report within **10 minutes** of dispatch, treat the task as a launch failure.
|
|
- **Milestone timeout:** If a worker is `in_progress` and sends no update (milestone or done) for **10 minutes**, escalate to `blocked`.
|
|
- **Recovery:** On timeout, main agent must either re-dispatch or report failure to user. Never silently wait.
|
|
|
|
---
|
|
|
|
## Worker Report Protocol
|
|
|
|
Workers report back to the main agent using this structured format. All fields are required.
|
|
|
|
### On `accepted`
|
|
```
|
|
status: accepted
|
|
summary: <one sentence: what I understand the task to be>
|
|
evidence: <first concrete action taken, e.g. "read file X", "found 3 candidates">
|
|
risk: <none | low | medium | high> — <brief reason if not none>
|
|
next: <what I will do next>
|
|
```
|
|
|
|
### On `milestone`
|
|
```
|
|
status: milestone
|
|
summary: <what was just completed>
|
|
evidence: <artifact or output, e.g. file written, test passed, result found>
|
|
risk: <none | low | medium | high> — <brief reason if not none>
|
|
next: <what remains>
|
|
```
|
|
|
|
### On `blocked`
|
|
```
|
|
status: blocked
|
|
summary: <what I was trying to do>
|
|
evidence: <specific error, missing input, or ambiguity causing the block>
|
|
risk: high — blocked task cannot proceed
|
|
next: <what main agent needs to do to unblock>
|
|
```
|
|
|
|
### On `done`
|
|
```
|
|
status: done
|
|
summary: <what was accomplished>
|
|
evidence: <final artifact: file path, output, test result, etc.>
|
|
risk: <none | low | medium | high> — <brief reason if not none>
|
|
next: none
|
|
```
|
|
|
|
---
|
|
|
|
## Main Agent Report Protocol
|
|
|
|
Main agent reports to the user at these moments:
|
|
- After dispatching (transition to `dispatching`)
|
|
- After receiving `accepted` (transition to `in_progress`)
|
|
- After each `milestone` from a worker
|
|
- After verifying output (transition to `done`)
|
|
- Immediately on `blocked` or timeout
|
|
|
|
### Report Format
|
|
|
|
```
|
|
who: <worker name or task ID>
|
|
status: <dispatching | in_progress | milestone | blocked | done>
|
|
output: <what has been produced so far, or "none yet">
|
|
next: <what happens next, or "task complete">
|
|
```
|
|
|
|
### Timing Rules
|
|
|
|
- Do NOT wait silently. Every state change → one report to user.
|
|
- Do NOT batch multiple state changes into one delayed report.
|
|
- If nothing has changed for 5 minutes during `in_progress`, send a heartbeat to user.
|