mirror of
https://github.com/dtzp555-max/openclaw-agent-workflow.git
synced 2026-07-22 21:45:10 +00:00
144 lines
3.8 KiB
Markdown
144 lines
3.8 KiB
Markdown
# 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
|
|
|
|
---
|
|
|
|
## The Problem
|
|
|
|
When an OpenClaw agent handles a complex, multi-step task by dispatching sub-agents, things can go wrong silently:
|
|
|
|
```
|
|
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: "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:
|
|
|
|
```
|
|
planned → dispatching → in_progress → reviewing → done
|
|
↓
|
|
blocked → (resolved) → in_progress
|
|
```
|
|
|
|
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.
|
|
|
|
A live `CURRENT_STATE.md` file tracks all active, completed, blocked, and failed tasks.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Copy this skill into your OpenClaw project:
|
|
|
|
```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:
|
|
|
|
```json
|
|
{
|
|
"skills": ["openclaw-agent-workflow"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```
|
|
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)
|
|
```
|
|
|
|
---
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `SKILL.md` | Full protocol definition — 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
|