Task Engine

---

name: task-engine description: "Multi-agent task orchestration engine with state machine tracking. Use when complex multi-step projects need automated monitoring, multi-agent collaboration, and Discord-based progress tracking."

---

Task Engine

Orchestrates multi-step projects across multiple agents (Claude Code, Eva, others) using a state machine with JSON-based persistence. Each task has subtasks dispatched to agents, tracked via heartbeat, and reported through Discord.

CLI Commands

All commands run from the skill root:

cd /home/zeron/.openclaw/workspace/skills/task-engine

All commands support --json for machine-readable output:

{"ok": true, "task_id": "TASK-001", "status": "PLANNING", "message": "Created TASK-001"}

Create a task

python3 scripts/task_engine.py create "Implement feature X" --priority P0 --plan "3 phases: models, API, tests"
python3 scripts/task_engine.py create "Feature Y" --priority P1 --json

View status

python3 scripts/task_engine.py status                    # All active tasks (table)
python3 scripts/task_engine.py status TASK-001           # Detailed single task
python3 scripts/task_engine.py status TASK-001 --json    # Machine-readable
python3 scripts/task_engine.py status --all              # Include terminal tasks

Transition task state

python3 scripts/task_engine.py transition TASK-001 approve --note "Plan approved" --json
python3 scripts/task_engine.py transition TASK-001 block --note "Waiting on API key"
python3 scripts/task_engine.py transition TASK-001 complete --note "All verified" --json

Dispatch subtask to an agent

python3 scripts/task_engine.py dispatch TASK-001 "Implement auth models" \
    --agent claude-code --type dev --json
python3 scripts/task_engine.py dispatch TASK-001 "Run integration tests" \
    --agent eva --type test --deps subtask_01,subtask_02

Dispatching the first subtask auto-transitions APPROVED -> IN_PROGRESS.

Update subtask progress

python3 scripts/task_engine.py subtask TASK-001 subtask_01 start --progress 30 --json
python3 scripts/task_engine.py subtask TASK-001 subtask_01 done --note "Models complete" --json
python3 scripts/task_engine.py subtask TASK-001 subtask_02 fail --note "Schema mismatch" --json

Check tasks (heartbeat integration)

python3 scripts/task_engine.py check              # Check all active tasks (verbose)
python3 scripts/task_engine.py check TASK-001      # Check one task
python3 scripts/task_engine.py check --quiet       # Minimal output for cron
python3 scripts/task_engine.py check --json        # Machine-readable JSON
python3 scripts/task_engine.py check --discord     # Discord-formatted digest

Archive completed task

python3 scripts/task_engine.py archive TASK-001 --json    # Only works on terminal tasks

Auto-dispatch

Auto-dispatch scans subtasks and dispatches ready ones to appropriate agents:

python3 scripts/task_engine.py auto-dispatch TASK-001             # Dispatch ready subtasks
python3 scripts/task_engine.py auto-dispatch TASK-001 --dry-run   # Preview without acting
python3 scripts/task_engine.py auto-dispatch --all                # All active tasks
python3 scripts/task_engine.py auto-dispatch TASK-001 --subtask subtask_02  # Specific subtask
python3 scripts/task_engine.py auto-dispatch TASK-001 --subtask subtask_01 --show-context  # View dispatch context

Output is always JSON with dispatches and skipped arrays.

Notify (Discord formatting)

Generate Discord-formatted notification messages:

python3 scripts/task_engine.py notify digest               # Full heartbeat digest
python3 scripts/task_engine.py notify TASK-001 created     # Task creation message
python3 scripts/task_engine.py notify TASK-001 status      # Status update with progress
python3 scripts/task_engine.py notify TASK-001 transition   # Last transition
python3 scripts/task_engine.py notify TASK-001 completed    # Completion summary
python3 scripts/task_engine.py notify TASK-001 alert --type stuck --subtask-id subtask_01

Rebuild index (recovery)

Reconstruct index.json from task directories if it gets corrupted:

python3 scripts/task_engine.py rebuild-index         # Scan and rebuild
python3 scripts/task_engine.py rebuild-index --json  # Machine-readable output

Heartbeat Integration

Add step 4.3 to the heartbeat's cmd_beat() function, after the ongoing.json check:

# 4.3 Task Engine check
logger.info("[4.3/8] Task Engine check")
try:
    import sys
    sys.path.insert(0, str(Path("/home/zeron/.openclaw/workspace/skills/task-engine/scripts")))
    from engine.checker import check_all_tasks
    te_result = check_all_tasks()
    if te_result.get("alerts"):
        alerts.extend(te_result["alerts"])
        all_ok = False
    if te_result.get("summary"):
        logger.info("  Tasks: %s", te_result["summary"])
except ImportError:
    logger.debug("  Task engine not installed, skipping")
except Exception as e:
    logger.warning("  Task engine check failed: %s", e)

The check is cheap (~300-500 tokens per heartbeat for 1-3 active tasks). It reads index.json first, then only loads task/subtask files for active tasks.

State Machine

PLANNING ──approve──> APPROVED ──start──> IN_PROGRESS ──test──> TESTING ──review──> REVIEW ──complete──> COMPLETED
    │                                         │  │                 │  │                │
    │reject                              block│  │fail        reopen│  │fail       reopen│ fail
    v                                         v  v                 v  v                v   v
 REJECTED                                BLOCKED FAILED      IN_PROGRESS FAILED   IN_PROGRESS FAILED
                                           │
                                      unblock│
                                           v
                                      IN_PROGRESS

Terminal states: COMPLETED, FAILED, REJECTED.

See references/state-transitions.md for the full transition table.

Subtask states

PENDING -> ASSIGNED -> IN_PROGRESS -> DONE
                │            │
                │block       │fail / block
                v            v
             BLOCKED      FAILED / BLOCKED

Auto-transitions (checked by heartbeat)

| Condition | Action | |-----------|--------| | All type: dev subtasks DONE | Task -> TESTING | | All type: test subtasks DONE | Task -> REVIEW | | First subtask dispatched | Task APPROVED -> IN_PROGRESS | | Any subtask FAILED | Alert for human intervention | | Subtask stuck 3+ heartbeats | Alert via Discord | | Task past ETA | Alert as overdue |

Discord Formatting

The discord_formatter.py module generates formatted messages for Discord notifications. All formatting is pure string generation — no API calls.

Available formats:

Task created: New task announcement with priority and plan

Status update: Progress bars and subtask tree

Transition: State change with emoji indicators

Alert: Urgent stuck/overdue/failed alerts with human ping

Completion summary: Final report with subtask results

Heartbeat digest: Full summary of all active tasks

Progress bars render as: [████░░░░░░] 40%

Agent Capabilities

| Agent | Key | Best For | Max Parallel | |-------|-----|----------|--------------| | Claude Code | claude-code | Dev, refactor, debug, docs | 3 | | Eva | eva | Test, validate, system-ops | 1 |

Agent selection priority: 1. Preferred agent (if specified and capable) 2. Match by preferred_types 3. Match by broader capabilities 4. Fallback to Eva

See references/agent-capabilities.md for full details.

Troubleshooting

Corrupted index.json

python3 scripts/task_engine.py rebuild-index --json

Scans all tasks/TASK-*/task.json files and reconstructs the index. Skips invalid/unreadable files.

Common errors

| Error | Cause | Fix | |-------|-------|-----| | Invalid transition: X + 'event' | Transition not allowed from current state | Check references/state-transitions.md | | Task TASK-XXX not found | Task doesn't exist or was archived | Check tasks/ and tasks/archive/ | | Cannot archive: not terminal | Task must be COMPLETED/FAILED/REJECTED | Transition to terminal state first | | Agent at capacity | Max parallel instances reached | Wait for running subtasks to complete | | Dependency not DONE | Blocked by incomplete subtask | Complete blocking subtask first |

JSON parse errors

The engine handles corrupt JSON files gracefully:

During check: skips bad tasks, logs warning, continues

During rebuild-index: skips unreadable files, reports in output

All CLI commands catch exceptions and return clean error messages (not tracebacks)

Data Location

Task files: /home/zeron/.openclaw/workspace/tasks/TASK-NNN/

Index: /home/zeron/.openclaw/workspace/tasks/index.json

Archive: /home/zeron/.openclaw/workspace/tasks/archive/

Config: /home/zeron/.openclaw/workspace/skills/task-engine/config/settings.yaml

Agent reference: /home/zeron/.openclaw/workspace/skills/task-engine/references/agent-capabilities.md

State transitions: /home/zeron/.openclaw/workspace/skills/task-engine/references/state-transitions.md

Corrupted index.json

python3 scripts/task_engine.py rebuild-index --json

Scans all tasks/TASK-*/task.json files and reconstructs the index. Skips invalid/unreadable files.

Common errors

| Error | Cause | Fix | |-------|-------|-----| | Invalid transition: X + 'event' | Transition not allowed from current state | Check references/state-transitions.md | | Task TASK-XXX not found | Task doesn't exist or was archived | Check tasks/ and tasks/archive/ | | Cannot archive: not terminal | Task must be COMPLETED/FAILED/REJECTED | Transition to terminal state first | | Agent at capacity | Max parallel instances reached | Wait for running subtasks to complete | | Dependency not DONE | Blocked by incomplete subtask | Complete blocking subtask first |

JSON parse errors

The engine handles corrupt JSON files gracefully:

During check: skips bad tasks, logs warning, continues

During rebuild-index: skips unreadable files, reports in output

All CLI commands catch exceptions and return clean error messages (not tracebacks)