From 2d86c2968c1ba4a2270eb45d301645d9d10b75d2 Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Thu, 19 Mar 2026 07:58:55 +1000 Subject: [PATCH] feat: initial agent-workflow skill (v1.0.0) --- README.md | 230 ++++++++++++++++++++++++------------------- SKILL.md | 198 +++++++++++-------------------------- openclaw.plugin.json | 28 +----- 3 files changed, 195 insertions(+), 261 deletions(-) diff --git a/README.md b/README.md index 26c9186..cf2ba4c 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/SKILL.md b/SKILL.md index ec17301..710a8b9 100644 --- a/SKILL.md +++ b/SKILL.md @@ -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: -echo: -plan: +status: accepted +summary: +evidence: +risk: — +next: ``` -### 2. `milestone` — Significant progress checkpoint +### On `milestone` ``` -REPORT milestone -task_id: -step_completed: -next_step: -artifact: +status: milestone +summary: +evidence: +risk: — +next: ``` -### 3. `blocked` — Cannot proceed +### On `blocked` ``` -REPORT blocked -task_id: -blocker: -tried: -needs: +status: blocked +summary: +evidence: +risk: high — blocked task cannot proceed +next: ``` -### 4. `done` — Task complete +### On `done` ``` -REPORT done -task_id: -summary: -artifacts: -success_criteria_met: true|false -notes: +status: done +summary: +evidence: +risk: — +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 ] Dispatched → worker agent -Plan: +who: +status: +output: +next: ``` -### On milestone (forwarded from worker) -``` -[TASK ] Progress: -Next: -``` +### Timing Rules -### On block -``` -[TASK ] BLOCKED -Reason: -Tried: -Waiting on: -``` - -### On completion -``` -[TASK ] DONE -Summary: -Artifacts: -``` - -### On timeout / launch failure -``` -[TASK ] TIMEOUT — no response for 10 minutes -Last 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: - -## Active Tasks - -| ID | Title | State | Last Event | Owner | -|---|---|---|---|---| -| T-001 | | 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. diff --git a/openclaw.plugin.json b/openclaw.plugin.json index 736adb0..49a0e5b 100644 --- a/openclaw.plugin.json +++ b/openclaw.plugin.json @@ -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" }