commit 33ddccba79f5be6b76c0c779e33d8f9a61159496 Author: dtzp555 Date: Thu Mar 19 07:58:13 2026 +1000 feat: initial agent-workflow skill (v1.0.0) Co-Authored-By: Claude Sonnet 4.6 diff --git a/README.md b/README.md new file mode 100644 index 0000000..26c9186 --- /dev/null +++ b/README.md @@ -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 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..ec17301 --- /dev/null +++ b/SKILL.md @@ -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: +echo: +plan: +``` + +### 2. `milestone` — Significant progress checkpoint +``` +REPORT milestone +task_id: +step_completed: +next_step: +artifact: +``` + +### 3. `blocked` — Cannot proceed +``` +REPORT blocked +task_id: +blocker: +tried: +needs: +``` + +### 4. `done` — Task complete +``` +REPORT done +task_id: +summary: +artifacts: +success_criteria_met: true|false +notes: +``` + +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 ] Dispatched → worker agent +Plan: +``` + +### On milestone (forwarded from worker) +``` +[TASK ] Progress: +Next: +``` + +### 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 | +|---|---|---|---| +``` diff --git a/examples/task-tracking-example.md b/examples/task-tracking-example.md new file mode 100644 index 0000000..91b2b15 --- /dev/null +++ b/examples/task-tracking-example.md @@ -0,0 +1,276 @@ +# Task Tracking Example + +A complete end-to-end walkthrough of the openclaw-agent-workflow protocol. + +**Scenario:** User asks the main agent to add a new payments feature, which requires backend API work, database migration, and frontend integration. + +--- + +## Step 1 — User Request + +``` +User: Add a Stripe payments integration. We need a backend API endpoint, + a database table for payment records, and a frontend checkout form. +``` + +--- + +## Step 2 — Main Agent: Task Planning + +Main agent creates the task and updates `CURRENT_STATE.md`: + +```markdown +# Current Workflow State +Last updated: 2026-03-19T10:00:00Z + +## Active Tasks + +| ID | Title | State | Last Event | Owner | +|-------|-----------------------------|------------|--------------------|--------| +| T-001 | Stripe payments integration | planned | created | main | +``` + +Main agent reports to user: + +``` +[TASK T-001] Dispatched → worker agent +Plan: +- Create payments database table (migration) +- Implement /api/payments POST endpoint +- Add Stripe SDK and webhook handler +- Build frontend checkout form component +- Write integration tests +``` + +State in `CURRENT_STATE.md` updated to `dispatching`. + +--- + +## Step 3 — Worker Agent: Accepted Report + +Worker agent receives the task and immediately sends: + +``` +REPORT accepted +task_id: T-001 +echo: Implement Stripe payments integration — DB migration, backend API, frontend form +plan: + - Run database migration to create payments table + - Install and configure stripe SDK + - Implement POST /api/payments endpoint + - Add Stripe webhook handler + - Build CheckoutForm React component + - Write integration tests +``` + +Main agent receives this, updates state to `in_progress`: + +```markdown +| T-001 | Stripe payments integration | in_progress | accepted | worker-payments | +``` + +--- + +## Step 4 — Worker Agent: First Milestone + +Worker completes the database migration: + +``` +REPORT milestone +task_id: T-001 +step_completed: Database migration created and applied — payments table live +next_step: Installing Stripe SDK and configuring API keys +artifact: db/migrations/20260319_create_payments.sql +``` + +Main agent forwards to user: + +``` +[TASK T-001] Progress: Database migration complete +Next: Stripe SDK setup +``` + +`CURRENT_STATE.md` updated: + +```markdown +| T-001 | Stripe payments integration | in_progress | milestone: migration done | worker-payments | +``` + +--- + +## Step 5 — Worker Agent: Blocked Report + +Worker hits an issue with API key configuration: + +``` +REPORT blocked +task_id: T-001 +blocker: Stripe API keys not present in environment. STRIPE_SECRET_KEY and + STRIPE_WEBHOOK_SECRET are missing from .env and CI secrets. +tried: + - Checked .env.example — keys not documented + - Checked CI config — no Stripe secrets configured + - Checked team docs wiki — no setup guide found +needs: Stripe API keys (test mode) added to .env and CI secrets +``` + +Main agent updates state to `blocked` and reports to user: + +``` +[TASK T-001] BLOCKED +Reason: Stripe API keys missing from environment +Tried: Checked .env, CI config, and team docs +Waiting on: STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET (test mode keys) +``` + +`CURRENT_STATE.md` updated: + +```markdown +## Blocked Tasks + +| ID | Title | Blocker | Since | +|-------|-----------------------------|--------------------------------|----------------------| +| T-001 | Stripe payments integration | Missing Stripe API keys in env | 2026-03-19T10:18:00Z | +``` + +--- + +## Step 6 — User Resolves Blocker + +``` +User: I've added the Stripe test keys to .env and GitHub secrets. + STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are set. +``` + +Main agent relays to worker. Worker resumes: + +``` +REPORT milestone +task_id: T-001 +step_completed: Stripe SDK installed and configured — keys verified working +next_step: Implementing POST /api/payments endpoint +artifact: src/lib/stripe.ts +``` + +State returns to `in_progress`. `CURRENT_STATE.md` blocker row removed. + +--- + +## Step 7 — Worker Agent: More Milestones + +``` +REPORT milestone +task_id: T-001 +step_completed: POST /api/payments endpoint implemented with idempotency key support +next_step: Adding Stripe webhook handler +artifact: src/api/payments.ts +``` + +``` +REPORT milestone +task_id: T-001 +step_completed: Stripe webhook handler implemented and verified locally +next_step: Building CheckoutForm React component +artifact: src/api/webhooks/stripe.ts +``` + +``` +REPORT milestone +task_id: T-001 +step_completed: CheckoutForm component built with card element and error handling +next_step: Writing integration tests +artifact: src/components/CheckoutForm.tsx +``` + +Main agent forwards each to user with brief updates: +``` +[TASK T-001] Progress: /api/payments endpoint done +[TASK T-001] Progress: Webhook handler done +[TASK T-001] Progress: CheckoutForm component done — writing tests +``` + +--- + +## Step 8 — Worker Agent: Done Report + +``` +REPORT done +task_id: T-001 +summary: Stripe payments integration complete. Backend API endpoint with idempotency, + webhook handler for payment confirmation events, database migration for + payment records, and CheckoutForm frontend component with error handling. + All integration tests passing. +artifacts: + - db/migrations/20260319_create_payments.sql + - src/lib/stripe.ts + - src/api/payments.ts + - src/api/webhooks/stripe.ts + - src/components/CheckoutForm.tsx + - tests/integration/payments.test.ts +success_criteria_met: true +notes: Webhook endpoint needs to be registered in Stripe dashboard before going to prod. + See src/api/webhooks/stripe.ts line 3 for the expected URL path. +``` + +--- + +## Step 9 — Main Agent: Review + +Main agent checks the artifacts, verifies tests pass, confirms success criteria: + +- Database migration exists and applies cleanly +- API endpoint matches spec +- Webhook handler registered at correct path +- Frontend component renders and submits +- Tests all green + +--- + +## Step 10 — Main Agent: Report Done to User + +``` +[TASK T-001] DONE +Summary: Stripe payments integration complete — API, webhook, DB migration, checkout form +Artifacts: + - db/migrations/20260319_create_payments.sql + - src/api/payments.ts + webhook handler + - src/components/CheckoutForm.tsx + - Integration tests passing + +Note: Register the webhook URL in your Stripe dashboard before deploying to prod. + Path: /api/webhooks/stripe +``` + +`CURRENT_STATE.md` final state: + +```markdown +# Current Workflow State +Last updated: 2026-03-19T11:05:00Z + +## Active Tasks +(none) + +## Completed Tasks (last 5) + +| ID | Title | Completed At | Artifacts | +|-------|-----------------------------|----------------------|----------------------------------------| +| T-001 | Stripe payments integration | 2026-03-19T11:05:00Z | payments.sql, payments.ts, +4 files | +``` + +--- + +## Summary + +This example demonstrates: + +| Protocol Event | What Happened | +|---|---| +| Task created | Main agent created T-001, reported plan to user | +| `accepted` report | Worker echoed task back, state → `in_progress` | +| `milestone` reports | User saw progress at each step, never wondered "is it still running?" | +| `blocked` report | User was immediately informed of the blocker with full context | +| Blocker resolved | State returned to `in_progress` without user having to chase | +| `done` report | Full artifact list and caveats surfaced to user | +| Main agent review | State only moved to `done` after main agent verified the work | + +No silent disappearances. No mystery. Every state change has evidence. diff --git a/openclaw.plugin.json b/openclaw.plugin.json new file mode 100644 index 0000000..736adb0 --- /dev/null +++ b/openclaw.plugin.json @@ -0,0 +1,27 @@ +{ + "name": "openclaw-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" + ] +}