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,143 @@
+# 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