mirror of
https://github.com/dtzp555-max/openclaw-agent-workflow.git
synced 2026-07-21 21:15:11 +00:00
feat: initial agent-workflow skill (v1.0.0)
This commit is contained in:
@@ -1,185 +1,107 @@
|
||||
# OpenClaw Agent Workflow Skill
|
||||
|
||||
This skill enforces a lightweight JIRA-like workflow for multi-step agent tasks, preventing silent failures and status opacity.
|
||||
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 defined, not yet dispatched |
|
||||
| `dispatching` | Main agent sending task to worker agent |
|
||||
| `in_progress` | Worker agent actively executing |
|
||||
| `blocked` | Worker cannot proceed without external input |
|
||||
| `reviewing` | Worker done, main agent verifying output |
|
||||
| `done` | Task verified and complete |
|
||||
|
||||
### State Transition Rules
|
||||
|
||||
```
|
||||
planned → dispatching : main agent sends task
|
||||
dispatching → in_progress : worker sends "accepted" report
|
||||
in_progress → blocked : worker hits unresolvable blocker
|
||||
in_progress → reviewing : worker sends "done" report
|
||||
blocked → in_progress : blocker resolved
|
||||
reviewing → done : main agent verifies and closes
|
||||
reviewing → in_progress : main agent rejects, worker resumes
|
||||
```
|
||||
|-------|---------|
|
||||
| `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
|
||||
|
||||
A state upgrade is only valid when the following evidence exists:
|
||||
State upgrades MUST be backed by evidence. Spawning alone does not count.
|
||||
|
||||
| Transition | Required Evidence |
|
||||
|---|---|
|
||||
| `dispatching → in_progress` | Worker emits `accepted` report with task echo |
|
||||
| `in_progress → reviewing` | Worker emits `done` report with artifact reference or summary |
|
||||
| `blocked → in_progress` | Blocker resolved message from worker or user |
|
||||
| `reviewing → done` | Main agent confirms output matches success criteria |
|
||||
|------------|-------------------|
|
||||
| `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 |
|
||||
|
||||
**No state may be skipped.** A task cannot go from `in_progress` directly to `done` without a `reviewing` step.
|
||||
**Rule:** Never write "task is in_progress" in a user-facing update unless the worker has sent an `accepted` report.
|
||||
|
||||
---
|
||||
|
||||
## Timeout Rules
|
||||
|
||||
| Condition | Action |
|
||||
|---|---|
|
||||
| Worker silent for **10 minutes** after dispatch | Mark state as `launch_failure`, report to user |
|
||||
| Worker silent for **10 minutes** during `in_progress` | Escalate to `blocked`, report to user |
|
||||
| Blocker unresolved for **30 minutes** | Report stale block to user, ask for guidance |
|
||||
|
||||
When a timeout fires, main agent must:
|
||||
1. Update `CURRENT_STATE.md` with the timeout event
|
||||
2. Notify the user with the last known state and elapsed time
|
||||
3. Await user instruction before retrying or canceling
|
||||
- **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 Agent Reporting Protocol
|
||||
## Worker Report Protocol
|
||||
|
||||
Worker agents MUST report back at these moments:
|
||||
Workers report back to the main agent using this structured format. All fields are required.
|
||||
|
||||
### 1. `accepted` — Task received and understood
|
||||
### On `accepted`
|
||||
```
|
||||
REPORT accepted
|
||||
task_id: <id>
|
||||
echo: <one-line restatement of the task>
|
||||
plan: <bullet list of planned steps>
|
||||
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>
|
||||
```
|
||||
|
||||
### 2. `milestone` — Significant progress checkpoint
|
||||
### On `milestone`
|
||||
```
|
||||
REPORT milestone
|
||||
task_id: <id>
|
||||
step_completed: <what just finished>
|
||||
next_step: <what is starting now>
|
||||
artifact: <file path or output reference, if any>
|
||||
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>
|
||||
```
|
||||
|
||||
### 3. `blocked` — Cannot proceed
|
||||
### On `blocked`
|
||||
```
|
||||
REPORT blocked
|
||||
task_id: <id>
|
||||
blocker: <clear description of what is blocking>
|
||||
tried: <what was already attempted>
|
||||
needs: <what is needed to unblock>
|
||||
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>
|
||||
```
|
||||
|
||||
### 4. `done` — Task complete
|
||||
### On `done`
|
||||
```
|
||||
REPORT done
|
||||
task_id: <id>
|
||||
summary: <what was accomplished>
|
||||
artifacts: <list of files created/modified>
|
||||
success_criteria_met: true|false
|
||||
notes: <any caveats or follow-up items>
|
||||
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
|
||||
```
|
||||
|
||||
Workers that do not send any report within 10 minutes of accepting a task are considered to have silently failed.
|
||||
|
||||
---
|
||||
|
||||
## Main Agent User-Reporting Protocol
|
||||
## 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
|
||||
|
||||
### On dispatch
|
||||
```
|
||||
[TASK <id>] Dispatched → worker agent
|
||||
Plan: <summary of steps>
|
||||
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">
|
||||
```
|
||||
|
||||
### On milestone (forwarded from worker)
|
||||
```
|
||||
[TASK <id>] Progress: <step_completed>
|
||||
Next: <next_step>
|
||||
```
|
||||
### Timing Rules
|
||||
|
||||
### On block
|
||||
```
|
||||
[TASK <id>] BLOCKED
|
||||
Reason: <blocker>
|
||||
Tried: <what was attempted>
|
||||
Waiting on: <what is needed>
|
||||
```
|
||||
|
||||
### On completion
|
||||
```
|
||||
[TASK <id>] DONE
|
||||
Summary: <what was accomplished>
|
||||
Artifacts: <list>
|
||||
```
|
||||
|
||||
### On timeout / launch failure
|
||||
```
|
||||
[TASK <id>] TIMEOUT — no response for 10 minutes
|
||||
Last state: <state>
|
||||
Action needed: retry / cancel / investigate
|
||||
```
|
||||
|
||||
Main agent should NOT silently proceed to the next task after a failure. Always surface the failure to the user.
|
||||
|
||||
---
|
||||
|
||||
## CURRENT_STATE.md Update Triggers
|
||||
|
||||
Main agent must update `CURRENT_STATE.md` whenever:
|
||||
|
||||
1. A new task is created (`planned`)
|
||||
2. A task is dispatched (`dispatching`)
|
||||
3. A worker report is received (any report type)
|
||||
4. A timeout fires
|
||||
5. A task reaches `done`
|
||||
|
||||
### CURRENT_STATE.md Format
|
||||
|
||||
```markdown
|
||||
# Current Workflow State
|
||||
Last updated: <ISO timestamp>
|
||||
|
||||
## Active Tasks
|
||||
|
||||
| ID | Title | State | Last Event | Owner |
|
||||
|---|---|---|---|---|
|
||||
| T-001 | <title> | in_progress | milestone: step 2/4 | worker-a |
|
||||
|
||||
## Completed Tasks (last 5)
|
||||
|
||||
| ID | Title | Completed At | Artifacts |
|
||||
|---|---|---|---|
|
||||
| T-000 | <title> | <timestamp> | <paths> |
|
||||
|
||||
## Blocked Tasks
|
||||
|
||||
| ID | Title | Blocker | Since |
|
||||
|---|---|---|---|
|
||||
|
||||
## Failed / Timed Out Tasks
|
||||
|
||||
| ID | Title | Failure Reason | Since |
|
||||
|---|---|---|---|
|
||||
```
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user