mirror of
https://github.com/dtzp555-max/openclaw-agent-workflow.git
synced 2026-07-19 09:46:03 +00:00
feat: initial agent-workflow skill (v1.0.0)
This commit is contained in:
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
+4
-24
@@ -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"
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user