taodeng/openclaw-agent-workflow
1
0
Fork 0
mirror of https://github.com/dtzp555-max/openclaw-agent-workflow.git synced 2026-07-19 09:46:03 +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
A lightweight JIRA-like workflow skill for OpenClaw agents. Prevents the three most common failure modes in multi-step agent tasks:
- **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
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.
---
## 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"
Agent: "On it!"
...
[10 minutes of silence]
...
Agent: "Done!" ← Did it actually finish? Was anything skipped?
```
Or worse:
```
Agent: "On it!"
...
[silence forever]
...
User: "Deploy the new service and update the config"
Main agent: "On it!"
... [10 minutes of silence] ...
User: "Hello?"
```
This skill solves that by giving agents a shared protocol for state transitions, progress reporting, and timeout handling.
---
## How It Works
Every task moves through defined states with evidence requirements:
**2. Status opacity**
```
planned → dispatching → in_progress → reviewing → done
↓
blocked → (resolved) → in_progress
Main agent: "Working on it..."
User: "How far along are you?"
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
Copy this skill into your OpenClaw project:
**Step 1:** Copy the skill into your OpenClaw skills directory:
```bash
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
{
"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
### 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
## State Transition Diagram
```
User: Refactor the auth module and update all callers
[TASK T-001] Dispatched → worker agent
Plan:
- Audit current auth module
- Define new interface
- Rewrite module
- Update callers
- Run tests
[TASK T-001] Progress: Auth module audit complete (12 callers found)
Next: Defining new interface
[TASK T-001] Progress: New interface defined
Next: Rewriting module
[TASK T-001] BLOCKED
Reason: CallerX uses internal auth state not exposed by new interface
Tried: Checked all public methods, reviewed git history
Waiting on: Decision — expose the state or refactor CallerX separately
User: Refactor CallerX separately
[TASK T-001] Progress: Blocker resolved, resuming module rewrite
...
[TASK T-001] DONE
Summary: Auth module refactored, 12 callers updated, CallerX refactored separately
Artifacts: src/auth/index.ts, src/auth/interface.ts, tests/auth.test.ts (+11 files)
+----------+
| planned |
+----------+
|
(dispatch)
|
v
+-------------+
| dispatching |
+-------------+
|
(worker: accepted)
|
v
+------------+
+-----> | in_progress|
| +------------+
| | |
| (worker: | | (worker:
| milestone) | | done)
| | |
| [report | v
| to user] | reviewing |
| +----------+
| |
| (main: verified)
| |
| v
| +------+
| | 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
| 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 |
| `CURRENT_STATE.md` | Live task state (auto-managed by agents, created on first use) |
| `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
| `examples/task-tracking-example.md` | End-to-end worked example |
SKILL.md
+60 -138
View File
@@ -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.
openclaw.plugin.json
+4 -24
View File
@@ -1,27 +1,7 @@
{
"name": "openclaw-agent-workflow",
"name": "agent-workflow",
"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.",
"skill_file": "SKILL.md",
"author": "OpenClaw",
"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"
]
"description": "Lightweight JIRA-like task tracking for OpenClaw agents",
"type": "skill",
"entrypoint": "SKILL.md"
}