taodeng/openclaw-agent-workflow
1
0
Fork 0
mirror of https://github.com/dtzp555-max/openclaw-agent-workflow.git synced 2026-07-21 21:15:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: initial agent-workflow skill (v1.0.0)

Browse Source
This commit is contained in:
taodeng
2026-03-19 07:58:55 +10:00
parent 33ddccba79
commit 2d86c2968c
3 changed files with 195 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+131 -99
View File
@@ -1,127 +1,167 @@
# openclaw-agent-workflow # openclaw-agent-workflow
A lightweight JIRA-like workflow skill for OpenClaw agents. Prevents the three most common failure modes in multi-step agent tasks: A lightweight task-tracking skill for OpenClaw agents. Gives multi-step agent work a clear, observable lifecycle — no more silent failures, no more mystery state.
- **Silent disappearance** — agent stops responding with no explanation
- **Status opacity** — user has no idea what the agent is doing or how far along it is
- **Lost context on failure** — when something breaks, nobody knows what was tried or where it stopped
--- ---
## The Problem ## The Problem
When an OpenClaw agent handles a complex, multi-step task by dispatching sub-agents, things can go wrong silently: When an OpenClaw agent dispatches sub-agents to handle complex tasks, three failure modes appear regularly:
**1. Silent disappearance**
``` ```
User: "Migrate the database schema and update all dependent services" User: "Deploy the new service and update the config"
Agent: "On it!" Main agent: "On it!"
... ... [10 minutes of silence] ...
[10 minutes of silence]
...
Agent: "Done!" ← Did it actually finish? Was anything skipped?
```
Or worse:
```
Agent: "On it!"
...
[silence forever]
...
User: "Hello?" User: "Hello?"
``` ```
This skill solves that by giving agents a shared protocol for state transitions, progress reporting, and timeout handling. **2. Status opacity**
---
## How It Works
Every task moves through defined states with evidence requirements:
``` ```
planned → dispatching → in_progress → reviewing → done Main agent: "Working on it..."
↓ User: "How far along are you?"
blocked → (resolved) → in_progress Main agent: "Still working..."
``` ```
Worker agents report back at key moments (`accepted`, `milestone`, `blocked`, `done`). If 10 minutes pass without a report, the main agent marks the task as `launch_failure` and alerts the user. **3. Lost context on failure**
```
Main agent: "Something went wrong."
User: "What was tried? Where did it stop? What do I need to fix?"
Main agent: [no useful answer]
```
A live `CURRENT_STATE.md` file tracks all active, completed, blocked, and failed tasks. This skill solves all three by requiring agents to report at every meaningful state transition, with evidence.
--- ---
## Installation ## Installation
Copy this skill into your OpenClaw project: **Step 1:** Copy the skill into your OpenClaw skills directory:
```bash ```bash
cp -r openclaw-agent-workflow/ ~/.openclaw/skills/ cp -r openclaw-agent-workflow/ ~/.openclaw/skills/
``` ```
Or reference it directly in your agent's skill path. Then include it in your agent configuration: **Step 2:** Reference it in your agent config:
```json ```json
{ {
"skills": ["openclaw-agent-workflow"] "skills": ["agent-workflow"]
} }
``` ```
That's it. The skill is loaded automatically when the agent starts.
---
## Usage Scenarios
### Scenario 1: Multi-service refactor
```
User: Refactor the auth module and update all 12 callers
who: worker-a
status: dispatching
output: none yet
next: worker-a to confirm acceptance
who: worker-a
status: in_progress
output: read auth/index.ts, identified 12 callers
next: rewriting module core
who: worker-a
status: milestone
output: auth/index.ts rewritten, 9/12 callers updated
next: 3 callers remain (PaymentService, AdminAPI, LegacyBridge)
who: worker-a
status: done
output: all 12 callers updated, tests passing (auth.test.ts)
next: task complete
```
### Scenario 2: Worker gets blocked
```
User: Migrate the database schema
who: worker-b
status: in_progress
output: migration script written (migrations/0042_schema.sql)
next: running migration
who: worker-b
status: blocked
output: migration/0042_schema.sql exists, but prod DB is read-only
next: need DB write credentials or manual approval to proceed
```
### Scenario 3: Launch failure (timeout)
```
User: Run the full integration test suite
who: worker-c
status: dispatching
output: none yet
next: awaiting accepted report
[10 minutes pass with no response]
who: worker-c
status: blocked
output: no accepted report received within 10 minutes
next: retry dispatch or cancel — user decision required
```
--- ---
## Usage ## State Transition Diagram
### Starting a tracked task
When the main agent receives a multi-step task, it should:
1. Create a task entry in `CURRENT_STATE.md` with state `planned`
2. Dispatch to a worker agent with the task ID
3. Wait for the worker's `accepted` report before proceeding
4. Forward `milestone` and `blocked` reports to the user
5. Verify the `done` report before marking the task complete
### Worker agent behavior
Workers follow the reporting protocol in `SKILL.md`. Every worker must:
- Send `accepted` within 10 minutes of receiving a task
- Send `milestone` after each significant step
- Send `blocked` immediately when stuck
- Send `done` with a full summary when finished
### Example interaction
``` ```
User: Refactor the auth module and update all callers +----------+
| planned |
[TASK T-001] Dispatched → worker agent +----------+
Plan: |
- Audit current auth module (dispatch)
- Define new interface |
- Rewrite module v
- Update callers +-------------+
- Run tests | dispatching |
+-------------+
[TASK T-001] Progress: Auth module audit complete (12 callers found) |
Next: Defining new interface (worker: accepted)
|
[TASK T-001] Progress: New interface defined v
Next: Rewriting module +------------+
+-----> | in_progress|
[TASK T-001] BLOCKED | +------------+
Reason: CallerX uses internal auth state not exposed by new interface | | |
Tried: Checked all public methods, reviewed git history | (worker: | | (worker:
Waiting on: Decision — expose the state or refactor CallerX separately | milestone) | | done)
| | |
User: Refactor CallerX separately | [report | v
| to user] | reviewing |
[TASK T-001] Progress: Blocker resolved, resuming module rewrite | +----------+
... | |
| (main: verified)
[TASK T-001] DONE | |
Summary: Auth module refactored, 12 callers updated, CallerX refactored separately | v
Artifacts: src/auth/index.ts, src/auth/interface.ts, tests/auth.test.ts (+11 files) | +------+
| | done |
| +------+
|
| (blocked → resolved)
|
+--------+
| blocked|
+--------+
|
(user unblocks)
|
[back to in_progress]
``` ```
--- ---
@@ -129,15 +169,7 @@ Artifacts: src/auth/index.ts, src/auth/interface.ts, tests/auth.test.ts (+11 fil
## Files ## Files
| File | Purpose | | File | Purpose |
|---|---| |------|---------|
| `SKILL.md` | Full protocol definition — states, evidence rules, timeouts, report formats | | `SKILL.md` | Full protocol: states, evidence rules, timeouts, report formats |
| `openclaw.plugin.json` | Skill registration metadata | | `openclaw.plugin.json` | Skill registration metadata |
| `CURRENT_STATE.md` | Live task state (auto-managed by agents, created on first use) | | `examples/task-tracking-example.md` | End-to-end worked example |
| `examples/task-tracking-example.md` | Complete worked example |
---
## See Also
- `SKILL.md` — full protocol specification
- `examples/task-tracking-example.md` — end-to-end worked example with all report types
SKILL.md
+59 -137
View File
@@ -1,185 +1,107 @@
# OpenClaw Agent Workflow Skill # 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 ## Workflow States
| State | Meaning | | State | Meaning |
|---|---| |-------|---------|
| `planned` | Task defined, not yet dispatched | | `planned` | Task accepted by main agent, not yet dispatched |
| `dispatching` | Main agent sending task to worker agent | | `dispatching` | Main agent has sent task to worker; awaiting `accepted` confirmation |
| `in_progress` | Worker agent actively executing | | `in_progress` | Worker confirmed receipt AND has begun work (evidence required) |
| `blocked` | Worker cannot proceed without external input | | `blocked` | Worker cannot proceed; main agent must intervene |
| `reviewing` | Worker done, main agent verifying output | | `reviewing` | Worker reports done; main agent is verifying output |
| `done` | Task verified and complete | | `done` | Main agent has verified output and reported to user |
### 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
```
--- ---
## Evidence Rules ## 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 | | Transition | Required Evidence |
|---|---| |------------|-------------------|
| `dispatching → in_progress` | Worker emits `accepted` report with task echo | | `dispatching` → `in_progress` | Worker sends `accepted` report with first action taken |
| `in_progress → reviewing` | Worker emits `done` report with artifact reference or summary | | `in_progress` → `reviewing` | Worker sends `done` report with concrete output (file path, result, diff, etc.) |
| `blocked → in_progress` | Blocker resolved message from worker or user | | `reviewing` → `done` | Main agent has read/verified the output artifact |
| `reviewing → done` | Main agent confirms output matches success criteria | | `*` → `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 ## Timeout Rules
| Condition | Action | - **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`.
| Worker silent for **10 minutes** after dispatch | Mark state as `launch_failure`, report to user | - **Recovery:** On timeout, main agent must either re-dispatch or report failure to user. Never silently wait.
| 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
--- ---
## 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 status: accepted
task_id: <id> summary: <one sentence: what I understand the task to be>
echo: <one-line restatement of the task> evidence: <first concrete action taken, e.g. "read file X", "found 3 candidates">
plan: <bullet list of planned steps> 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 status: milestone
task_id: <id> summary: <what was just completed>
step_completed: <what just finished> evidence: <artifact or output, e.g. file written, test passed, result found>
next_step: <what is starting now> risk: <none | low | medium | high> — <brief reason if not none>
artifact: <file path or output reference, if any> next: <what remains>
``` ```
### 3. `blocked` — Cannot proceed ### On `blocked`
``` ```
REPORT blocked status: blocked
task_id: <id> summary: <what I was trying to do>
blocker: <clear description of what is blocking> evidence: <specific error, missing input, or ambiguity causing the block>
tried: <what was already attempted> risk: high — blocked task cannot proceed
needs: <what is needed to unblock> next: <what main agent needs to do to unblock>
``` ```
### 4. `done` — Task complete ### On `done`
``` ```
REPORT done status: done
task_id: <id>
summary: <what was accomplished> summary: <what was accomplished>
artifacts: <list of files created/modified> evidence: <final artifact: file path, output, test result, etc.>
success_criteria_met: true|false risk: <none | low | medium | high> — <brief reason if not none>
notes: <any caveats or follow-up items> 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: 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 who: <worker name or task ID>
Plan: <summary of steps> 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) ### Timing Rules
```
[TASK <id>] Progress: <step_completed>
Next: <next_step>
```
### On block - Do NOT wait silently. Every state change → one report to user.
``` - Do NOT batch multiple state changes into one delayed report.
[TASK <id>] BLOCKED - If nothing has changed for 5 minutes during `in_progress`, send a heartbeat to user.
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 |
|---|---|---|---|
```
openclaw.plugin.json
+4 -24
View File
@@ -1,27 +1,7 @@
{ {
"name": "openclaw-agent-workflow", "name": "agent-workflow",
"version": "1.0.0", "version": "1.0.0",
"description": "Lightweight JIRA-like workflow for multi-step agent tasks. Prevents silent failures and status opacity by enforcing state transitions, evidence rules, timeout handling, and structured reporting protocols.", "description": "Lightweight JIRA-like task tracking for OpenClaw agents",
"skill_file": "SKILL.md", "type": "skill",
"author": "OpenClaw", "entrypoint": "SKILL.md"
"tags": ["workflow", "task-tracking", "agent-coordination", "multi-step", "reliability"],
"state_file": "CURRENT_STATE.md",
"states": [
"planned",
"dispatching",
"in_progress",
"blocked",
"reviewing",
"done",
"launch_failure"
],
"timeout_minutes": {
"dispatch_to_accepted": 10,
"in_progress_silence": 10,
"blocked_stale": 30
},
"report_types": ["accepted", "milestone", "blocked", "done"],
"examples": [
"examples/task-tracking-example.md"
]
} }