Feature: OpenClaw skill for sub-agent task tracking via AgentFlow

[Tweakzx]

Problem

When the main OpenClaw agent spawns sub-agents (Codex, Claude Code, etc.) to work on tasks, the human operator has no visibility into what sub-agents are doing. There is no dashboard, no real-time status, no structured history.

AgentFlow already has a Web Console with a Stage Board, task list, run history, and audit trail. The missing piece is a bridge that connects OpenClaw sub-agent lifecycle events to AgentFlow.

Suggested Solution

Create an OpenClaw skill (e.g., skill-agentflow-tracking) that instructs the main agent to:

Task Creation

When spawning a sub-agent, create a corresponding task in AgentFlow:

POST /api/tasks  →  { project, title, description, priority, impact, effort, source, external_id }

Status Transitions

Map sub-agent lifecycle to AgentFlow task statuses:

Sub-agent event	AgentFlow status	Note
spawn	in_progress	Agent started working
sub-agent reports progress	(heartbeat)	Extend lease
sub-agent completes successfully	pr_ready or pr_open	Based on whether a PR was created
sub-agent fails	blocked	With error details
PR merged	merged	Via GitHub webhook or manual move

Run Recording

For each sub-agent execution, create a run record:

POST /api/task/<id>/run  →  { adapter: "openclaw-codex", agent: "codex-worker-1" }

Skill Content (SKILL.md)

# AgentFlow Task Tracking Skill

When spawning sub-agents for coding tasks, track them in AgentFlow.

## Setup
- AgentFlow server must be running: `agentflow serve --port 8787`
- Default project: `openclaw-tasks`
- API base: `http://127.0.0.1:8787`

## Workflow
1. Before spawning a sub-agent, create a task via POST /api/tasks
2. After spawning, move task to `in_progress` via POST /api/task/<id>/move
3. When sub-agent completes, update task status accordingly
4. For batch operations, create all tasks first, then spawn agents

## API Reference
- Create task: POST /api/tasks
- Move task: POST /api/task/<id>/move { to_status, note }
- View board: GET /api/flow?project=openclaw-tasks
- Task detail: GET /api/task/<id>
- Audit trail: GET /api/audit?project=openclaw-tasks

Value

• Human visibility: Open http://localhost:8787 to see all sub-agent tasks on the Stage Board
• Structured history: Every sub-agent run is recorded with timing, agent name, and result
• Audit trail: Full status transition history for compliance and debugging
• Multi-agent coordination: See all active workers at a glance via the Web Console

Depends on

• Feature: Add POST /api/tasks endpoint for programmatic task creation #5 (POST /api/tasks endpoint) — required for programmatic task creation

[Tweakzx]

Triage decision (2026-03-31): Keep, P2.

Why worth doing:

• Skill/runbook integration improves consistency of human+agent operations.
• Works best after API surface and execution path are stable.

Recommended dependency order:

• After Feature: Add POST /api/tasks endpoint for programmatic task creation #5/Enhancement: OpenClaw plugin — expose full task CRUD via tools/commands #7 API access and Feature: Implement a real agent adapter (e.g. OpenClaw / Codex / Claude Code) #1/Enhancement: OpenClaw plugin — support real adapter execution (not just mock) #10 execution foundation are stable.

[Tweakzx]

Implementation update (2026-03-31): tracking-oriented bundle skills were updated to align with AgentFlow task tracking workflow.

Delivered:

• Updated bundle skills for Codex / Claude / Cursor:
  • switched examples to real adapter path (--adapter openclaw)
  • added task inspection/audit commands (task-detail, audit)
  • added sub-agent progress heartbeat examples via POST /api/task/<id>/progress

Effect:

• Main agent runbooks can now standardize:
  • create/execute task
  • emit progress heartbeats while running
  • inspect run/audit traces after completion

This addresses the practical "skill-level bridge" portion of this issue.

[m13v]

the sub-agent visibility problem is real. we run parallel agents constantly and the biggest pain point isn't knowing whether they succeeded or failed, its understanding what went wrong when they fail. your AgentFlow status transitions cover the lifecycle well but for debugging the "blocked" state you need more than error text. we added lightweight screen recording to each agent session so when a sub-agent gets stuck, you can scrub through exactly what it was doing. the run recording endpoint would be a natural place to store a video URL alongside the structured run data. even at 3-5 fps the visual context is way more diagnostic than any amount of structured logging.

[m13v]

the capture service that handles per-session screen recording with hardware encoding, could integrate with your run recording endpoint: https://github.com/m13v/macos-session-replay/blob/main/Sources/SessionReplay/ScreenCaptureService.swift