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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-07-19 09:46:03 +00:00 · 2026-03-19 07:58:13 +10:00
commit 33ddccba79
4 changed files with 631 additions and 0 deletions
@@ -0,0 +1,185 @@
+# OpenClaw Agent Workflow Skill
+
+This skill enforces a lightweight JIRA-like workflow for multi-step agent tasks, preventing silent failures and status opacity.
+
+---
+
+## 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
+```
+
+---
+
+## Evidence Rules
+
+A state upgrade is only valid when the following evidence exists:
+
+| 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 |
+
+**No state may be skipped.** A task cannot go from `in_progress` directly to `done` without a `reviewing` step.
+
+---
+
+## 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
+
+---
+
+## Worker Agent Reporting Protocol
+
+Worker agents MUST report back at these moments:
+
+### 1. `accepted` — Task received and understood
+```
+REPORT accepted
+task_id: <id>
+echo: <one-line restatement of the task>
+plan: <bullet list of planned steps>
+```
+
+### 2. `milestone` — Significant progress checkpoint
+```
+REPORT milestone
+task_id: <id>
+step_completed: <what just finished>
+next_step: <what is starting now>
+artifact: <file path or output reference, if any>
+```
+
+### 3. `blocked` — Cannot proceed
+```
+REPORT blocked
+task_id: <id>
+blocker: <clear description of what is blocking>
+tried: <what was already attempted>
+needs: <what is needed to unblock>
+```
+
+### 4. `done` — Task complete
+```
+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>
+```
+
+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 reports to the user at these moments:
+
+### On dispatch
+```
+[TASK <id>] Dispatched → worker agent
+Plan: <summary of steps>
+```
+
+### On milestone (forwarded from worker)
+```
+[TASK <id>] Progress: <step_completed>
+Next: <next_step>
+```
+
+### 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 |
+|---|---|---|---|
+```